Questa pagina descrive come impostare un progetto di quota per le tue API basate su client. Per informazioni su cosa sia il progetto quota, come impostare l'API quota e come viene determinato il progetto quota, consulta Informazioni sul progetto quota.
Le richieste possono non andare a buon fine se effettui una richiesta a un'API basata sul client e il progetto di quota non può essere identificato. Il progetto di quota può essere impostato in diversi modi e viene verificato controllando le seguenti opzioni. Vengono visualizzati nell'ordine di precedenza:
Specificato nella richiesta: il progetto di quota specificato nella richiesta. Quando utilizzi le librerie client, puoi utilizzare anche le variabili di ambiente nelle tue richieste.
Chiave API: se utilizzi una chiave API per fornire le credenziali per una richiesta, il progetto associato alla chiave API viene utilizzato come progetto di quota.
Credenziali Google Cloud CLI: se utilizzi gcloud 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 quota. Tuttavia, non tutte le API basate sul client eseguono il failover sul progetto condiviso.
Service account: se il principal per la chiamata API è un service account, anche tramite rappresentazione, il progetto associato al service account viene utilizzato come progetto quota.
Federazione delle identità per la forza lavoro: se il principal 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 quota.
Se nessuno dei controlli precedenti produce 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 con più di un metodo, viene applicata la seguente precedenza:
- In modo programmatico
- Variabile di ambiente
- Credenziali utilizzate per autenticare la richiesta
Impostare il progetto di 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 disporre dell'autorizzazione richiesta per il progetto di quota specificato.
Il modo in cui imposti il progetto di quota in modo programmatico dipende dal fatto che tu stia utilizzando una libreria client, gcloud CLI o una richiesta API REST.
Libreria client
Puoi impostare il valore per il progetto di quota utilizzando le opzioni client quando crei il client. Questo metodo funziona bene se vuoi controllare il valore del progetto di quota dalla tua applicazione, indipendentemente dall'ambiente in cui viene eseguita.
Per ulteriori informazioni sull'implementazione delle opzioni client, consulta la documentazione della libreria client.
Interfaccia a riga di comando gcloud
Puoi impostare il progetto di quota per tutti i comandi gcloud CLI 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 della CLI gcloud, consulta la pagina di riferimento di gcloud config. Per ulteriori informazioni sul flag --billing-project,
consulta il riferimento per 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 richieste per il progetto di quota.
Per ulteriori informazioni e codice campione, consulta Impostare il progetto di quota con una richiesta REST.
Imposta il progetto 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 in shell diverse o per eseguire l'override del progetto di quota associato alla credenziale. Il principal di qualsiasi richiesta deve disporre delle autorizzazioni richieste per il progetto di quota specificato dalla variabile di ambiente.
La variabile di ambiente dipende dalla lingua:
| Lingua | Variabile di ambiente |
|---|---|
| C++ |
|
| C# |
|
| Vai |
|
| Java |
|
| Node.js |
|
| Python |
|
| PHP |
|
| Ruby | Non disponibile |
Imposta il progetto di 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. Questa procedura dipende dal tipo di credenziali utilizzate per autenticare la richiesta:
- Service account: il progetto associato al account di servizio viene utilizzato come progetto quota.
- Credenziali utente: per un ambiente di sviluppo locale,
le credenziali predefinite dell'applicazione
trovano le credenziali utente nel file ADC locale. Questo file può anche specificare
un progetto di quota. Se hai impostato il progetto nella configurazione di Google Cloud CLI e disponi delle autorizzazioni richieste per quel progetto, il progetto 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 richieste per impostare e utilizzare il progetto quota
Per ottenere l'autorizzazione necessaria per impostare un progetto come progetto quota o utilizzare quel progetto quota in una richiesta, chiedi all'amministratore di concederti il ruolo IAM Consumer Service Usage (roles/serviceusage.serviceUsageConsumer) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene l'autorizzazione
serviceusage.services.use
necessaria per
impostare un progetto come progetto quota o utilizzare quel progetto quota in una richiesta.
Potresti anche ottenere questa autorizzazione con 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, vedi Autorizzazioni per le quote.
Imposta l'utente quota
Alcune API limitano anche il numero di richieste per utente, il che è diverso dalle quote per progetto descritte nelle sezioni precedenti di questa pagina.
Per impostazione predefinita, il sistema utilizza l'entità autenticata. Se non è presente un principal autenticato, il sistema utilizza l'indirizzo IP client.
Se devi sostituire l'utente quota, puoi impostare il parametro quotaUser
tramite i parametri di sistema dell'API Cloud. Se specifichi un quotaUser o un X-Goog-Quota-User, devi utilizzare una chiave API valida con restrizioni dell'indirizzo IP per identificare il progetto di quota. In caso contrario, il
parametro quotaUser viene ignorato.
Per saperne di più sui parametri di sistema dell'API Cloud e sulle relative definizioni, consulta la tabella delle definizioni dei parametri di sistema.
Passaggi successivi
- Informazioni sul progetto quota
- Scopri di più sulle credenziali predefinite dell'applicazione.
- Scopri di più sull'autenticazione.
- Informazioni sulle quote