La piattaforma API di Google fornisce un insieme di funzionalità comuni a tutte le API di Google create utilizzando la piattaforma. Per utilizzare e controllare questa funzionalità, la piattaforma predefinisce un insieme speciale di parametri di richiesta chiamati parametri di sistema. Questi parametri sono disponibili in tutte le API REST e gRPC di Google. Un parametro di sistema può essere specificato utilizzando un parametro di query HTTP o un'intestazione HTTP. Per le API gRPC di Google, sono supportate solo le intestazioni HTTP.
La maggior parte degli utenti non avrà bisogno di utilizzare direttamente questi parametri. Tuttavia, vengono spesso utilizzate dalle librerie client fornite da Google. Se devi scrivere codice personalizzato per accedere direttamente alle API di Google, i parametri di sistema possono essere utili in casi come il controllo della stampa in formato JSON o la specifica delle chiavi API.
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 parametro di sistema $foo, viene
inviato come ?$foo=xxx nell'URL o ?%24foo=xxx se codificato in URL. Per i dettagli, consulta la
tabella di seguito.
Mappatura gRPC
Per le richieste gRPC, i parametri di sistema vengono inviati come intestazioni di richiesta HTTP con chiavi in minuscolo. Per i dettagli, vedi la tabella seguente.
Definizioni
Nella tabella seguente sono elencati tutti i parametri di sistema e le relative definizioni.
| Parametro di query dell'URL | Intestazione HTTP/gRPC | Descrizione |
|---|---|---|
Authorization |
Credenziali di autenticazione. Per maggiori dettagli, consulta Panoramica dell'autenticazione. | |
$alt,alt |
Formato di risposta alternativo. I valori supportati sono json (predefinito), media, proto, sse (stream JSON). |
|
$apiVersion |
X-Goog-Api-Version |
La versione dell'API da utilizzare. Non tutte le API supportano questo parametro: controlla la documentazione dell'API prima di utilizzarlo. |
$.xgafv |
Formato dell'errore JSON. I valori supportati sono 1 e 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 filtraggio delle risposte. Se vuoto, tutti i campi devono essere restituiti, se non diversamente documentato. |
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, visita la pagina https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Riservato per evitare di inserire password negli URL. | |
$prettyPrint,prettyPrint |
Stampa in formato leggibile della risposta JSON. I valori supportati sono true (predefinito) e false. |
|
quotaUser |
X-Goog-Quota-User |
Uno pseudo identificatore utente per l'addebito delle quote per utente. Se non specificato, viene utilizzato il principal autenticato. Se non è presente un principal autenticato, verrà utilizzato l'indirizzo IP client. Se specificata, deve essere utilizzata 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 di 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 separato da spazi di stringhe NAME "/" SEMVER, dove NAME deve contenere solo lettere minuscole, cifre e "-", mentre 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 la richiesta, che deve essere registrato nell'audit logging. Un motivo di esempio potrebbe essere un numero di ticket di richiesta di assistenza. Per i log di controllo, i caratteri nel motivo determinano se il motivo è 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 sono codificati in base64. | |
$userProject |
X-Goog-User-Project |
Un progetto specificato dal chiamante ai fini 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 completamento dell'elaborazione della richiesta da parte del server. 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 all'interno di questo header dipendono dal servizio e dal metodo API Google individuali chiamati. Non esiste un unico insieme universale di parametri per questa intestazione. Consulta sempre la documentazione dell'API specifica con cui interagisci per determinare quali parametri sono supportati o richiesti. 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 Pubblicazione della documentazione per
quotaUser. - 2020-07 parametri di ricerca OAuth 2.0 ritirati.
- 2019-10 È stato introdotto il parametro di sistema
X-Server-Timeout. - 2017-10 È stato introdotto il parametro di sistema
X-Goog-User-Project.