Gängige Anwendungsfälle implementieren

Auf dieser Seite wird beschrieben, wie Sie gängige Anwendungsfälle mithilfe der Cloud Quotas API implementieren. Mit dieser API können Sie Kontingente programmatisch anpassen und Kontingentanpassungen in Ihren Google Cloud-Projekten, Ordnern oder Ihrer Organisation automatisieren.

Weitere Informationen finden Sie in der Übersicht und in der Referenz zur Cloud Quotas API.

Beschränkungen

Die Cloud Quotas API unterliegt den folgenden Einschränkungen:

Für Kontingente auf Projektebene können Sie eine Erhöhung und Verringerung der Kontingente anfordern.
Kontingentverringerungen können für Kontingente auf Projekt-, Ordner- und Organisationsebene angefordert werden.

Verfolgen Sie die Nutzung und fordern Sie einen Anstieg an, wenn die Nutzung über 80 % liegt.

In diesem Beispiel wird die Kontingentnutzung mit Cloud Monitoring nachverfolgt. Anschließend wird eine Erhöhung angefordert, wenn die Nutzung über 80 % liegt.

Rufen Sie die Ressource QuotaInfo für Ihren Dienst auf, um den aktuellen quotaValue zu ermitteln. Der Dienst in diesem Beispiel ist compute.googleapis.com:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Ersetzen Sie PROJECT_NUMBER durch die Projektnummer für Ihr Projekt.

Suchen Sie in der Antwort QuotaInfo nach der Kontingent-ID CPUS-per-project-region, um die CPUs pro Projekt und die entsprechenden Standorte zu ermitteln. Der quotaValue ist 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"
                ]
            }
        ]
    },
      …
]

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Rufen Sie die Cloud Monitoring API auf, um die Kontingentnutzung zu ermitteln. Im folgenden Beispiel wurde die Region us-central1 angegeben. Unterstützte Kontingentmesswerte sind unter serviceruntime aufgeführt.

{
"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
    }
}

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Verarbeiten Sie zum Ermitteln der Nutzung die Antwort der Cloud Monitoring API. Vergleichen Sie den Wert von Cloud Monitoring mit dem quotaValue in den vorherigen Schritten, um die Nutzung zu ermitteln.

In der folgenden Beispielantwort beträgt der Nutzungswert in Cloud Monitoring 19 in der Region us-central1. Der quotaValue für alle Regionen ist 20. Die Nutzung beträgt mehr als 80 % des Kontingents und eine Aktualisierung der Kontingenteinstellung kann initiiert werden.

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
    }
  }
}

Diese Ausgabe enthält die folgenden Werte:

PROJECT_ID: eine global eindeutige Kennung für Ihr Projekt

Rufen Sie zuerst ListQuotaPreferences auf, um zu prüfen, ob ausstehende Anfragen vorhanden sind, um doppelte Kontingenteinstellungen zu vermeiden. Das Flag reconciling=true ruft ausstehende Anfragen auf.
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences?filter=service=%22compute.googleapis.com%22%20AND%20quotaId=%22CPUS-per-project-region%22%20AND%20reconciling=true
```
Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.
Rufen Sie UpdateQuotaPreference auf, um den Kontingentwert für die Region us-central1 zu erhöhen. Im folgenden Beispiel wurde ein neuer bevorzugter Wert von 100 angegeben.

Das Feld allow_missing ist auf true gesetzt. Damit wird das System angewiesen, eine QuotaPreference-Ressource zu erstellen, in der keine mit dem angegebenen Namen vorhanden ist.
```
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": [
    "mapField": {
    "key": "region",
    "value": "us-central1"
    }
    ],
    }
