Présentation de l'API Cloud Quotas

L'API Cloud Quotas vous permet d'ajuster de manière automatisée des quotas au niveau du projet et d'automatiser les demandes d'ajustement de quota au niveau du projet. Par exemple, vous pouvez utiliser l'API Cloud Quotas pour :

  • Automatiser les ajustements de quota : vous pouvez utiliser l'API Cloud Quotas pour demander des ajustements de quota en fonction de vos propres critères. Par exemple, pour éviter les erreurs de dépassement de quota, vous pouvez utiliser l'API pour demander une augmentation de quota de manière automatisée lorsque les ressources Compute Engine atteignent 80 % du quota disponible.

  • Réutiliser les configurations de quota entre les projets : l'API Cloud Quotas peut cloner vos configurations de quota d'un projet à un autre. Si vous devez augmenter un ensemble connu de quotas pour chaque nouveau projet Google Cloud, vous pouvez utiliser l'API Cloud Quotas pour automatiser cette opération dans la logique de création de votre projet. Les demandes d'ajustement de quota sont soumises à l'approbation de Google Cloud.

  • Traiter les demandes de quota des clients : si vous êtes un fournisseur SaaS intégré à Google Cloud, vous pouvez recevoir des demandes d'augmentation de quota via un portail destiné aux clients autre que la console Google Cloud. Ces requêtes doivent être transférées à Google Cloud pour traitement. L'API Cloud Quotas peut transférer automatiquement les requêtes des clients.

  • Activer le contrôle des versions de configuration du client : l'API Cloud Quotas est déclarative. Vous pouvez traiter les configurations de quota comme du code et stocker les configurations dans votre propre système contrôlé des versions pour l'historique et le rollback.

Limites

Cloud Quotas présente les limites suivantes :

  • Les ajustements d'augmentation de quota doivent être effectués au niveau du projet et sont soumis à l'approbation de Google Cloud.

  • Vous pouvez demander des ajustements de diminution de quota pour les quotas au niveau du project-, du folder-, et de l'organisation.

  • L'API Cloud Quotas n'accepte que les opérations au niveau du projet. Les opérations au niveau du dossier et de l'organisation ne sont pas prises en charge.

Point de terminaison de service

Un point de terminaison de service est une URL de base qui spécifie l'adresse réseau d'un service d'API. Un service peut posséder plusieurs points de terminaison. Le service d'API Cloud Quotas possède le point de terminaison suivant, et tous les URI sont relatifs :

https://cloudquotas.googleapis.com

Rôles requis

Pour obtenir les autorisations nécessaires pour accéder aux ressources cloudquotas_quotaPreferences et cloudquotas_quotaInfos, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Cloud Quotas (cloudquotas.admin) 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 les autorisations requises pour accéder aux ressources cloudquotas_quotaPreferences et cloudquotas_quotaInfos. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour accéder aux ressources cloudquotas_quotaPreferences et cloudquotas_quotaInfos :

  • cloudquotas.quotas.update
  • cloudquotas.quotas.get
  • monitoring.timeSeries.list
  • resourcemanager.projects.get
  • resourcemanager.projects.list

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Modèle de ressource d'API

Le modèle de ressource de l'API Cloud Quotas se compose de deux ressources : QuotaPreference et QuotaInfo.

Préférence de quota

La ressource QuotaPreference représente vos préférences de quota pour une combinaison de dimension particulière. Utilisez cette ressource pour ajuster les quotas dans vos projets, dossiers ou organisations.

Définir une valeur préférée pour une région

L'exemple suivant montre une ressource QuotaPreference dans une méthode CreateQuotaPreference.

{
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {
        "region": "us-central1"
    }
}

La valeur preferredValue de 100 indique que le demandeur souhaite que le quota GPUS-PER-GPU-FAMILY-per-project-region soit défini sur cette valeur. Le champ de dimensions indique que la préférence ne s'applique qu'à la région us-central1.

Vérifier la valeur accordée

L'exemple suivant montre une ressource QuotaPreference dans une méthode GetQuotaPreference.

{
    "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-gpus-us-central1",
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 100,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
    },
    "dimensions": {
        "region": "us-central1"
    },
    "createTime": "2023-01-15T01:30:15.01Z",
    "updateTime": "2023-01-16T02:35:16.01Z"
}

Ce résultat inclut les valeurs suivantes :

  • PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

La réponse affiche une valeur grantedValue de 100, ce qui signifie que la valeur preferredValue de l'exemple précédent a été approuvée et traitée. Les préférences pour différentes dimensions sont différentes ressources QuotaPreference. Par exemple, QuotaPreference pour le processeur dans les régions us-central1 et us-east1 sont deux ressources distinctes.

Veuillez indiquer une préférence de quota

