La piattaforma API di Google fornisce un insieme di funzionalità comuni a tutte le API Google costruite 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 questi parametri direttamente. Tuttavia, vengono spesso utilizzati 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 bello JSON o la specifica delle chiavi API.
Mappatura HTTP
Per le richieste HTTP, i parametri di sistema vengono inviati come parametri di query dell'URL o come 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 maggiori dettagli, consulta la tabella riportata 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 la Panoramica dell'autenticazione. | |
$alt,alt |
Formato di risposta alternativo. I valori supportati sono json (predefinito), media, proto, sse (stream JSON). |
|
$.xgafv |
Formato dell'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 |
Sostituzione dell'intestazione della richiesta HTTP Content-Type. |
$fields,fields |
X-Goog-FieldMask |
FieldMask utilizzato per il filtro delle risposte. Se vuoto, devono essere restituiti tutti i campi, a meno che non sia indicato diversamente 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 informazioni dettagliate, visita la pagina https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Riservato per impedire di inserire password negli URL. | |
$prettyPrint,prettyPrint |
Risposta JSON con stampa leggibile. I valori supportati sono true (predefinito), false. |
|
quotaUser |
X-Goog-Quota-User |
Un pseudo identificatore utente per l'addebito delle quote per utente. Se non specificato, viene utilizzato il principale autenticato. Se non è presente un principale autenticato, verrà utilizzato l'indirizzo IP del client. Se specificato, per identificare il progetto quota deve essere utilizzata una chiave API valida con limitazioni del servizio. 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 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 la richiesta, che deve essere registrato nell'audit logging. Un esempio di motivo potrebbe essere il numero di una richiesta di assistenza. | |
$userProject |
X-Goog-User-Project |
Un progetto specificato dall'utente per la quota e la fatturazione. L'utente che chiama 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 |
Passare parametri aggiuntivi per le richieste gRPC in formato di query URL. Ad esempio: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0. |
Log delle modifiche
- 11/2021 Documentazione pubblicata per
x-goog-request-params. - 02/2021 Documentazione pubblicata per
quotaUser. - Luglio 2020 Parametri di query OAuth 2.0 ritirati.
- 10/2019 È stato introdotto il parametro di sistema
X-Server-Timeout. - 10/2017 È stato introdotto il parametro di sistema
X-Goog-User-Project.