```
Diese Ausgabe enthält die folgenden Werte:
- PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt
So passen Sie die Dimensionen Ihrer Kontingenteinstellung an:
- Wenn die Kontingenteinstellung für alle Regionen gelten soll, entfernen Sie die Regionsinformationen.
- Wenn Ihr Kontingent pro Zone definiert ist, ersetzen Sie die Regionsinformationen durch die Zoneninformationen.
Rufen Sie GetQuotaPreference auf, um den Status der Änderung der Kontingenteinstellung zu prüfen:
```
GET projects/PROJECT_NUMBER/locations/global/quotaPreferences/compute_googleapis_com-cpus-us-central1
```
Ersetzen Sie PROJECT_NUMBER durch die Projektnummer für Ihr Projekt. Während Google Cloud den angeforderten Kontingentwert auswertet, wird der Abgleichsstatus auf true gesetzt.
```
"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": [
    "mapField": {
        "key": "region",
        "value": "us-central1"
    }
],
"reconciling": true
"createTime": "2023-01-15T01:30:15.01Z",
"updateTime": "2023-01-16T02:35:16.01Z"
```
Diese Ausgabe enthält die folgenden Werte:
- PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt
Nachdem die Kontingenteinstellung verarbeitet wurde, wird das Feld reconciling auf false gesetzt. grantedValue ist mit preferredValue identisch. Das bevorzugte Kontingent ist vollständig gewährt.

Wenn Google Cloud eine Kundenanfrage ablehnt oder teilweise genehmigt, kann der zugewiesene Kontingentwert immer noch unter dem bevorzugten Wert liegen.

Kontingent verringern

Im folgenden Beispiel wird die Anzahl der TPUs in jeder Region auf 10 reduziert.

Rufen Sie die Kontingent-ID und den aktuellen Kontingentwert mit einem ListQuotaInfos-Aufruf ab:
```
GET projects/PROJECT_NUMBER/locations/global/services/compute.googleapis.com/quotaInfos
```
Ersetzen Sie PROJECT_NUMBER durch Ihre Projektnummer für Ihr Projekt.

Suchen Sie in den Antwortfeldern nach einem QuotaInfo-Eintrag für 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"
                ]
            }
        ]
    },
      …
]

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

In dieser Antwort lautet die Kontingent-ID V2-TPUS-per-project-region und der aktuelle quotaValue ist 20.

Reduzieren Sie das TPU-Kontingent in jeder Region mit einem CreateQuotaPreferenceRequest auf 10. Legen Sie den Wert preferredValue auf 10 fest.

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",
}

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Bestätigen Sie den neuen Kontingentwert mit einem GetQuotaInfo-Aufruf, der die Kontingent-ID als V2-TPUS-per-project-region definiert.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts. Das folgende Beispiel zeigt eine Antwort. value ist 10 und gilt in allen Regionen.

"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"
        ]
    }
]

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Kontingenteinstellungen in ein anderes Projekt kopieren

Im folgenden Beispiel werden alle Kontingenteinstellungen von einem Projekt in ein anderes kopiert.

Rufen Sie ListQuotaPreferences für das Quellprojekt ohne Filter auf:
```
GET projects/PROJECT_NUMBER1/locations/global/quotaPreferences
```
PROJECT_NUMBER1 ist die Projektnummer für das Quellprojekt. Die Antwort enthält alle Kontingenteinstellungen für das Quellprojekt.

Rufen Sie für jede Kontingenteinstellung in der Antwort UpdateQuotaPreference auf und definieren Sie die folgenden Felder:

name: Das aktualisierte Feld "Name" stammt aus der Antwort und die Quellprojektnummer (PROJECT_NUMBER1) wird durch die Zielprojektnummer (PROJECT_NUMBER2) ersetzt.
service, quotaId, preferredValue, dimensions – Diese Felder können direkt aus der Antwort übernommen werden.

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

ZusatzinformationenListQuotaPreferences um den Status der Kontingenteinstellungen für das Zielprojekt zu prüfen:
```
GET projects/PROJECT_NUMBER2/locations/global/quotaPreferences
```
Ersetzen Sie PROJECT_NUMBER2 durch die Projektnummer Ihres Zielprojekts.

Ausstehende Kontingentanfragen auflisten

Rufen Sie ListQuotaPreferences mit dem Filter reconciling=true auf, um alle ausstehenden Anfragen für Kontingenteinstellungen für ein Projekt aufzulisten.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Die Antwort auf diese Anfrage gibt die neueste ausstehende Kontingenteinstellung zurück. Da die Cloud Quotas API eine deklarative API ist, versucht das System, die aktuellste Kontingenteinstellung zu erfüllen.

Dies ist eine Beispielantwort:

"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": [
            "map_field": {
                "key": "region",
                "value": "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"
    }
]

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Kontingenterhöhungen für Gruppen anfordern

Wenn Sie Erhöhungen für eine Gruppe von Kontingenten in einem neuen Projekt anfordern möchten, speichern Sie die bevorzugten Kontingente für das neue Projekt in einer CSV-Datei mit den folgenden Werten: Dienstname, Kontingent-ID, bevorzugter Kontingentwert, Dimensionen.

Lesen Sie für jede Zeile in der CSV-Datei den Inhalt in die Felder serviceName, quotaId, preferredValue und dimensionMap.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Da das Zielprojekt neu ist, kann beim Lesen und Zuweisen der Felder die Methode CreateQuotaPreference sicher aufgerufen werden. Alternativ können Sie die Methode UpdateQuotaPreference aufrufen, wobei allow_missing auf true gesetzt ist.

Die Methode buildYourOwnQuotaPreferenceId erstellt eine Kontingentpräferenz-ID aus dem Dienstnamen, der Kontingent-ID und einer Zuordnung von Dimensionen gemäß Ihrem Benennungsschema. Alternativ können Sie sich entscheiden, die Kontingent-ID nicht festzulegen. Eine ID für die Kontingenteinstellung wird für Sie generiert.

Kontingentinformationen für eine dienstspezifische Dimension abrufen

Die GPU-Familie ist eine dienstspezifische Dimension. In der folgenden Beispielanfrage wird die Kontingent-ID GPUS-PER-GPU-FAMILY-per-project-region verwendet, um die Ressource QuotaInfo abzurufen.

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

Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

Dies ist eine Beispielantwort. Für jeden eindeutigen gpu_family-Schlüssel unterscheiden sich quotaValue und applicableLocations:

"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": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            },
            "mapField": {
                "key": "gpu_family",
                "value": "NVIDIA_H200"
            }
        ],
        "details": {
            "quotaValue": 30,
            "resetValue": 30,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "region",
                "value": "us-central1"
            }
        ],
        "details": {
            "quotaValue": 100,
            "resetValue": 100,
        },
        "applicableLocations": [
            "us-central1"
        ]
    },
    {
        "dimensions": [
            "mapField": {
                "key": "gpu_familly",
                "value": "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"
        ]
    }
]

Diese Ausgabe enthält die folgenden Werte:

PROJECT_NUMBER: eine automatisch generierte eindeutige Kennzeichnung für das Projekt

Kontingenteinstellung für eine dienstspezifische Dimension erstellen

Das folgende Beispiel zeigt, wie Sie ein Kontingent für eine bestimmte Region und GPU-Familie mit einem bevorzugten Wert von 100 erstellen. Der Zielspeicherort wird in der Zuordnung der Dimensionen mit dem Schlüssel region und die Ziel-GPU-Familie mit dem Schlüssel gpu_family angegeben.

Im folgenden CreateQuotaPreference-Beispiel wird eine GPU-Familie von NVIDIA_H100 und eine Region von us-central1 angegeben. Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

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": [
        "mapField": {
            "key": "region",
            "value": "us-central1"
        }
          "mapField": {
            "key": "gpu_family",
            "value": "NVIDIA_H100"
        }
    ],
}

Kontingenteinstellung für eine dienstspezifische Dimension aktualisieren

Der folgende Beispielcode ruft den aktuellen Wert für die Dimensionen {"region" : "us-central1"; gpu_family:"NVIDIA_H100"} ab und legt dann den bevorzugten Wert auf das Doppelte fest. Ersetzen Sie PROJECT_NUMBER durch die Projektnummer Ihres Projekts.

// 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)
        .setQuotaConfig(QuotaConfig.newBuilder().setPreferredValue(currentQuotaValue * 2))
        .putAllDimensions(targetDimensions));
UpdateQuotaPreferenceRequest updateRequest = UpdateQuotaPreferenceRequest.newBuilder()
        .setQuotaPreference(targetPreference)
        .setAllowMissing(true)
        .build();
 cloudQuotas.updateQuotaPreference(updateRequest);

Nächste Schritte

Informationen zur Cloud Quotas API
Referenz zur Cloud Quotas API
Lernen Sie Kontingente kennen