Kontingentprojekt festlegen

Auf dieser Seite wird beschrieben, wie Sie ein Kontingentprojekt für Ihre clientbasierten APIs festlegen. Informationen zum Kontingentprojekt, zum Festlegen der Kontingent-API und zur Bestimmung des Kontingentprojekts finden Sie unter Informationen zum Kontingentprojekt.

Wenn Sie eine Anfrage an eine clientbasierte API senden und ein Kontingentprojekt nicht identifiziert werden kann, schlägt die Anfrage fehl.

Das Kontingentprojekt kann auf verschiedene Arten festgelegt werden. Das Projekt wird durch Prüfung der folgenden Optionen verifiziert. Die aufgeführte Reihenfolge ist die Reihenfolge ihrer Priorität.

  • Das in der Umgebung oder der Anfrage festgelegte Kontingentprojekt.
  • Wenn Sie einen API-Schlüssel verwenden, um Anmeldedaten für eine Anfrage bereitzustellen, wird das mit dem API-Schlüssel verknüpfte Projekt als Kontingentprojekt verwendet.
  • Wenn Sie die Google Cloud CLI zum Abrufen Ihres Zugriffstokens verwenden und sich mit Ihren Nutzeranmeldedaten bei der gcloud CLI authentifiziert haben, wird das freigegebene Projekt der gcloud CLI manchmal als Kontingentprojekt verwendet. Nicht alle clientbasierten APIs greifen auf das freigegebene Projekt zurück.
  • Wenn das Hauptkonto für den API-Aufruf ein Dienstkonto ist, auch im Wege der Identitätsübertragung, wird das mit dem Dienstkonto verknüpfte Projekt als Kontingentprojekt verwendet.
  • Wenn das Hauptkonto für die API ein Nutzer der Mitarbeiteridentitätsföderation ist, wird das Nutzerprojekt für Workforce-Pools als Kontingentprojekt verwendet.

Wenn keine der oben genannten Prüfungen ein Kontingentprojekt ergibt, schlägt die Anfrage fehl.

Es gibt mehrere Möglichkeiten, Kontingentprojekte festzulegen. Wenn das Kontingentprojekt durch mehrere Methoden angegeben wird, gilt die folgende Priorität:

  1. Programmatisch
  2. Umgebungsvariable
  3. Zur Authentifizierung der Anfrage verwendete Anmeldedaten

Kontingentprojekt programmatisch festlegen

Sie können das Kontingentprojekt in Ihrer Anwendung explizit festlegen. Diese Methode überschreibt alle anderen Definitionen. Das zur Authentifizierung der Anfrage verwendete Hauptkonto muss die erforderliche Berechtigung für das angegebene Kontingentprojekt haben.

Wie Sie das Kontingentprojekt programmatisch festlegen, hängt davon ab, ob Sie eine Clientbibliothek, die gcloud CLI oder eine REST-Anfrage verwenden.

Clientbibliothek

Sie können den Wert für das Kontingentprojekt mithilfe von Clientoptionen festlegen, wenn Sie den Client erstellen. Diese Methode eignet sich gut, wenn Sie den Wert für Ihr Kontingentprojekt von Ihrer Anwendung aus steuern möchten, unabhängig von der Umgebung, in der sie ausgeführt wird.

Weitere Informationen zum Implementieren von Clientoptionen finden Sie in der Dokumentation zur Clientbibliothek.

gcloud-CLI

Sie können das Kontingentprojekt für alle gcloud CLI-Befehle festlegen. Verwenden Sie dazu das Attribut billing/quota_project in der gcloud CLI-Konfiguration. Sie können das Kontingentprojekt auch für einen bestimmten Befehl mit dem Flag --billing-project festlegen, das Vorrang vor dem Konfigurationsattribut hat.

Weitere Informationen zu Konfigurationen der gcloud CLI finden Sie auf der Referenzseite für die gcloud-Konfiguration. Weitere Informationen zum Flag --billing-project finden Sie in der Referenz zu globalen Flags.

REST-Anfrage

Sie können das Kontingentprojekt in einer REST-Anfrage mit dem Header x-goog-user-project angeben. Das Hauptkonto, das die Anfrage stellt, muss die erforderlichen Berechtigungen für das Kontingentprojekt haben.

Weitere Informationen und Beispielcode finden Sie unter Kontingentprojekt mit einer REST-Anfrage festlegen.

Kontingentprojekt mit einer Umgebungsvariablen festlegen

