Cloud Quotas API – Übersicht

Mit der Cloud Quotas API können Sie Kontingente programmatisch anpassen und Kontingentanpassungen auf Projektebene automatisieren. Die Cloud Quotas API kann für Folgendes verwendet werden:

Kontingentanpassungen automatisieren
Über die Cloud Quotas API können Sie Kontingenterhöhungen anfordern, wenn bestimmte Bedingungen erfüllt sind. Um beispielsweise Fehler aufgrund von Kontingentüberschreitungen zu vermeiden, können Sie die API verwenden, um eine Kontingenterhöhung programmatisch anzufordern, wenn Compute Engine-Ressourcen 80 % des verfügbaren Kontingents erreichen.
Kontingentkonfigurationen projektübergreifend skalieren
Die Cloud Quotas API kann Ihre Kontingentkonfigurationen von Projekt zu Projekt klonen. Wenn es einen bekannten Satz von Kontingenten gibt, die für jedes neue Google Cloud-Projekt erhöht werden müssen, können Sie die API in die Erstellungslogik Ihres Projekts einbinden, um automatisch eine Anfrage zur Kontingenterhöhung zu senden. Alle Kontingenterhöhungen müssen von Google Cloud genehmigt werden.
Kundenkontingentanfragen verarbeiten
Wenn Sie ein in Google Cloud eingebundener SaaS-Anbieter sind, können Sie Anfragen zur Kontingenterhöhung über ein anderes kundenseitiges Portal als die Google Cloud Console erhalten. Diese Anfragen müssen zur Verarbeitung an Google Cloud weitergeleitet werden. Die Cloud Quotas API kann Kundenanfragen automatisch weiterleiten.
Versionsverwaltung für die Clientkonfiguration aktivieren
Die Cloud Quotas API ist deklarativ. Sie können Kontingentkonfigurationen als Code behandeln und Konfigurationen in Ihrem eigenen versionierten System für Verlauf und Rollback speichern.

Beschränkungen

Die Cloud Quotas API unterliegt den folgenden Einschränkungen:

  • Die API unterstützt das Google Cloud CLI nicht.

  • Die API unterstützt keine Anfragen zur Kontingenterhöhung für Kontingente auf Ordner- und Organisationsebene.

Dienstendpunkt

Ein Dienstendpunkt ist eine Basis-URL, die die Netzwerkadresse eines API-Dienstes angibt. Ein Dienst kann mehrere Endpunkte haben. Der Cloud Quotas API-Dienst hat den folgenden Endpunkt und alle URIs beziehen sich auf ihn:

https://cloudquotas.googleapis.com

Erforderliche Rollen

Um die Berechtigungen zu erhalten, die Sie benötigen, um auf cloudquotas_quotaPreferences und cloudquotas_quotaInfos Ressourcen zuzugreifen, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Cloud-Kontingente-Administrator (cloudquotas.admin) für das Projekt zuzuweisen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die für den Zugriff auf die Ressourcen cloudquotas_quotaPreferences und cloudquotas_quotaInfos erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind für den Zugriff auf die Ressourcen cloudquotas_quotaPreferences und cloudquotas_quotaInfos erforderlich:

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

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

API-Ressourcenmodell

Das Cloud Quotas API-Ressourcenmodell besteht aus zwei Ressourcen: QuotaPreference und QuotaInfo.

Kontingentpräferenz

Die Ressource QuotaPreference steht für Ihre Kontingenteinstellung für eine bestimmte Dimensionskombination. Verwenden Sie diese Ressource, um die Kontingente in Ihren Projekten, Ordnern oder Organisationen anzupassen.

Bevorzugten Wert für eine Region festlegen

Das folgende Beispiel zeigt eine QuotaPreference-Ressource in einer CreateQuotaPreference-Methode.

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

Der preferredValue von 100 gibt an, dass der Anforderer möchte, dass das Kontingent GPUS-PER-GPU-FAMILY-per-project-region auf diesen Wert gesetzt wird. Das Feld „Dimensionen“ gibt an, dass die Einstellung nur für die Region us-central1 gilt.

Zugewiesenen Wert prüfen

Das folgende Beispiel zeigt eine QuotaPreference-Ressource in einer GetQuotaPreference-Methode.

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

Diese Ausgabe enthält die folgenden Werte:

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

Die Antwort zeigt ein grantedValue von 100, was bedeutet, dass der preferredValue aus dem vorherigen Beispiel genehmigt und erfüllt wurde. Einstellungen für verschiedene Dimensionen sind unterschiedliche QuotaPreference-Ressourcen. Beispielsweise sind QuotaPreference für CPU in den Regionen us-central1 und us-east1 zwei unterschiedliche Ressourcen.

Kontingentpräferenz ist erforderlich

QuotaPreference-Ressourcen werden verwendet, um Ihren bevorzugten Wert für ein bestimmtes Kontingent anzugeben. Der aktuelle Wert für ein bestimmtes Kontingent basiert auf:

  • QuotaPreference Anfragen von Ihnen.

  • Von Google Cloud genehmigte Anfragen zur Kontingenterhöhung.

  • Änderungen an Kontingenten, die von Google Cloud initiiert werden.

Das Löschen eines QuotaPreference wird nicht unterstützt. Sie können jedoch einen bevorzugten Kontingentwert festlegen, der niedriger als der von Google Cloud genehmigte Wert ist, um weitere Leitlinien hinzuzufügen.

Weitere Informationen zur Ressource QuotaPreference finden Sie in der Referenz zur Cloud Quotas API.

