Cloud Quotas API – Übersicht

Mit der Cloud Quotas API können Sie Kontingente auf Projektebene programmatisch anpassen und Anfragen zur Kontingentanpassung auf Projektebene automatisieren. Sie können die Cloud Quotas API beispielsweise für Folgendes verwenden:

Kontingentanpassungen automatisieren: Mit der Cloud Quotas API können Sie Kontingentanpassungen basierend auf Ihren eigenen Kriterien anfordern. Um beispielsweise Fehler aufgrund von Kontingentüberschreitungen zu vermeiden, können Sie die API verwenden, um eine Kontingentanpassung programmatisch anzufordern, wenn Compute Engine-Ressourcen 80 % des verfügbaren Kontingents erreichen.
Kontingentkonfigurationen für mehrere Projekte wiederverwenden: Mit der Cloud Quotas API können Sie 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 Cloud Quotas API verwenden, um dies in der Erstellungslogik Ihres Projekts zu automatisieren. Anfragen zur Kontingentanpassung unterliegen der Genehmigung von Google Cloud.
Anfragen zu Kundenkontingenten bearbeiten: Wenn Sie ein in Google Cloud eingebundener SaaS-Anbieter sind, erhalten Sie möglicherweise Anfragen zur Kontingenterhöhung über ein anderes kundenseitiges Portal als die Google Cloud Console. 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

Für Cloud-Kontingente gelten die folgenden Einschränkungen:

Anpassungen der Kontingenterhöhung müssen auf Projektebene vorgenommen werden und unterliegen der Genehmigung von Google Cloud.
You can request quota decrease adjustments for project-, folder-, and auf Organisationsebene.
Die Cloud Quotas API unterstützt nur Vorgänge auf Projektebene. Vorgänge auf Ordner- und Organisationsebene werden nicht unterstützt.

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 auf Projekte, Ordner und Organisationen 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

Das Feld location in einem Ressourcennamen ist immer global. Die Cloud Quotas API ist ein globaler Dienst.

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

Nächste Schritte

Gängige Anwendungsfälle implementieren
Referenz zur Cloud Quotas API
Lernen Sie Kontingente kennen