Cette page explique comment définir un projet de quota pour vos API basées sur un client. Pour en savoir plus sur le projet de quota, comment définir l'API de quota et comment le projet de quota est déterminé, consultez la page À propos du projet de quota.
Lorsque vous envoyez une requête à une API basée sur un client, si un projet de quota ne peut pas être identifié, la requête échoue.
Le projet de quota peut être défini de plusieurs manières. Le projet sera validé en cochant les options suivantes. L'ordre indiqué est l'ordre de priorité.
- Projet de quota défini dans l'environnement ou dans la requête.
- Si vous utilisez une clé API pour fournir des identifiants pour une requête, le projet associé à cette clé est utilisé comme projet de quota.
- Si vous utilisez Google Cloud CLI pour obtenir votre jeton d'accès et que vous vous êtes authentifié auprès de gcloud CLI avec vos identifiants utilisateur, le projet partagé gcloud CLI est parfois utilisé comme projet de quota. Toutes les API basées sur le client ne relèvent pas du projet partagé.
- Si le compte principal de l'appel d'API est un compte de service, y compris par emprunt d'identité, le projet associé au compte de service est utilisé comme projet de quota.
- Si le compte principal de l'API est un utilisateur de fédération des identités des employés, le projet utilisateur de pools d'employés est utilisé comme projet de quota.
Si aucune des vérifications précédentes ne génère de projet de quota, la requête échoue.
Il existe plusieurs façons de définir des projets de quotas. Si le projet de quota est spécifié par plusieurs méthodes, la priorité suivante est appliquée:
- De manière automatisée
- Variable d'environnement
- Identifiants utilisés pour authentifier la requête
Définir le projet de quota de manière automatisée
Vous pouvez définir explicitement le projet de quota dans votre application. Cette méthode remplace toutes les autres définitions. Le compte principal utilisé pour authentifier la requête doit disposer de l'autorisation requise sur le projet de quota spécifié.
La manière dont vous définissez le projet de quota de manière automatisée varie selon que vous utilisez une bibliothèque cliente, gcloud CLI ou une requête API REST.
Bibliothèque cliente
Vous pouvez définir la valeur du projet de quota à l'aide des options client lorsque vous créez le client. Cette méthode est adaptée si vous souhaitez contrôler la valeur de votre projet de quota depuis votre application, quel que soit l'environnement dans lequel elle s'exécute.
Pour en savoir plus sur la mise en œuvre des options client, consultez la documentation de votre bibliothèque cliente.
gcloud CLI
Vous pouvez définir le projet de quota pour toutes les commandes gcloud CLI en utilisant la propriété billing/quota_project dans votre configuration gcloud CLI. Vous pouvez également définir le projet de quota pour une commande spécifique à l'aide de l'option --billing-project, qui est prioritaire sur la propriété de configuration.
Pour en savoir plus sur les configurations de la CLI gcloud, consultez la page de référence de gcloud config. Pour en savoir plus sur l'option --billing-project, consultez la documentation de référence du SDK Google Cloud.
Requête REST
Vous pouvez spécifier le projet de quota dans une requête REST à l'aide de l'en-tête x-goog-user-project.
Le compte principal qui effectue la requête doit disposer des autorisations requises sur le projet de quota.
Pour en savoir plus et obtenir un exemple de code, consultez la section Définir le projet de quota avec une requête REST.
Définir le projet de quota à l'aide d'une variable d'environnement
Les bibliothèques clientes pour certains langages permettent de définir le projet de quota à l'aide d'une variable d'environnement. Cette approche peut être utile si vous souhaitez définir le projet de quota différemment dans des shells différents ou pour remplacer le projet de quota associé à l'identifiant. Le compte principal pour toute requête doit disposer des autorisations requises sur le projet de quota spécifié par la variable d'environnement.
La variable d'environnement dépend du langage :
| Langage | Variable d'environnement |
|---|---|
| C++ |
|
| C# |
|
| Go |
|
| Java |
|
| Node.js |
|
| Python |
|
| PHP |
|
| Ruby | Non disponible |
Définir le projet de quota à l'aide des identifiants d'authentification
Si le projet de quota n'est pas spécifié, les bibliothèques d'authentification tentent de le déterminer à partir des identifiants utilisés pour la requête. Ce processus dépend du type d'identifiants utilisés pour authentifier la requête:
- Compte de service : le projet associé au compte de service est utilisé comme projet de quota.
- Identifiants utilisateur : pour un environnement de développement local, les identifiants par défaut de l'application trouvent vos identifiants utilisateur à partir du fichier ADC local. Ce fichier peut également spécifier un projet de quota. Si le projet est défini dans votre configuration Google Cloud CLI et que vous disposez des autorisations requises sur ce projet, le projet de quota est défini par défaut lorsque vous créez le fichier ADC local. Vous pouvez également définir le projet de quota ADC à l'aide de la commande
auth application-default set-quota-project. - Clés API : lorsque vous utilisez une clé API pour fournir des identifiants pour une requête, le projet associé à la clé API est utilisé comme projet de quota.
Autorisations requises pour définir et utiliser le projet de quota
Pour obtenir l'autorisation dont vous avez besoin pour définir un projet comme projet de quota, ou pour utiliser ce projet de quota dans une requête, demandez à votre administrateur de vous accorder le rôle IAM Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer) sur le projet.
Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.
Ce rôle prédéfini contient l'autorisation serviceusage.services.use, qui est nécessaire pour définir un projet en tant que projet de quota ou utiliser ce projet de quota dans une requête.
Vous pouvez également obtenir cette autorisation avec des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous utilisez un projet que vous avez créé comme projet de quota, vous disposez des autorisations nécessaires.
Pour en savoir plus sur les autorisations, consultez la page Autorisations de quota.
Définir l'utilisateur du quota
Certaines API limitent également le nombre de requêtes par utilisateur, ce qui diffère des quotas par projet décrits dans les sections précédentes de cette page.
Par défaut, le système utilise le compte principal authentifié. En l'absence de compte principal authentifié, le système utilise l'adresse IP client.
Si vous devez remplacer l'utilisateur du quota, vous pouvez définir le paramètre quotaUser via les Paramètres système de l'API Cloud. Si vous spécifiez un paramètre quotaUser ou X-Goog-Quota-User, une clé API valide comportant des restrictions d'adresse IP doit être utilisée pour identifier le projet de quota. Sinon, le paramètre quotaUser est ignoré.
Pour en savoir plus sur les paramètres système de l'API Cloud et leurs définitions, consultez le tableau des définitions des paramètres système.
Étapes suivantes
- À propos du projet de quota
- Apprenez-en plus sur les identifiants par défaut de l'application.
- Obtenez plus d'informations sur l'authentification
- Comprendre les quotas