Dienstkontingente verwalten

Auf dieser Seite wird beschrieben, wie Sie alle Kontingentmesswerte und -beschränkungen in einem Google Cloud-Projekt für einen bestimmten Dienst anzeigen und die Kontingentnutzung für diesen Dienst mithilfe einer Kontingentüberschreibung begrenzen. Mithilfe von Service Usage können Sie das Kontingent für Ihre Projekte für jeden Dienst verwalten, einschließlich öffentlicher Google Cloud-Dienste und privater Dienste, die mit Cloud Endpoints erstellt wurden. Weitere Informationen zu den Unterschieden zwischen öffentlichen und privaten APIs und Diensten finden Sie unter Öffentliche und private Dienste.

Machen Sie sich unbedingt mit dem Dienstkontingentmodell vertraut, um die in dieser Anleitung verwendete Terminologie besser zu verstehen.

Für die meisten praktischen Anwendungsfälle ist die Verwendung der Google Cloud Console die einfachste Möglichkeit, Kontingente zu verwalten. Wenn Sie Programme unter Verwendung der Service Usage API schreiben müssen, empfehlen wir Ihnen, eine der von uns bereitgestellten Clientbibliotheken zu verwenden. Um die API auszuprobieren, ohne gleich eine komplette Entwicklungsumgebung für Anwendungen einzurichten, können Sie die Anleitung in diesem Dokument und den curl-Befehl verwenden. Einige der in dieser Anleitung verlinkten Ressourcen stehen ggf. nur auf Englisch zur Verfügung.

Vorbereitung

Zum Verwalten von Dienstkontingenten benötigen Sie:

Für diese Anleitung verwenden wir eine Umgebungsvariable PROJECT_NUMBER, die auf eine Projektnummer festgelegt ist, die Ihnen gehört, und den Dienst serviceusage.googleapis.com als gewünschten Dienst.

Mit dem folgenden Befehl können Sie die Projektnummer für ein Projekt mit der ID PROJECT_ID, das Ihnen gehört, schnell finden:

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

Dienstkontingent anzeigen

Verwenden Sie den folgenden Befehl, um alle Kontingentmesswerte und -beschränkungen anzuzeigen, die für einen bestimmten Verbraucher eines Dienstes gelten:

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

Der Aufruf antwortet mit einer Liste von Messwerten, die vom Dienst definiert wurden und jeweils eine Liste der Grenzwerte für die für diesen Nutzer geltenden Messwerte, den Werten für diese Limits und etwaigen Überschreibungen liefern. Sie sehen hier ein Beispiel:

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

Jeder Messwert in der Antwort hat ein name-Feld. Verwenden Sie den name in der URL, um die Kontingenteinstellungen nur für diesen Messwert und nicht für alle Messwerte zu überprüfen. In dieser Anleitung speichert die Umgebungsvariable METRIC_RESOURCE_NAME den Ressourcennamen des Kontingentmesswerts:

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}

In ähnlicher Weise hat jedes Limit innerhalb eines Messwerts ein name-feld. Verwenden Sie den name in der URL, um die Kontingenteinstellungen für genau dieses Limit für diesen Messwert und nicht für alle Limits für einen Messwert oder alle Messwerte zu überprüfen. In dieser Anleitung speichert die Umgebungsvariable LIMIT_RESOURCE_NAME den Ressourcennamen des Kontingentlimits:

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}

Überschreibung eines Verbraucherkontingents erstellen

Der Inhaber eines Projekts kann eine Überschreibung durch den Nutzer auf ein bestimmtes Kontingentlimit für dieses Projekt anwenden, um die Gesamtgröße des Kontingents zu verringern, den der Nutzer auf dieses Limit anrechnen kann.

Beachten Sie, dass eine Überschreibung durch den Nutzer das verfügbare Kontingent nicht über das hinaus erhöhen kann, was durch den Dienststandard und vorhandene Überschreibungen durch andere Parteien (z. B. den Dienstinhaber oder den Kontingentadministrator einer Organisation) zulässig ist. Verwenden Sie zum Erhöhen des verfügbaren Kontingents die Option "Kontingente bearbeiten" auf der Kontingent-Hauptseite oder fragen Sie den Organisationsadministrator nach einer Kontingenterhöhung.

