Cette page a été traduite par l'API Cloud Translation.

Mettre en œuvre des cas d'utilisation courants

Vous trouverez sur cette page la procédure à suivre pour mettre en œuvre des cas d'utilisation courants utilisant l'API Cloud Quotas. Cette API vous permet d'ajuster de manière automatisée des quotas et d'automatiser les ajustements de quota dans vos projets, dossiers ou organisations Google Cloud.

Pour en savoir plus, consultez la présentation et la documentation de référence de l'API Cloud Quotas.

Limites

Cloud Quotas présente les limites suivantes :

Dans la plupart des cas, les ajustements d'augmentation de quota doivent être effectués au niveau du projet. Un nombre limité de produits accepte les ajustements visant une augmentation de quota au niveau de l'organisation. Pour savoir si un produit Google Cloud prend en charge les ajustements d'augmentation de quota au niveau de l'organisation, consultez la documentation du produit.
Vous pouvez demander des ajustements de diminution de quota pour les quotas au niveau du projet, de l'organisation et du dossier.
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.
Dans la console Google Cloud, la page Quotas et limites du système n'accepte pas la sélection régionale ou zonale pour les demandes d'ajustement des quotas à partir du bouton Modifier. Pour ajuster les quotas au niveau régional ou zonal dans la console Google Cloud, consultez les instructions pour demander un quota plus élevé.

Suivre l'utilisation et demander une augmentation lorsque l'utilisation est supérieure à 80 %

Cet exemple suit l'utilisation du quota avec Cloud Monitoring, puis demande une augmentation lorsque l'utilisation est supérieure à 80 %.

Appelez la ressource QuotaInfo de votre service pour déterminer la valeur quotaValue actuelle. Dans cet exemple, le service est compute.googleapis.com:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Remplacez PROJECT_NUMBER par le numéro de votre projet.

Pour trouver les processeurs par projet et les emplacements applicables, recherchez l'ID de quota CPUS-per-project-region dans la réponse QuotaInfo. quotaValue est défini sur 20.

"quotaInfos": [
  ...
  {
      "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"
      ],
      "dimensionsInfo": [
          {
              "dimensions": [],
              "details": {
                  "quotaValue": 20,
                  "resetValue": 20
              },
              "applicableLocations": [
                  "us-central1",
                  "us-central2",
                  "us-west1",
                  "us-east1"
              ]
          }
      ]
  },
  ...
]

Appelez l'API Cloud Monitoring pour connaître l'utilisation du quota. Dans l'exemple suivant, la région us-central1 a été spécifiée. Les métriques de quota compatibles sont répertoriées sous serviceruntime.

{
"name": "projects/PROJECT_NUMBER"
  "filter": "metric.type=\"serviceruntime.googleapis.com/quota/allocation/usage\" AND
  metric.labels.quota_metric=\"compute.googleapis.com/cpus\" AND resource.type=\"consumer_quota\" AND
  resource.label.location=\"us-central1\" ",
  "interval": {
  "startTime": "2023-11-10T18:18:18.0000Z",
  "endTime": "2023-11-17T18:18:18.0000Z"
  },
  "aggregation": {
  "alignmentPeriod": "604800s", // 7 days
  "perSeriesAligner": "ALIGN_MAX",
  "crossSeriesReducer": "REDUCE_MAX"
  }
}

Pour déterminer votre utilisation, gérez la réponse de l'API Cloud Monitoring. Comparez la valeur de Cloud Monitoring à quotaValue dans les étapes précédentes pour déterminer l'utilisation.

Dans l'exemple de réponse suivant, la valeur d'utilisation dans Cloud Monitoring est de 19 dans la région us-central1. La valeur quotaValue pour toutes les régions est 20. L'utilisation est supérieure à 80% du quota, et une mise à jour des préférences de quota peut être effectuée.

time_series {
metric {
labels {
key: "quota_metric"
value: "compute.googleapis.com/cpus"
}
  type: "serviceruntime.googleapis.com/quota/allocation/usage"
}
resource {
  type: "consumer_quota"
  labels {
    key: "project_id"
    value: "PROJECT_ID"
  }
  labels {
    key: "location"
    value: "us-central1"
  }
}
metric_kind: GAUGE
value_type: INT64
points {
  interval {
    start_time {
      seconds: "2023-11-10T18:18:18.0000Z"
    }
    end_time {
      seconds: "2023-11-17T18:18:18.0000Z"
    }
  }
  value {
    int64_value: 19
  }
}
}

