A plataforma de APIs do Google oferece um conjunto de funcionalidades em comum para todas as APIs do Google criadas nela. Para usar e controlar essa funcionalidade, a plataforma pré-define um conjunto especial de parâmetros de solicitação chamados parâmetros do sistema. Esses parâmetros estão disponíveis em todas as APIs REST e gRPC do Google. Um parâmetro do sistema pode ser especificado usando um parâmetro de consulta HTTP ou um cabeçalho HTTP. Somente os cabeçalhos HTTP são compatíveis com APIs gRPC do Google.
A maioria dos usuários não precisará usar esses parâmetros diretamente. No entanto, eles costumam ser usados pelas bibliotecas de cliente fornecidas pelo Google. Se você precisar escrever um código personalizado para acessar as APIs do Google diretamente, os parâmetros do sistema poderão ser úteis em casos como o controle de pretty-printing do JSON ou a especificação de chaves de API.
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 da gRPC
Para solicitação gRPC (em inglês), os parâmetros do sistema são enviados como cabeçalhos de 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 aceitos são json (padrão), media, proto, sse (streams JSON). |
|
$.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 o número de um ticket de suporte do Histórico de consultas. | |
$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 se aplica somente às APIs REST em que o tempo limite do cliente não é usado. | |
x-goog-request-params |
Transmite parâmetros adicionais para solicitações gRPC no formato de consulta de URL. Por exemplo: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0. |
Registro de alterações
- 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.