Les ressources QuotaPreference sont utilisées pour indiquer votre valeur préférée pour un quota particulier. La valeur actuelle d'un quota particulier est basée sur :

  • Les requêtes QuotaPreference que vous avez effectuées.

  • Approbation des demandes d'augmentation de quota par Google Cloud.

  • Modifications apportées aux quotas initiés par Google Cloud

Il n'est pas possible de supprimer un objet QuotaPreference. Toutefois, vous pouvez définir une valeur de quota préférée inférieure à la valeur approuvée par Google Cloud pour ajouter des garde-fous.

Pour en savoir plus sur la ressource QuotaPreference, consultez la documentation de référence de l'API Cloud Quotas.

Pour en savoir plus sur les requêtes QuotaPreference, consultez Mettre en œuvre des cas d'utilisation courants.

Informations sur les quotas

QuotaInfo est une ressource en lecture seule qui fournit des informations sur un quota particulier pour un projet, un dossier ou des organisations spécifique. Elle affiche des informations sur les quotas définis par les services Google Cloud et sur les ajustements de quotas effectués par les clients. La ressource QuotaInfo contient des informations telles que les métadonnées, le type de conteneur et la dimension.

Définir différentes valeurs de quota par région

L'exemple de ressource QuotaInfo suivant montre que le quota de processeurs pour le projet est de 200 pour la région us-central1 et de 100 pour toutes les autres régions.

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/CPUS-per-project-region",
    "quotaId": "CPUS-per-project-region",
    "metric": "compute.googleapis.com/cpus",
    "containerType": "PROJECT",
    "dimensions": [
        "region"
    ],
    "isPrecise": true,
    "quotaDisplayName": "CPUs per project per region",
    "metricDisplayName": "CPUs",
    "dimensionsInfo": [
        {
            "dimensions": {
                "region": "us-central1"
            },
            "details": {
                "quotaValue": 200,
                "resetValue": 200
            },
            "applicableLocations": [
                "us-central1",
            ]
        },
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 100
            },
            "applicableLocations": [
                "us-central2",
                "us-west1",
                "us-east1"
            ]
        }
    ]
}

Ce résultat inclut les valeurs suivantes :

  • PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

Définir un quota mondial

L'exemple de ressource QuotaInfo suivant montre un quota de débit avec un intervalle d'actualisation par minute. Les dimensions sont vides, ce qui indique qu'il s'agit d'un quota mondial. Tous les quotas sans dimension de région ou de zone sont mondiaux.

{
    "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/ReadRequestsPerMinutePerProject",
    "quotaId": "ReadRequestsPerMinutePerProject",
    "metric": "compute.googleapis.com/read_requests",
    "refreshInterval": "minute",
    "containerType": "PROJECT",
    "dimensions": [],
    "isPrecise": false,
    "quotaDisplayName": "Read Requests per Minute",
    "metricDisplayName": "Read Requests",
    "dimensionsInfo": [
        {
            "details": {
                "quotaValue": 100,
                "resetValue": 200
            },
            "applicableLocations": [
                "global"
            ]
        }
    ]
}

Ce résultat inclut les valeurs suivantes :

  • PROJECT_NUMBER : identifiant unique généré automatiquement pour votre projet.

Pour en savoir plus sur la ressource QuotaInfo, consultez la documentation de référence de l'API Cloud Quotas.

Pour en savoir plus sur les requêtes QuotaPreference, consultez Mettre en œuvre des cas d'utilisation courants.

Noms de ressources

Les ressources sont des entités nommées et sont identifiées par des noms de ressources. Les noms de ressources sont utilisés dans toutes les requêtes et réponses, et chaque ressource doit posséder son propre nom de ressource unique. Chaque nom de ressource est encodé par un ensemble de champs.

Ressource de préférence de quota

La convention d'attribution de noms pour une ressource QuotaPreference utilise le modèle suivant :

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Vous pouvez définir quotaPreferenceId lors de la création d'une préférence de quota. Sinon, un ID est généré. Il est recommandé d'utiliser un schéma de nommage quotaPreferenceId pour encoder le nom du service, l'ID de quota, l'emplacement et d'autres dimensions. L'élément quotaPreferenceId doit être unique pour le projet, le dossier ou les organisations.

Pour la ressource quotaPreference par exemple, vous pouvez utiliser un modèle pour encoder votre ID de préférence de quota : 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

L'exemple suivant illustre ce modèle : 

compute_us-central1_nvidia-200

Avec un nom de ressource, vous devez utiliser la méthode GET pour récupérer un QuotaPreference. Vous pouvez également appeler la méthode UPDATE avec l'option allow_missing activée pour créer ou mettre à jour un QuotaPreference.

Ressource d'informations sur les quotas

La convention d'attribution de noms pour une ressource QuotaInfo utilise le modèle suivant :

projects/PROJECT_NUMBER/locations/global/services/SERVICE_NAME/quotaInfos/QUOTA_ID

Étape suivante