Impostare il progetto di quota

Questa pagina descrive come impostare un progetto di quota per le API basate su client. Per informazioni sul progetto quota, su come impostare l'API quota e su come viene determinato il progetto quota, consulta Informazioni sul progetto di quota.

Quando effettui una richiesta a un'API basata su client, se non è possibile identificare un progetto di quota, la richiesta non va a buon fine.

Il progetto di quota può essere impostato in più modi. Il progetto verrà verificato selezionando le opzioni seguenti. L'ordine elencato è la precedenza.

  • Il progetto di quota impostato nell'ambiente o nella richiesta.
  • Se utilizzi una chiave API per fornire le credenziali per una richiesta, il progetto associato alla chiave API viene utilizzato come progetto di quota.
  • Se utilizzi Google Cloud CLI per ottenere il token di accesso e hai eseguito l'autenticazione a gcloud CLI con le tue credenziali utente, a volte il progetto condiviso gcloud CLI viene utilizzato come progetto di quota. Non tutte le API basate su client fanno affidamento sul progetto condiviso.
  • Se l'entità per la chiamata API è un account di servizio, anche tramite impersonificazione, il progetto associato all'account di servizio viene utilizzato come progetto di quota.
  • Se l'entità per l'API è un utente della federazione delle identità per la forza lavoro, il progetto utente dei pool di forza lavoro viene utilizzato come progetto di quota.

Se nessuno dei controlli precedenti restituisce un progetto di quota, la richiesta non va a buon fine.

Esistono diversi modi per impostare i progetti di quota. Se il progetto di quota viene specificato da più metodi, viene applicata la seguente precedenza:

  1. In modo programmatico
  2. Variabile di ambiente
  3. Credenziali utilizzate per autenticare la richiesta

Imposta il progetto quota in modo programmatico

Puoi impostare esplicitamente il progetto di quota nella tua applicazione. Questo metodo sostituisce tutte le altre definizioni. L'entità utilizzata per autenticare la richiesta deve avere l'autorizzazione richiesta nel progetto di quota specificato.

La modalità di impostazione programmatica del progetto di quota dipende dal fatto che tu stia utilizzando una libreria client, gcloud CLI o una richiesta API REST.

Libreria client

Puoi impostare il valore del progetto quota utilizzando le opzioni del client quando crei il client. Questo metodo funziona bene se vuoi controllare il valore del progetto di quota dall'applicazione, a prescindere dall'ambiente in cui viene eseguito.

Per ulteriori informazioni sull'implementazione delle opzioni client, consulta la documentazione della libreria client.

Interfaccia a riga di comando gcloud

Puoi impostare il progetto quota per tutti i comandi dell'interfaccia a riga di comando gcloud utilizzando la proprietà billing/quota_project nella configurazione di gcloud CLI. Puoi anche impostare il progetto di quota per un comando specifico utilizzando il flag --billing-project, che ha la precedenza sulla proprietà di configurazione.

Per ulteriori informazioni sulle configurazioni dell'interfaccia a riga di comando di gcloud, consulta la pagina di riferimento di gcloud config. Per ulteriori informazioni sul flag --billing-project, consulta il riferimento di Google Cloud SDK.

Richiesta REST

Puoi specificare il progetto di quota in una richiesta REST utilizzando l'intestazione x-goog-user-project. L'entità che effettua la richiesta deve disporre delle autorizzazioni necessarie per il progetto di quota.

Per maggiori informazioni e codice campione, consulta Impostare il progetto di quota con una richiesta REST.

Imposta il progetto di quota utilizzando una variabile di ambiente

Le librerie client per alcuni linguaggi supportano l'impostazione del progetto di quota utilizzando una variabile di ambiente. Questo approccio può essere utile se vuoi impostare il progetto di quota in modo diverso nelle diverse shell o per eseguire l'override del progetto di quota associato alla credenziale. L'entità per qualsiasi richiesta deve avere le autorizzazioni necessarie per il progetto di quota specificato dalla variabile di ambiente.

La variabile di ambiente dipende dal linguaggio:

Lingua Variabile di ambiente
C++

GOOGLE_CLOUD_CPP_USER_PROJECT

C#

GOOGLE_CLOUD_QUOTA_PROJECT

Go

GOOGLE_CLOUD_QUOTA_PROJECT

Java

GOOGLE_CLOUD_QUOTA_PROJECT

Node.js

GOOGLE_CLOUD_QUOTA_PROJECT

Python

GOOGLE_CLOUD_QUOTA_PROJECT

PHP

GOOGLE_CLOUD_QUOTA_PROJECT

Ruby Non disponibile

Imposta il progetto quota utilizzando le credenziali di autenticazione

Se il progetto di quota non è specificato, le librerie di autenticazione tentano di determinarlo dalle credenziali utilizzate per la richiesta. Questo processo dipende dal tipo di credenziali utilizzate per autenticare la richiesta:

  • Account di servizio: il progetto associato all'account di servizio viene utilizzato come progetto di quota.
  • Credenziali utente: per un ambiente di sviluppo locale, Credenziali predefinite dell'applicazione trova le credenziali utente dal file ADC locale. Questo file può anche specificare un progetto di quota. Se il progetto è impostato nella configurazione dell'interfaccia a riga di comando di Google Cloud e disponi delle autorizzazioni necessarie per il progetto, il progetto di quota viene impostato per impostazione predefinita quando crei il file ADC locale. Puoi anche impostare il progetto di quota ADC utilizzando il comando auth application-default set-quota-project.
  • Chiavi API: quando utilizzi una chiave API per fornire le credenziali per una richiesta, il progetto associato alla chiave API viene utilizzato come progetto di quota.

Autorizzazioni necessarie per impostare e utilizzare il progetto di quota

Per ottenere l'autorizzazione necessaria per impostare un progetto come progetto di quota o utilizzare il progetto di quota in una richiesta, chiedi all'amministratore di concederti il ruolo IAM Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) del progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questo ruolo predefinito contiene l'autorizzazione serviceusage.services.use, necessaria per impostare un progetto come progetto di quota o per utilizzarlo in una richiesta.

Potresti riuscire a ottenere questa autorizzazione anche con i ruoli personalizzati o altri ruoli predefiniti.

Se utilizzi un progetto che hai creato come progetto di quota, disponi delle autorizzazioni necessarie.

Per ulteriori informazioni sulle autorizzazioni, consulta Autorizzazioni di condivisione.

Imposta l'utente della quota

Alcune API limitano anche il numero di richieste per utente, che è diverso dalle quote per progetto descritte nelle sezioni precedenti di questa pagina.

Per impostazione predefinita, il sistema utilizza l'entità autenticata. Se non esiste un'entità autenticata, il sistema utilizza l'indirizzo IP del client.

Se devi eseguire l'override dell'utente quota, puoi impostare il parametro quotaUser tramite i Parametri di sistema dell'API Cloud. Se specifichi un valore quotaUser o X-Goog-Quota-User, devi utilizzare una chiave API valida con restrizioni relative agli indirizzi IP per identificare il progetto di quota. In caso contrario, il parametro quotaUser viene ignorato.

Per scoprire di più sui parametri di sistema dell'API Cloud e sulle relative definizioni, consulta la tabella delle definizioni dei parametri di sistema.

Passaggi successivi