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 dovrà utilizzare direttamente questi parametri. 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 JSON o la specifica delle chiavi API.
Mapping 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 come URL. Per i 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 lettere minuscole. 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 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 (impostazione predefinita), media, proto, sse (stream JSON). |
|
$.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 filtro 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 maggiori dettagli, visita la pagina https://cloud.google.com/docs/authentication/api-keys. |
passwd,password |
Riservato per impedire l'inserimento di password negli URL. | |
$prettyPrint,prettyPrint |
Stampa in formato leggibile la risposta JSON. I valori supportati sono true (predefinito) e false. |
|
quotaUser |
X-Goog-Quota-User |
Uno pseudo identificatore utente per la fatturazione 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 esempio di motivo 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 non è applicabile il timeout lato client. | |
x-goog-request-params |
Trasmissione 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 specifici 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-06 Aggiornamento della documentazione 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 ritirati.
- 2019-10 È stato introdotto il parametro di sistema
X-Server-Timeout. - 2017-10 È stato introdotto il parametro di sistema
X-Goog-User-Project.