Pour éviter les préférences de quota en double, appelez d'abord ListQuotaPreferences pour vérifier si des requêtes sont en attente. L'option reconciling=true appelle les requêtes en attente.
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
```
Remplacez PROJECT_NUMBER par le numéro de votre projet.
Appelez UpdateQuotaPreference pour augmenter la valeur du quota pour la région us-central1. Dans l'exemple suivant, une nouvelle valeur préférée de 100 a été spécifiée.

Le champ allow_missing est défini sur true. Cela indique au système de créer une ressource QuotaPreference où aucun nom n'existe avec le nom fourni.
```
PATCH projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1?allowMissing=true {
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": { "preferredValue": 100 },
"dimensions": { "region": "us-central1" },
"justification": "JUSTIFICATION",
"contactEmail": "EMAIL"
}
```
Remplacez les éléments suivants :
- PROJECT_NUMBER: identifiant unique de votre projet.
- JUSTIFICATION: chaîne facultative expliquant votre requête.
- EMAIL: adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.
Pour ajuster les dimensions de votre préférence de quota, procédez comme suit :
- Si vous souhaitez que les préférences de quota s'appliquent à toutes les régions, supprimez les informations régionales.
- Si votre quota est défini par zone, remplacez les informations régionales par les informations de zone.
Appelez GetQuotaPreference pour vérifier l'état de la modification des préférences de quota:
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
```
Remplacez PROJECT_NUMBER par le numéro de votre projet.

Pendant que Google Cloud évalue la valeur de quota demandée, l'état de rapprochement est défini sur true.
```
"name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
"service": "compute.googleapis.com",
"quotaId": "CPUS-per-project-region",
"quotaConfig": {
  "preferredValue": 100,
  "grantedValue": 50,
  "traceId": "123acd-345df23",
  "requestOrigin": "ORIGIN_UNSPECIFIED"
},
"dimensions": { "region": "us-central1" },
"reconciling": true,
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
```
Une fois les préférences de quota traitées, le champ reconciling est défini sur false. La valeur grantedValue est identique à preferredValue. Le quota préféré est entièrement accordé.

Lorsque Google Cloud refuse ou approuve partiellement une demande client, la valeur de quota accordée peut toujours être inférieure à la valeur préférée.

Réduire un quota

L'exemple suivant réduit le nombre de TPU à 10 dans chaque région.

Obtenez l'ID de quota et la valeur actuelle du quota avec un appel ListQuotaInfos:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Remplacez PROJECT_NUMBER par le numéro de votre projet.

Parcourez les champs de réponse pour rechercher une entrée QuotaInfo pour V2-TPUS-per-project-region.

"quotaInfos": [
  ...
  {
      "name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
      "quotaId": "V2-TPUS-per-project-region",
      "metric": "compute.googleapis.com/Tpus",
      "containerType": "PROJECT",
      "dimensions": [
          "region"
      ],
      "dimensionsInfo": [
          {
              "dimensions": [],
              "details": {
                  "quotaValue": 20,
                  "resetValue": 20
              },
              "applicableLocations": [
                  "us-central1",
                  "us-central2",
                  "us-west1",
                  "us-east1"
              ]
          }
      ]
  },
  ...
]

Dans cette réponse, l'ID de quota est V2-TPUS-per-project-region et la valeur quotaValue actuelle est de 20.

Réduisez le quota de TPU à chaque région à 10 avec un CreateQuotaPreferenceRequest. Définissez preferredValue sur 10.
```
POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-Tpu-all-regions {
  "quotaConfig": {
      "preferredValue": 10
  },
  "dimensions": [],
  "service": "compute.googleapis.com",
  "quotaId": "V2-TPUS-per-project-region",
  "justification": "JUSTIFICATION",
  "contactEmail": "EMAIL"
}
```
Remplacez les éléments suivants :
- PROJECT_NUMBER: identifiant unique de votre projet.
- JUSTIFICATION: chaîne facultative expliquant votre requête.
- EMAIL: adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.

Confirmez la nouvelle valeur du quota avec un appel GetQuotaInfo qui définit l'ID de quota sur V2-TPUS-per-project-region.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region

Remplacez PROJECT_NUMBER par le numéro de votre projet.

Voici un exemple de réponse, la valeur de value est 10 et s'applique dans toutes les régions.

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/V2-TPUS-per-project-region",
"quotaId": "V2-TPUS-per-project-region",
"metric": "compute.googleapis.com/v2_tpus",
"containerType": "PROJECT",
"dimensions": [
  "region"
],
"dimensionsInfo": [
  {
      "dimensions": [],
      "details": {
          "value": 10,
      },
      "applicableLocations": [
          "us-central1",
          "us-central2",
          "us-west1",
          "us-east1"
      ]
  }
]

Copier les préférences de quota dans un autre projet

L'exemple suivant copie toutes les préférences de quota d'un projet à un autre. Il est écrit en Java, mais vous pouvez utiliser n'importe quel langage de programmation.

