A plataforma de APIs do Google define parâmetros do sistema para controlar funcionalidades comuns em APIs REST e gRPC, como chaves de API, máscaras de campo de resposta, atribuição de cota e formatação JSON. Dependendo do protocolo, você transmite parâmetros do sistema para um serviço como parâmetros de consulta de URL ou cabeçalhos HTTP. É possível especificar esses parâmetros diretamente ao escrever um código personalizado, embora ferramentas como as bibliotecas de cliente fornecidas pelo Google processem muitos deles automaticamente.
Mapeamento de HTTP
Para solicitações HTTP, os parâmetros do sistema são enviados como parâmetros de consulta de URL ou cabeçalhos de solicitação HTTP. Por exemplo, se você tiver um parâmetro do sistema $foo, ele será enviado como ?$foo=xxx no URL ou ?%24foo=xxx, se codificado por URL. Veja mais detalhes na tabela abaixo.
Mapeamento de gRPC
Para solicitações gRPC, os parâmetros do sistema são enviados como cabeçalhos da solicitação HTTP com chaves em letras minúsculas. Veja mais detalhes na tabela abaixo.
Definições
A tabela a seguir lista todos os parâmetros do sistema e as definições deles.
| Parâmetro de consulta do URL | Cabeçalho HTTP/gRPC | Descrição |
|---|---|---|
Authorization |
Credenciais de autenticação. Consulte a visão geral da autenticação para mais detalhes. | |
$alt,alt |
Formato de resposta alternativo. Os valores compatíveis são json (padrão), media, proto, sse (streams JSON). |
|
$apiVersion |
X-Goog-Api-Version |
A versão da API a ser usada. Nem todas as APIs oferecem suporte a esse parâmetro. Consulte a documentação da API antes de usá-lo. |
$.xgafv |
Formato de erro JSON. Os valores aceitos são 1, 2 (padrão). O formato de erro 1 só deve ser usado por bibliotecas de cliente das APIs do Google. |
|
$callback,callback |
Parâmetro de callback JSONP. | |
$ct |
Content-Type |
Substituição de cabeçalho da solicitação HTTP Content-Type. |
$fields,fields |
X-Goog-FieldMask |
FieldMask usado para filtrar as respostas. Se estiver vazio, todos os campos serão retornados, a menos que seja documentado de outra forma. |
X-HTTP-Method-Override |
O método HTTP pretendido para a solicitação. Alguns proxies de rede não aceitam todos os métodos HTTP. | |
$key,key |
X-Goog-Api-Key |
Indica a chave de API do Google. Para mais detalhes, consulte https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Reservado para evitar a inserção de senhas nos URLs. | |
$prettyPrint,prettyPrint |
Resposta de pretty-print do JSON. Os valores aceitos são true (padrão), false. |
|
quotaUser |
X-Goog-Quota-User |
Um pseudo-identificador de usuário para cobrança de cotas por usuário. Se não for especificado, o principal autenticado será usado. Se não houver um principal autenticado, o endereço IP do cliente será usado. Quando especificado, é preciso usar uma chave de API válida com restrições de serviço para identificar o projeto de cota. Caso contrário, esse parâmetro será ignorado. |
$outputDefaults |
Força a saída de valores proto padrão para respostas do JSON. | |
$unique |
Parâmetro de consulta exclusivo para desativar o armazenamento de consultas em cache. | |
X-Goog-Api-Client |
Identificação do cliente da API. O valor é uma lista de strings NAME "/" SEMVER separadas por espaços, em que NAME deve haver apenas letras minúsculas, dígitos e "-", enquanto SEMVER deve ser uma string de versão semântica. Por exemplo: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0. |
|
X-Goog-Request-Reason |
Contém uma razão para fazer a solicitação, que se destina a ser gravada no registro de auditoria. Um exemplo de razão seria um número de solicitação de histórico de consultas Para registros de auditoria, os caracteres no motivo determinam se ele é codificado em base64 antes de ser anexado à entrada de registro. Os motivos que incluem apenas letras, dígitos e espaços são mantidos em texto simples. Os motivos que incluem outros caracteres são codificados em base64. | |
$userProject |
X-Goog-User-Project |
Um projeto especificado pelo autor da chamada para fins de cotas e faturamento. O autor da chamada precisa ter a permissão serviceusage.services.use no projeto. |
X-Server-Timeout |
Tempo limite (em segundos, valor flutuante) para o servidor concluir o processamento da solicitação. Esse parâmetro do sistema só se aplica a APIs REST para as quais o tempo limite do lado do cliente não é aplicável. | |
x-goog-request-params |
Transmissão de parâmetros adicionais para solicitações gRPC. O valor precisa ser codificado como uma string de consulta de URL (por exemplo, key1=value1&key2=value2).As chaves e os valores específicos com suporte nesse cabeçalho dependem do serviço e do método da API do Google que estão sendo chamados. Não há um conjunto único e universal de parâmetros para esse cabeçalho. Sempre consulte a documentação da API específica com que você está interagindo para determinar quais parâmetros são aceitos ou obrigatórios. Os usos comuns incluem:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar |
Registro de alterações
- 10/2026: publicação da documentação de
X-Goog-Api-Version. - 6/2026: atualização da documentação de
x-goog-request-params. - 11/2021: publicação da documentação de
x-goog-request-params. - 2/2021: publicação da documentação de
quotaUser. - 7/2020: descontinuação dos parâmetros de consulta do OAuth 2.0.
- 10/2019: introdução do parâmetro do sistema
X-Server-Timeout. - 10/2017: introdução do parâmetro do sistema
X-Goog-User-Project.