Clientbibliotheken für einige Sprachen unterstützen das Festlegen des Kontingentprojekts mithilfe einer Umgebungsvariablen. Dieser Ansatz kann nützlich sein, wenn Sie das Kontingentprojekt in verschiedenen Shells unterschiedlich festlegen oder das mit den Anmeldedaten verknüpfte Kontingentprojekt überschreiben möchten. Das Hauptkonto für jede Anfrage muss die erforderlichen Berechtigungen für das Kontingentprojekt haben, das durch die Umgebungsvariable angegeben wird.

Die Umgebungsvariable ist sprachabhängig:

Sprache Umgebungsvariable
C++

GOOGLE_CLOUD_CPP_USER_PROJECT

C#

GOOGLE_CLOUD_QUOTA_PROJECT

Go

GOOGLE_CLOUD_QUOTA_PROJECT

Java

GOOGLE_CLOUD_QUOTA_PROJECT

Node.js

GOOGLE_CLOUD_QUOTA_PROJECT

Python

GOOGLE_CLOUD_QUOTA_PROJECT

PHP

GOOGLE_CLOUD_QUOTA_PROJECT

Ruby Nicht verfügbar

Kontingentprojekt mit Authentifizierungsdaten festlegen

Wenn das Kontingentprojekt nicht angegeben ist, versuchen die Authentifizierungsbibliotheken, es aus den Anmeldedaten zu ermitteln, die für die Anfrage verwendet wurden. Dieser Vorgang hängt vom Typ der Anmeldedaten ab, die zur Authentifizierung der Anfrage verwendet wurden:

  • Dienstkonto: Das mit dem Dienstkonto verknüpfte Projekt wird als Kontingentprojekt verwendet.
  • Nutzeranmeldedaten: In einer lokalen Entwicklungsumgebung findet Standardanmeldedaten für Anwendungen Ihre Nutzeranmeldedaten aus der lokalen ADC-Datei. Diese Datei kann auch ein Kontingentprojekt angeben. Wenn das Projekt in Ihrer Google Cloud CLI-Konfiguration festgelegt ist und Sie die erforderlichen Berechtigungen für dieses Projekt haben, wird das Kontingentprojekt standardmäßig festgelegt, wenn Sie die lokale ADC-Datei erstellen. Sie können das ADC-Kontingentprojekt auch mit dem Befehl auth application-default set-quota-project festlegen.
  • API-Schlüssel: Wenn Sie einen API-Schlüssel verwenden, um Anmeldedaten für eine Anfrage bereitzustellen, wird das mit dem API-Schlüssel verknüpfte Projekt als Kontingentprojekt verwendet.

Erforderliche Berechtigungen zum Festlegen und Verwenden des Kontingentprojekts

Um die Berechtigung zu erhalten, ein Projekt als Kontingentprojekt festzulegen, oder um dieses Kontingentprojekt in einer Anfrage zu verwenden, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Service Usage-Nutzer (roles/serviceusage.serviceUsageConsumer) für das Projekt zu gewähren. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierte Rolle enthält die Berechtigung serviceusage.services.use, die erforderlich ist, um ein Projekt als Kontingentprojekt festzulegen oder um dieses Kontingentprojekt in einer Anfrage zu verwenden.

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

Wenn Sie ein Projekt verwenden, das Sie als Kontingentprojekt erstellt haben, haben Sie die erforderlichen Berechtigungen.

Weitere Informationen zu Berechtigungen finden Sie unter Kontingentberechtigungen.

Kontingentnutzer festlegen

Einige APIs begrenzen auch die Anzahl der Anfragen pro Nutzer, die sich von den Kontingenten pro Projekt unterscheidet, die in vorherigen Abschnitten auf dieser Seite beschrieben wurden.

Standardmäßig verwendet das System das authentifizierte Hauptkonto. Wenn kein authentifiziertes Hauptkonto vorhanden ist, verwendet das System die Client-IP-Adresse.

Wenn Sie den Kontingentnutzer überschreiben müssen, können Sie den Parameter quotaUser über die Systemparameter der Cloud API festlegen. Wenn Sie einen quotaUser oder X-Goog-Quota-User angeben, muss ein gültiger API-Schlüssel mit Einschränkungen für IP-Adressen verwendet werden, um das Kontingentprojekt zu identifizieren. Andernfalls wird der Parameter quotaUser ignoriert.

Weitere Informationen zu Cloud API-Systemparametern und ihren Definitionen finden Sie in der Definitionstabelle für Systemparameter.

Nächste Schritte