Appelez ListQuotaPreferences sur le projet source sans filtre :
```
GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
```
PROJECT_NUMBER1 est le numéro du projet source. La réponse contient toutes les préférences de quota pour le projet source.

Pour chaque préférence de quota dans la réponse, appelez UpdateQuotaPreference et définissez les champs suivants:

name : le champ de nom mis à jour est extrait de la réponse et le numéro de projet source (PROJECT_NUMBER1) est remplacé par le numéro de projet de destination (PROJECT_NUMBER2).
service, quotaId, preferredValue, dimensions : ces champs peuvent être directement récupérés de la réponse telle quelle.

for (QuotaPreference srcPreference : listResponse.getQuotaPreferences()) {
  QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
      .setName(srcPreference.getName().replace("PROJECT_NUMBER1", "PROJECT_NUMBER2"))
      .setService(srcPreference.getService())
      .setQuotaId(srcPreference.getQuotaId())
      .setJustification(srcPreference.getJustification())
      .setContactEmail(srcPreference.getContactEmail())
      .setQuotaConfig(
          QuotaConfig.newBuilder().setPreferredValue(srcPreference.getQuotaConfig().getPreferredValue()))
      .putAllDimensions(srcPreference.getDimensionsMap());
  UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
      .setQuotaPreference(targetPreference)
      .setAllowMissing(true)
      .build();
  cloudQuotas.updateQuotaPreference(updateRequest);
}

Appelez ListQuotaPreferences pour vérifier l'état des préférences de quota pour le projet de destination:
```
GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
```
Remplacez PROJECT_NUMBER2 par le numéro de votre projet de destination.

Répertorier les demandes de quota en attente

Pour répertorier toutes les requêtes de préférence de quota en attente pour un projet, appelez ListQuotaPreferences avec le filtre reconciling=true.

GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?reconciling=true

Remplacez PROJECT_NUMBER par le numéro de votre projet.

La réponse à cette requête renvoie la dernière préférence de quota en attente. Étant donné que l'API Cloud Quotas est une API déclarative, la dernière préférence de quota est celle que le système tente de remplir.

Un exemple de réponse ressemble à ce qui suit :

  "quotaPreferences": [
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 100,
        "grantedValue": 30,
        "traceId": "123acd-345df23",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "dimensions": {
        "region": "us-central1"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:30:15.01Z",
      "updateTime": "2023-01-16T02:35:16.01Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-cross-regions",
      "service": "compute.googleapis.com",
      "quotaId": "CPUS-per-project-region",
      "quotaConfig": {
        "preferredValue": 10,
        "grantedValue": 5,
        "traceId": "456asd-678df43",
        "requestOrigin": "ORIGIN_UNSPECIFIED"
      },
      "reconciling": true,
      "createTime": "2023-01-15T01:35:15.01Z",
      "updateTime": "2023-01-15T01:35:15.01Z"
    }
  ]

Demander une augmentation du quota des groupes

Pour demander des augmentations pour un groupe de quotas dans un nouveau projet, stockez les quotas préférés du nouveau projet dans un fichier CSV avec les valeurs suivantes : nom du service, ID du quota, valeur du quota préféré, dimensions.

Pour chaque ligne du fichier CSV, lisez le contenu dans les champs serviceName, quotaId, preferredValue et dimensionMap.

CreateQuotaPreferenceRequest request =
  CreateQuotaPreferenceRequest.newBuilder()
     .setParent("projects/PROJECT_NUMBER/locations/global")
     .setQuotaPreferenceId(buildYourOwnQuotaPreferenceId(serviceName, quotaId, dimensionMap))
     .setQuotaPreference(
        QuotaPreference.newBuilder()
            .setService(serviceName)
            .setQuotaId(quotaId)
            .setJustification(justification)
            .setContactEmail(contactEmail)
            .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(preferredValue))
            .putAllDimensions(dimensionMap))
  .build();
cloudQuotas.createQuotaPreference(request);

Remplacez PROJECT_NUMBER par le numéro de votre projet.

Étant donné que le projet cible est nouveau, vous pouvez appeler en toute sécurité la méthode CreateQuotaPreference lorsque vous lisez et attribuez des champs. Vous pouvez également appeler la méthode UpdateQuotaPreference avec le paramètre allow_missing défini sur true.

La méthode buildYourOwnQuotaPreferenceId crée un ID de préférence de quota à partir du nom du service, de l'ID de quota et d'un mappage des dimensions en fonction de votre schéma de nommage. Vous pouvez également choisir de ne pas définir d'ID de préférence de quota. Un ID de préférence de quota est généré pour vous.

Demander des ajustements pour des quotas qui ne sont pas utilisés

