Gérer les quotas de service

Cette page explique comment afficher toutes les métriques et limites de quota sur un projet Google Cloud pour un service spécifique, et comment limiter l'utilisation des quotas pour ce service à l'aide d'un quota de remplacement. Vous pouvez utiliser Service Usage pour gérer les quotas de vos projets pour n'importe quel service, y compris les services Google Cloud publics et les services privés créés à l'aide de Cloud Endpoints. Pour plus d'informations sur les différences entre les API et services publics et privés, consultez la page Services publics et services privés.

Assurez-vous de vous familiariser avec le modèle de quota de service pour mieux comprendre la terminologie utilisée dans ce tutoriel.

Dans la plupart des cas d'utilisation opérationnels, le moyen le plus simple de gérer le quota consiste à utiliser Google Cloud Console. Si vous devez programmer à l'aide de l'API Service Usage, nous vous recommandons d'utiliser l'une des bibliothèques clientes que nous fournissons. Pour tester l'API, vous pouvez suivre les instructions de ce guide et utiliser la commande curl pour effectuer vos tests sans configurer un environnement de développement d'application complet.

Avant de commencer

Pour gérer les quotas de service :

Pour ce tutoriel, nous utilisons une variable d'environnement PROJECT_NUMBER définie sur un numéro de projet que vous possédez, et le service serviceusage.googleapis.com comme service concerné.

Pour trouver rapidement le numéro d'un projet que vous possédez avec l'ID PROJECT_ID, utilisez la commande suivante :

PROJECT_NUMBER=`gcloud projects list --filter="${PROJECT_ID}" --format="value(PROJECT_NUMBER)"`

Afficher le quota de service

Pour voir toutes les métriques et limites de quota qui s'appliquent à un client spécifique sur un service, utilisez la commande suivante :

gcurl https://serviceusage.googleapis.com/v1beta1/projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics

L'appel répond avec une liste de métriques définies par le service. Chacune des métriques présente la liste des limites qui s'appliquent à ce client, les valeurs de ces limites et tout remplacement éventuel. Voici un exemple de réponse :

{
  "metrics": [
    {
      "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests",
      "displayName": "Default requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject",
          "unit": "1/min/{project}",
          "metric": "serviceusage.googleapis.com/default_requests",
          "quotaBuckets": [
            {
              "effectiveLimit": "240",
              "defaultLimit": "240"
            }
          ]
        }
      ],
      "metric": "serviceusage.googleapis.com/default_requests"
    },
    {
      "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fmutate_requests",
      "displayName": "Mutate requests",
      "consumerQuotaLimits": [
        {
          "name": "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fmutate_requests/limits/%2Fmin%2Fproject",
          "unit": "1/min/{project}",
          "metric": "serviceusage.googleapis.com/mutate_requests",
          "quotaBuckets": [
            {
              "effectiveLimit": "120",
              "defaultLimit": "120"
            }
          ]
        }
      ],
      "metric": "serviceusage.googleapis.com/mutate_requests"
    }
  ]
}

Chaque métrique de la réponse comporte un champ name. Pour inspecter les paramètres de quota pour cette métrique uniquement, plutôt que pour toutes les métriques, utilisez son name dans l'URL. Pour ce tutoriel, la variable d'environnement METRIC_RESOURCE_NAME stocke le nom de la ressource de métrique de quota :

METRIC_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests"
gcurl https://serviceusage.googleapis.com/v1beta1/${METRIC_RESOURCE_NAME}

De même, chaque limite d'une métrique comporte un champ name. Pour inspecter les paramètres de quota uniquement pour cette limite et cette métrique, plutôt que pour toutes les limites d'une même métrique ou toutes les limites de toutes les métriques, utilisez son name dans l'URL. Pour ce tutoriel, la variable d'environnement LIMIT_RESOURCE_NAME stocke le nom de la ressource de limite de quota :

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject"
gcurl https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}

Créer un remplacement de quota du client

Le propriétaire d'un projet peut appliquer un remplacement du client à une limite de quota spécifique sur ce projet, afin de réduire le montant total du quota que le consommateur peut imputer à cette limite.

Notez qu'un remplacement du client ne peut pas augmenter le quota disponible au-delà de ce qui est autorisé par le service par défaut ou tout remplacement existant effectué par d'autres parties (telles que le propriétaire du service ou l'administrateur de quota d'une organisation). Pour augmenter le quota disponible, utilisez l'option Modifier les quotas sur la page principale consacrée aux quotas ou demandez à l'administrateur de l'organisation une augmentation du quota.

