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:

In dieser Anleitung verwenden wir eine Umgebungsvariable PROJECT_NUMBER, die auf eine Projektnummer festgelegt ist, die Sie besitzen, und den Dienst serviceusage.googleapis.com als den Dienst von Interesse.

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.

Wenn Sie ein Limit überschreiben möchten, verwenden Sie zuerst eine der oben genannten Methoden, um das gewünschte Kontingentlimit zu ermitteln. Anschließend erstellen Sie mithilfe des Namensfelds eine neue Nutzerüberschreibung in der Sammlung der Überschreibungen für dieses Limit. 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 die neu erstellte Überschreibungsressource. Wenn der Vorgang fehlschlägt, enthält die Antwortnachricht done: true, jedoch 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. Beispielsweise wird ein Limit mit der Einheit "1/{project}/{region}" für jede Region erzwungen. Wenn Sie eine Überschreibung auf ein solches Limit anwenden, wird das Basiskontingent für jede Region oder Zone geändert. Wenn Sie das Kontingent nur für eine bestimmte Region oder Zone ändern möchten, fügen Sie beim Erstellen der Überschreibung eine Kontingentdimension über das Feld dimensions hinzu. 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 die Änderung einer Kontingentüberschreibung dazu führen würde, dass das erzwungene Kontingent um mehr als 10 % sinkt, wird der Anruf als Sicherheitsmaßnahme abgelehnt, um zu vermeiden, dass das Kontingent versehentlich zu schnell sinkt. Wenn Sie diese Einschränkung ignorieren möchten, verwenden Sie das Flag force. Hier ist beispielsweise ein Aufruf zur Erstellung, der das Flag "force" annimmt:

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