Weitere Informationen zu den QuotaPreference-Abfragen finden Sie unter Häufige Anwendungsfälle implementieren.

Kontingentinformationen

QuotaInfo ist eine schreibgeschützte Ressource, die Informationen zu einem bestimmten Kontingent für ein bestimmtes Projekt, einen Ordner oder eine Organisation bereitstellt. Es zeigt Informationen aus den von Google Cloud-Diensten definierten Kontingenten und alle erfüllten Kontingentanpassungen an, die von Kunden initiiert wurden. Die Ressource QuotaInfo enthält Informationen wie Metadaten, Containertyp und Dimension.

Unterschiedliche Kontingentwerte nach Region festlegen

Das folgende Beispiel für eine QuotaInfo-Ressource zeigt, dass das CPU-Kontingent für das Projekt 200 für die Region us-central1 und 100 für alle anderen Regionen beträgt.

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

Diese Ausgabe enthält die folgenden Werte:

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

Globales Kontingent festlegen

Das folgende Beispiel für eine QuotaInfo-Ressource zeigt ein Ratenkontingent mit einem Aktualisierungsintervall pro Minute. Die Dimensionen sind leer, d. h., es handelt sich um ein globales Kontingent. Alle Kontingente ohne Regions- oder Zonendimension sind global.

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

Diese Ausgabe enthält die folgenden Werte:

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

Weitere Informationen zur Ressource QuotaInfo finden Sie in der Referenz zur Cloud Quotas API.

Weitere Informationen zu QuotaPreference-Abfragen finden Sie unter Häufige Anwendungsfälle implementieren.

Ressourcennamen

Ressourcen sind benannte Entitäten und werden durch Ressourcennamen identifiziert. Ressourcennamen werden in allen Anfragen und Antworten verwendet und jede Ressource muss einen eigenen eindeutigen Ressourcennamen haben. Jeder Ressourcenname wird durch eine Reihe von Feldern codiert.

Ressource für Kontingentpräferenz

Die Namenskonvention für eine QuotaPreference-Ressource verwendet das folgende Muster:

projects/PROJECT_NUMBER/locations/global/quotaPreferences/QUOTA_PREFERENCE_ID

Sie können quotaPreferenceId beim Erstellen einer Kontingenteinstellung festlegen. Andernfalls wird eine ID generiert. Es wird empfohlen, den Dienstnamen, die Kontingent-ID, den Standort und andere Dimensionen über ein quotaPreferenceId-Benennungsschema zu codieren. Die quotaPreferenceId muss für das Projekt, den Ordner oder die Organisationen eindeutig sein.

Beispiel: quotaPreference Ein Muster zum Codieren Ihrer Kontingentpräferenz-ID sieht so aus: 

SERVICE_LOCATION_DIMENSION1-VALUES-IN-ORDER

Das folgende Beispiel veranschaulicht dieses Muster: 

compute_us-central1_nvidia-200

Bei einem Ressourcennamen sollten Sie die Methode GET verwenden, um eine QuotaPreference abzurufen. Sie können auch die Methode UPDATE mit aktivierter Option allow_missing aufrufen, um ein QuotaPreference zu erstellen oder zu aktualisieren.

Ressource für Kontingentinformationen

Die Namenskonvention für eine QuotaInfo-Ressource verwendet das folgende Muster:

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

Dimensionspriorität

Einige Anwendungsfälle für die Cloud Quotas API haben komplexe Dimensionskonfigurationen. Kontingente können auf einer detaillierteren Ebene konfiguriert werden als nur Regionen und Zonen. Sie können diesen Detaillierungsgrad erreichen, wenn Sie dienstspezifische Dimensionen verwenden. Beispiel: gpu_family und network_id sind dienstspezifische Dimensionen im Compute Engine-Dienst. Dimensionen werden von jedem einzelnen Dienst definiert und jeder Dienst kann einen anderen Satz von dienstspezifischen Dimensionen haben.

Bei der Arbeit mit Standortdimensionen oder dienstspezifischen Dimensionen gilt die folgende Priorität:

  1. Eine Kontingenteinstellungskonfiguration mit allen angegebenen standort- und dienstspezifischen Dimensionen hat Vorrang vor allen anderen Konfigurationen.

  2. Konfigurationen, die Standortdimensionen angeben, haben nur Vorrang vor Konfigurationen, die nur dienstspezifische Dimensionen enthalten.

Dimensionen kombinieren

In einer Konfiguration der Kontingenteinstellung können Sie Dimensionen so kombinieren:

  1. Die Konfiguration kann sowohl Standortdimensionen als auch dienstspezifische Dimensionen enthalten. Dies ist die höchste Reihenfolge.

  2. Die Konfiguration darf nur Standortdimensionen enthalten. Diese Konfiguration gilt für alle dienstspezifischen Dimensionen, mit Ausnahme der explizit mit Methode 1 konfigurierten Dimensionen.

  3. Die Konfiguration darf nur dienstspezifische Dimensionen enthalten. Diese Konfiguration gilt für alle Standorte mit Ausnahme der Standorte, die explizit mit Methode 1 oder 2 konfiguriert wurden.

  4. Wenn die Konfiguration beliebige dienstspezifische Dimensionen enthält, muss sie alle dienstspezifischen Dimensionen enthalten.

  5. Sie können Konfigurationen ohne Dimensionen haben. Solche Konfigurationen gelten für alle Standorte und alle dienstspezifischen Dimensionen, mit Ausnahme der explizit konfigurierten.

Nächste Schritte