Parâmetros do sistema

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 e sse (fluxos 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 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.