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 definisce preventivamente un set speciale di parametri della richiesta denominati parametri di sistema. Questi parametri sono disponibili in tutte le API REST Google e le API gRPC. 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 dovrà utilizzare questi parametri direttamente. Tuttavia, sono spesso utilizzati dalle librerie client fornite da Google. Se hai bisogno di scrivere codice personalizzato per accedere direttamente alle API di Google, i parametri di sistema possono essere utili in casi come il controllo della stampa JSON di dati o la specifica di chiavi API.
Mappatura HTTP
Per le richieste HTTP, i parametri di sistema vengono inviati come parametri di ricerca dell'URL o intestazioni di richiesta HTTP. Ad esempio, un parametro di sistema $foo viene inviato come ?$foo=xxx nell'URL o ?%24foo=xxx se è codificato nell'URL. Per ulteriori dettagli, consulta la tabella di seguito.
Mappatura gRPC
Per le richieste gRPC, i parametri di sistema vengono inviati come intestazioni delle richieste HTTP con le 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 i dettagli, consulta Panoramica dell'autenticazione. | |
$alt,alt |
Formato di risposta alternativo. I valori supportati sono json (predefinito), media, proto e sse (stream JSON). |
|
$.xgafv |
Formato di errore JSON. I valori supportati sono 1, 2 (valore 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 Content-Type HTTP. |
$fields,fields |
X-Goog-FieldMask |
FieldMask utilizzato per filtrare le risposte. Se è vuoto, devono essere restituiti tutti i campi, a meno che non sia indicato diversamente. |
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 maggiori dettagli, vedi https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Riservato per impedire l'inserimento di password negli URL. | |
$prettyPrint,prettyPrint |
Formatta la risposta JSON. I valori supportati sono true (valore predefinito), false. |
|
quotaUser |
X-Goog-Quota-User |
Uno pseudo identificatore utente per l'addebito delle quote per utente. Se non specificata, viene utilizzata l'entità autenticata. Se non esiste un'entità autenticata, verrà utilizzato l'indirizzo IP del client. Se specificato, per identificare il progetto di quota è necessario utilizzare una chiave API valida con restrizioni del servizio. In caso contrario, questo parametro viene ignorato. |
$outputDefaults |
Forza l'output dei valori predefiniti del protocollo per le risposte JSON. | |
$unique |
Parametro di query univoco per disabilitare la memorizzazione nella cache della richiesta. | |
X-Goog-Api-Client |
Identificazione del client API. Il valore è un elenco separato da spazi di stringhe NAME "/" SEMVER, in cui NAME deve contenere solo lettere minuscole, numeri 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 effettuare la richiesta, che deve essere registrata nell'audit logging. Un esempio potrebbe essere il numero di una richiesta di assistenza. | |
$userProject |
X-Goog-User-Project |
Un progetto specificato dal chiamante ai fini della quota e della fatturazione. Il chiamante deve avere l'autorizzazione serviceusage.services.use per il progetto. |
X-Server-Timeout |
Timeout (in secondi, valore in virgola mobile) 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 nel formato di query dell'URL. Ad esempio: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0. |
Log delle modifiche
- Documentazione pubblicata 2021-11 per
x-goog-request-params. - Documentazione pubblicata 2021-02 per
quotaUser. - Parametri di ricerca OAuth 2.0 obsoleti.
- 2019-10 Introdotto il parametro di sistema
X-Server-Timeout. - 2017-10 Introdotto il parametro di sistema
X-Goog-User-Project.