Les demandes d'ajustement de quota suivent le même processus, que le quota que vous ajustez soit utilisé ou non. Pour savoir comment demander un ajustement d'augmentation de quota, consultez la section Demander un quota supérieur. Pour demander une valeur de quota inférieure, suivez les instructions pour demander une valeur de quota supérieure, mais spécifiez la valeur inférieure de votre choix lorsque vous saisissez la valeur de votre demande.

Obtenir des informations sur le quota d'une dimension spécifique au service

La famille de GPU est une dimension spécifique au service. L'exemple de requête suivant utilise l'ID de quota GPUS-PER-GPU-FAMILY-per-project-region pour obtenir la ressource QuotaInfo.

GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GPUS-PER-GPU-FAMILY-per-project-region

Remplacez PROJECT_NUMBER par le numéro de votre projet.

Ceci est un exemple de réponse. Pour chaque clé gpu_family unique, quotaValue et applicableLocations sont différents :

"name": "projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos/GpusPerProjectPerRegion",
"quotatName": "CPUS-per-project-region",
"metric": "compute.googleapis.com/gpus_per_gpu_family",
"isPrecise": true,
"quotaDisplayName": "GPUs per GPU family",
"metricDisplayName": "GPUs",
"dimensions": [
    "region",
    "gpu_family"
],
"dimensionsInfo": [
    {
        "dimensions": {
            "region": "us-central1",
            "gpu_family": "NVIDIA_H200"
        },
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "region": "us-central1"
            }
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": {
            "gpu_familly": "NVIDIA_H100"
            }
        "details": {
            "quotaValue": 10,
        },
        "applicableLocations": [
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
      {
        "dimensions": [],
        "details": {
            "quotaValue": 50,
            "resetValue": 50,
        },
        "applicableLocations": [
            "us-central1",
            "us-central2",
            "us-west1",
            "us-east1"
        ]
    }
]

Créer une préférence de quota pour une dimension spécifique au service

L'exemple suivant montre comment créer un quota pour une région et une famille de GPU données avec une valeur préférée de 100. L'emplacement cible est spécifié dans le mappage des dimensions avec la clé region, et la famille du GPU cible avec la clé gpu_family.

L'exemple CreateQuotaPreference suivant spécifie une famille de GPU NVIDIA_H100 et une région us-central1.

POST projects/PROJECT_NUMBER/locations/global/quotaPreferences?quotaPreferenceId=compute_googleapis_com-gpus-us-central1-NVIDIA_H100 {
    "service": "compute.googleapis.com",
    "quotaId": "GPUS-PER-GPU-FAMILY-per-project-region",
    "quotaConfig": {
        "preferredValue": 100
    },
    "dimensions": {"region": "us-central1", "gpu_family": "NVIDIA_H100"},
    "justification": "JUSTIFICATION",
    "contactEmail": ""EMAIL"
}

Remplacez les éléments suivants :

PROJECT_NUMBER: identifiant unique de votre projet.
JUSTIFICATION: chaîne facultative expliquant votre requête.
EMAIL: adresse e-mail pouvant être utilisée comme contact, au cas où Google Cloud aurait besoin de plus d'informations avant d'accorder un quota supplémentaire.

Pour ajuster les dimensions de vos préférences de quota, procédez comme suit :

Mettre à jour une préférence de quota pour une dimension spécifique au service

L'exemple de code suivant obtient la valeur actuelle de la dimension {"region" : "us-central1"; gpu_family:"NVIDIA_H100"},, puis définit la valeur préférée sur le double de cette valeur. Il est écrit en Java, mais vous pouvez utiliser n'importe quel langage de programmation.

// Get the current quota value for the target dimensions
Map<String, String> targetDimensions = Maps.createHashMap("region", "us-central1", "gpu_family", "NVIDIA_H100");
long currentQuotaValue = 0;
QuotaInfo quotaInfo = cloudQuotas.GetQuotaInfo(
    "projects/PROJECT_NUMBER/locations/global/services/" + serviceName + "quotaInfos/" + quotaId;
for (dimensionsInfo : quotaInfo.getDimensionsInfoList()) {
    If (targetDimensions.entrySet().containsAll(dimensionsInfo.getDimensionsMap().entrySet()) {
       currentQuotaValue = dimensionsInfo.getDetails().getValue();
       break;
    })
}

// Set the preferred quota value to double the current value for the target dimensions
QuotaPreference.Builder targetPreference = QuotaPreference.newBuilder()
        .setName(buildYourOwnQuotaPreferenceId(serviceName, quotaId, targetDimensions))
        .setService(serviceName)
        .setQuotaId(quotaId)
        .setJustification(justification)
        .setContactEmail(contactEmail)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

Remplacez PROJECT_NUMBER par l'identifiant unique de votre projet.

Étape suivante

À propos de l'API Cloud Quotas
Documentation de référence de l'API Cloud Quotas
Comprendre les quotas