La piattaforma API di Google definisce i parametri di sistema per controllare le funzionalità comuni tra le API REST e gRPC, come chiavi API, maschere dei campi di risposta, attribuzione della quota e formattazione JSON. A seconda del protocollo, i parametri di sistema vengono passati a un servizio come parametri di ricerca URL o intestazioni HTTP. Puoi specificare questi parametri direttamente quando scrivi codice personalizzato, anche se strumenti come le librerie client fornite da Google ne gestiscono molti automaticamente.
Mappatura HTTP
Per le richieste HTTP, i parametri di sistema vengono inviati come parametri di ricerca URL o intestazioni delle richieste HTTP. Ad esempio, se hai un parametrio di sistema $foo, viene
inviato come ?$foo=xxx nell'URL o ?%24foo=xxx se codificato nell'URL. Per i dettagli, vedi la tabella seguente.
Mappatura gRPC
Per le richieste gRPC, i parametri di sistema vengono inviati come intestazioni delle richieste HTTP con chiavi in minuscolo. Per i dettagli, vedi la tabella seguente.
Definizioni
La tabella seguente elenca tutti i parametri di sistema e le relative definizioni.
| Parametro di query URL | Intestazione HTTP/gRPC | Descrizione |
|---|---|---|
Authorization |
Credenziali di autenticazione. Per i dettagli, consulta Panoramica dell'autenticazione. | |
$alt,alt |
Formato della risposta alternativo. I valori supportati sono json (predefinito), media, proto, sse (stream JSON). |
|
$apiVersion |
X-Goog-Api-Version |
La versione API da utilizzare. Non tutte le API supportano questo parametro: controlla la documentazione dell'API prima di utilizzarlo. |
$.xgafv |
Formato di errore JSON. I valori supportati sono 1, 2 (predefinito). Il formato di errore 1 deve essere utilizzato solo dalle librerie client delle API di Google. |
|
$callback,callback |
Parametro di callback JSONP. | |
$ct |
Content-Type |
Override dell'intestazione della richiesta HTTP Content-Type. |
$fields,fields |
X-Goog-FieldMask |
FieldMask utilizzato per il filtro delle risposte. Se è vuoto, tutti i campi devono essere restituiti, se non diversamente indicato nella documentazione. |
X-HTTP-Method-Override |
Il metodo HTTP previsto per la richiesta. Alcuni proxy di rete non accettano tutti i metodi HTTP. | |
$key,key |
X-Goog-Api-Key |
Chiave API di Google. Per i dettagli, vedi https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Riservato per impedire l'inserimento di password negli URL. | |
$prettyPrint,prettyPrint |
Risposta JSON con stampa di formattazione. I valori supportati sono true (predefinito), false. |
|
quotaUser |
X-Goog-Quota-User |
Uno pseudo identificatore dell'utente per l'addebito delle quote per utente. Se non specificato, viene utilizzato il principale autenticato. Se non è presente un'entità autenticata, verrà utilizzato l'indirizzo IP client. Se specificato, è necessario utilizzare una chiave API valida con limitazioni del servizio per identificare il progetto di quota. In caso contrario, questo parametro viene ignorato. |
$outputDefaults |
Forza l'output dei valori predefiniti del proto per le risposte JSON. | |
$unique |
Parametro di query univoco per disattivare la memorizzazione nella cache delle richieste. | |
X-Goog-Api-Client |
Identificazione del client API. Il valore è un elenco di stringhe NAME "/" SEMVER separate da spazi, dove NAME deve contenere solo lettere minuscole, cifre e "-", e SEMVER deve essere una stringa di versione semantica. Ad esempio: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0. |
|
X-Goog-Request-Reason |
Contiene un motivo per effettuare la richiesta, che deve essere registrato nell'audit log. Un esempio di motivo potrebbe essere un numero di ticket di assistenza. Per gli audit log, i caratteri del motivo determinano se il motivo viene codificato in base64 prima di essere allegato alla voce di log. I motivi che includono solo lettere, cifre e spazi vengono conservati in testo normale. I motivi che includono altri caratteri vengono codificati in base64. | |
$userProject |
X-Goog-User-Project |
Un progetto specificato dal chiamante per scopi di quota e fatturazione. Il chiamante deve disporre dell'autorizzazione serviceusage.services.use per il progetto. |
X-Server-Timeout |
Timeout (in secondi, valore float) per il server per completare l'elaborazione della richiesta. Questo parametro di sistema si applica solo alle API REST per le quali il timeout lato client non è applicabile. | |
x-goog-request-params |
Passaggio di parametri aggiuntivi per le richieste gRPC. Il valore deve essere codificato come stringa di query URL (ad es. key1=value1&key2=value2).Le chiavi e i valori specifici supportati in questa intestazione dipendono dal singolo servizio e metodo dell'API di Google chiamati. Non esiste un insieme di parametri unico e universale per questa intestazione. Consulta sempre la documentazione dell'API specifica con cui interagisci per determinare quali parametri sono supportati o obbligatori. Gli utilizzi comuni includono:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar |
Log delle modifiche
- 2026-10 Documentazione pubblicata per
X-Goog-Api-Version. - 2026-06 Documentazione aggiornata per
x-goog-request-params. - 2021-11 Documentazione pubblicata per
x-goog-request-params. - 2021-02 Documentazione pubblicata per
quotaUser. - 2020-07 parametri di ricerca OAuth 2.0 deprecati.
- 2019-10 Parametro di sistema
X-Server-Timeoutintrodotto. - 2017-10 Parametro di sistema
X-Goog-User-Projectintrodotto.