Pour identifier une limite à remplacer, utilisez d'abord l'une des méthodes ci-dessus pour trouver la limite de quota qui vous intéresse, puis utilisez son champ de nom pour créer un nouveau remplacement de client dans la collection de remplacements correspondant à cette limite. L'exemple suivant concerne une limite de quota spécifique :

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject"
gcurl https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides -d '{"overrideValue": "220"}'

Si l'appel réussit, il renverra un identifiant d'opération, qui représente le travail en cours sur le serveur, à mesure que la modification de quota se propage aux systèmes backend :

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Pour vérifier la progression de l'opération, utilisez simplement son name :

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl https://serviceusage.googleapis.com/v1/${OPERATION_NAME}

Si l'opération réussit, le message de réponse inclut done: true et contient la ressource de remplacement nouvellement créée. Si l'opération échoue, le message de réponse inclut done: true, mais contient les détails de l'erreur au lieu de la ressource.

Vous pouvez également vérifier si une modification a été appliquée en répétant l'appel get d'origine sur la limite spécifique. La limite doit maintenant comporter un champ consumerOverride supplémentaire.

Créer des remplacements de quotas régionaux ou zonaux

Certaines limites de quota sont appliquées par région ou par zone. Cette information est indiquée par la présence de {region} ou {zone} dans le champ unit de la limite. Par exemple, une limite avec l'unité "1/{project}/{region}" est appliquée au niveau de la région. Appliquer un remplacement à une telle limite modifie le quota de base de chaque région ou zone. Pour modifier le quota uniquement pour une région ou une zone spécifique, ajoutez une dimension de quota à l'aide du champ dimensions lors de la création du remplacement. Par exemple, créez un remplacement régional sur une limite de quota régional Cloud ML comme ceci :

REGIONAL_LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/ml.googleapis.com/consumerQuotaMetrics/ml.googleapis.com%2Foptimizer_management_requests"
gcurl https://serviceusage.googleapis.com/v1beta1/${REGIONAL_LIMIT_RESOURCE_NAME}/consumerOverrides -d '{"overrideValue": "550", "dimensions": {"region": "asia-south1"} }'

Mettre à jour un remplacement de quota du client

Le propriétaire d'un projet peut également modifier la valeur d'un remplacement du client existant sur le projet.

Par exemple, supposons qu'un précédent appel de création ait renvoyé un remplacement avec un champ name comme ceci :

name: "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"

Utilisez ensuite ce nom pour identifier le remplacement à mettre à jour, comme ceci :

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"
gcurl https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME} -X PATCH -d '{"overrideValue": "230"}'

Si l'appel réussit, il renverra un identifiant d'opération, qui représente le travail en cours sur le serveur, à mesure que la modification de quota se propage aux systèmes backend :

{
  "name": "operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
}

Pour vérifier la progression de l'opération, utilisez simplement son name :

OPERATION_NAME="operations/quf.92accba3-6530-4fc1-9a95-c1280d48a6b7"
gcurl https://serviceusage.googleapis.com/v1/${OPERATION_NAME}

Si l'opération réussit, le message de réponse inclut done: true et contient la ressource de remplacement mise à jour. Si l'opération échoue, le message de réponse inclut done: true, mais contient les détails de l'erreur au lieu de la ressource mise à jour.

Supprimer un remplacement de quota du client

Le propriétaire d'un projet peut également supprimer du projet un remplacement du client.

Par exemple, supposons qu'un précédent appel de création ait renvoyé un remplacement avec un champ name comme ceci :

name: "projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"

Pour supprimer le remplacement, exécutez la séquence suivante :

OVERRIDE_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject/consumerOverrides/b14c5591ff01"
gcurl https://serviceusage.googleapis.com/v1beta1/${OVERRIDE_RESOURCE_NAME} -X DELETE

Forcer des changements de quotas importants

Si un changement lié au remplacement de quota entraîne une baisse de plus de 10 % du quota imposé, l'appel est rejeté, par mesure de sécurité. Cela évite de diminuer trop rapidement le quota par accident. Pour ignorer cette restriction, utilisez l'indicateur force. Par exemple, voici un appel de création qui prend l'indicateur force :

LIMIT_RESOURCE_NAME="projects/${PROJECT_NUMBER}/services/serviceusage.googleapis.com/consumerQuotaMetrics/serviceusage.googleapis.com%2Fdefault_requests/limits/%2Fmin%2Fproject"
gcurl https://serviceusage.googleapis.com/v1beta1/${LIMIT_RESOURCE_NAME}/consumerOverrides?force=true -d '{"overrideValue": "40"}'