Verwenden Sie zum Ermitteln des zu überschreibenden Limits zuerst eine der oben genannten Methoden, um das gewünschte Kontingentlimit zu ermitteln. Verwenden Sie dann das Namensfeld, um eine neue Nutzerüberschreibung in der Sammlung der Überschreibungen für dieses Limit zu erstellen. Das folgende Beispiel bezieht sich auf ein bestimmtes Kontingentlimit:

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

Wenn der Aufruf erfolgreich ist, wird eine Vorgangs-ID zurückgegeben, die die laufende Arbeit auf dem Server darstellt, wenn sich die Kontingentänderung auf Backend-Systeme ausbreitet:

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

Um den Fortschritt des Vorgangs zu überprüfen, verwenden Sie einfach dessen name:

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

Wenn der Vorgang erfolgreich ist, enthält die Antwortnachricht done: true und enthält die neu erstellte Überschreibungsressource. Wenn der Vorgang fehlschlägt, enthält die Antwortnachricht done: true. Sie enthält aber Fehlerdetails anstelle der Ressource.

Sie können auch überprüfen, ob eine Änderung vorgenommen wurde, indem Sie den ursprünglichen "get"-Aufruf für das bestimmte Limit wiederholen. Das Limit sollte jetzt ein zusätzliches consumerOverride-Feld haben.

Regionale oder zonale Kontingentüberschreibungen erstellen

Einige Kontingentlimits gelten pro Region oder Zone. Dies wird durch das Vorhandensein von {region} oder {zone} im Feld unit des Limits angegeben. Beispiel: Das Limit "1/{project}/{region}" wird pro Region erzwungen. Wenn Sie eine Überschreibung auf dieses Limit anwenden, ändert sich das Basiskontingent für jede Region oder Zone. Wenn Sie das Kontingent nur für eine bestimmte Region oder Zone ändern möchten, fügen Sie beim Erstellen der Überschreibung eine Kontingentdimension hinzu. Verwenden Sie dazu das Feld dimensions. Erstellen Sie beispielsweise eine regionale Überschreibung für ein regionales Cloud ML-Kontingentlimit:

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

Überschreibung eines Verbraucherkontingents aktualisieren

Der Inhaber eines Projekts kann auch den Wert einer vorhandenen Überschreibung durch den Nutzer für das Projekt ändern.

Angenommen, ein vorheriger Erstellungsaufruf hat eine Überschreibung mit einem name-Feld wie dem folgenden zurückgegeben:

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

Verwenden Sie dann diesen Namen, um die zu aktualisierende Überschreibung folgendermaßen zu identifizieren:

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

Wenn der Aufruf erfolgreich ist, wird eine Vorgangs-ID zurückgegeben, die die laufende Arbeit auf dem Server darstellt, wenn sich die Kontingentänderung auf Backend-Systeme ausbreitet:

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

Um den Fortschritt des Vorgangs zu überprüfen, verwenden Sie einfach dessen name:

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

Wenn der Vorgang erfolgreich ist, enthält die Antwortnachricht done: true und die aktualisierte Überschreibungsressource. Wenn der Vorgang fehlschlägt, enthält die Antwortnachricht done: true. Sie enthält allerdings Fehlerdetails anstelle der aktualisierten Ressource.

Überschreibung eines Verbraucherkontingents löschen

Der Inhaber eines Projekts kann auch eine Überschreibung durch den Nutzer aus dem Projekt entfernen.

Angenommen, ein vorheriger Erstellungsaufruf hat eine Überschreibung mit einem name-Feld wie dem folgenden zurückgegeben:

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

Führen Sie die folgende Sequenz aus, um die Überschreibung zu löschen:

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

Große Kontingentänderungen erzwingen

Wenn eine Änderung der Kontingentüberschreibung dazu führt, dass das erzwungene Kontingent um mehr als 10 % sinkt, wird der Aufruf als Sicherheitsmaßnahme abgelehnt, um zu verhindern, dass das Kontingent versehentlich zu schnell sinkt. Verwenden Sie das Flag force, um diese Einschränkung zu ignorieren. Hier sehen Sie zum Beispiel einen Aufruf vom Typ „create“, der das Flag „force“ verwendet.

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