Parâmetros do sistema

A plataforma de APIs da Google oferece um conjunto de funcionalidades comuns a todas as APIs Google criadas com a plataforma. Para usar e controlar essa funcionalidade, a plataforma predefine um conjunto especial de parâmetros de pedido denominado parâmetros do sistema. Estes parâmetros estão disponíveis em todas as APIs REST da Google e APIs gRPC. Um parâmetro do sistema pode ser especificado através de um parâmetro de consulta HTTP ou de um cabeçalho HTTP. Para as APIs gRPC da Google, apenas são suportados cabeçalhos HTTP.

A maioria dos utilizadores não precisa de usar estes parâmetros diretamente. No entanto, são frequentemente usadas pelas bibliotecas cliente fornecidas pela Google. Se precisar de escrever código personalizado para aceder diretamente às APIs Google, os parâmetros do sistema podem ser úteis em casos como controlar a impressão formatada de JSON ou especificar chaves de API.

Mapeamento HTTP

Para pedidos HTTP, os parâmetros do sistema são enviados como parâmetros de consulta de URL ou cabeçalhos de pedidos HTTP. Por exemplo, se tiver um parâmetro do sistema $foo, é enviado como ?$foo=xxx no URL ou ?%24foo=xxx se for codificado por URL. Consulte a tabela abaixo para ver detalhes.

Nota: o prefixo do nome $ é adicionado para evitar conflitos com os parâmetros de pedido normais.

Mapeamento gRPC

Para pedidos gRPC, os parâmetros do sistema são enviados como cabeçalhos de pedidos HTTP com chaves em letras minúsculas. Consulte a tabela abaixo para ver detalhes.

Definições

A tabela seguinte apresenta todos os parâmetros do sistema e as respetivas definições.

Parâmetro de consulta de URL	Cabeçalho HTTP/gRPC	Descrição
	Authorization	Credenciais de autenticação. Consulte o artigo Vista geral da autenticação para ver detalhes.
$alt, alt		Formato de resposta alternativo. Os valores suportados são json (predefinição), media, proto e sse (streams JSON).
$.xgafv		Formato de erro JSON. Os valores suportados são 1 e 2 (predefinição). O formato de erro 1 só deve ser usado pelas bibliotecas cliente das APIs Google.
$callback, callback		Parâmetro de chamada de retorno JSONP.
$ct	Content-Type	Substituição do cabeçalho do pedido Content-Type de HTTP.
$fields, fields	X-Goog-FieldMask	FieldMask usado para a filtragem de respostas. Se estiver vazio, devem ser devolvidos todos os campos, salvo indicação em contrário.
	X-HTTP-Method-Override	O método HTTP pretendido para o pedido. Alguns proxies de rede não aceitam todos os métodos HTTP.
$key, key	X-Goog-Api-Key	Chave da API Google. Consulte https://cloud.google.com/docs/authentication/api-keys para ver detalhes.
passwd, password		Reservado para impedir a colocação de palavras-passe em URLs.
$prettyPrint, prettyPrint		Imprimir resposta JSON de forma organizada. Os valores suportados são true (predefinição) e false.
quotaUser	X-Goog-Quota-User	Um identificador de pseudoutilizador para a cobrança de quotas por utilizador. Se não for especificado, é usado o principal autenticado. Se não existir um principal autenticado, é usado o endereço IP do cliente. Quando especificado, tem de ser usada uma chave de API válida com restrições de serviço para identificar o projeto de quota. Caso contrário, este parâmetro é ignorado.
$outputDefaults		Forçar a saída de valores predefinidos de proto para respostas JSON.
$unique		Parâmetro de consulta exclusivo para desativar a colocação em cache de pedidos.
	X-Goog-Api-Client	Identificação do cliente API. O valor é uma lista de strings separadas por espaços de NAME "/" SEMVER, em que NAME só deve conter letras minúsculas, dígitos e "-", e 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 um motivo para fazer o pedido, que se destina a ser registado no registo de auditoria. Um exemplo de motivo seria um número do pedido de apoio técnico. Para registos de auditoria, os carateres no motivo determinam se o motivo está codificado em base64 antes de ser anexado à entrada do registo. Os motivos que incluem apenas letras, dígitos e espaços são mantidos em texto simples. Os motivos que incluem outros carateres estão codificados em base64.
$userProject	X-Goog-User-Project	Um projeto especificado pelo autor da chamada para fins de quota e faturação. O autor da chamada tem de ter a autorização serviceusage.services.use no projeto.
	X-Server-Timeout	Tempo limite (em segundos, valor flutuante) para o servidor terminar o processamento do pedido. Este parâmetro do sistema aplica-se apenas às APIs REST para as quais o limite de tempo do lado do cliente não é aplicável.
	x-goog-request-params	Transmitir parâmetros adicionais para pedidos gRPC no formato de consulta de URL. Por exemplo: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0.

Registo de alterações

• 2021-11 Publicação da documentação para x-goog-request-params.
• 2021-02 Publicação da documentação para quotaUser.
• 2020-07 Parâmetros de consulta OAuth 2.0 descontinuados.
• 2019-10 Introdução do parâmetro do sistema X-Server-Timeout.
• 2017-10 Introdução do parâmetro do sistema X-Goog-User-Project.