Kontingente konfigurieren

OpenAPI | gRPC

Auf dieser Seite wird beschrieben, wie Sie Kontingente für Ihre API konfigurieren. Auf übergeordneter Ebene sind folgende Schritte erforderlich:

Fügen Sie die Informationen zum Kontingent Ihrer OpenAPI-Konfigurationsdatei hinzu.
Stellen Sie Ihre OpenAPI-Konfigurationsdatei bereit.
Stellen Sie den Extensible Service Proxy (ESP) bereit.

Eine Übersicht über die Funktionalität von Kontingenten finden Sie unter Über Kontingente.

Vorbereitung

Sie sollten Folgendes bereits haben:

Vollständige Konfiguration für Cloud Endpoints
Bereitgestellte Endpoints-Konfiguration.
Bereitgestelltes API-Back-End
Konfigurierte API zur Verwendung eines API-Schlüssels Das wird von Endpoints benötigt, um das Google Cloud-Projekt zu identifizieren, dem die aufrufende Anwendung zugeordnet ist. Weitere Informationen finden Sie unter Durch einen API-Schlüssel geschützte APIs freigeben.

Kontingent dem OpenAPI-Dokument hinzufügen

In dieser Anleitung wird erläutert, wie Sie Ihrer OpenAPI-Konfigurationsdatei die erforderlichen Erweiterungen zum Konfigurieren von Kontingenten hinzufügen. Der Einfachheit halber wird das OpenAPI-Dokument auf dieser Seite als openapi.yaml-Datei bezeichnet und enthält die OpenAPI-Erweiterungen nur im YAML-Format.

Sie fügen der Datei openapi.yaml die folgenden drei Abschnitte hinzu:

x-google-management.metrics: Ein benannter Messwert, der die Zahl der Anfragen an die API ermittelt. Der von Ihnen vergebene Name soll den Zähler beschreiben. Der Name kann eine Kategorie sein, z. B. read-requests oder write-requests. Wenn Sie ein Kontingent für eine bestimmte Methode definieren, können Sie auch den Methodennamen einbeziehen, z. B. echo-api/echo_requests.
x-google-management.quota.limits: Stellt ein einzelnes durchsetzbares Limit für einen benannten Messwert dar. Hier konfigurieren Sie die zulässige Zahl der Anfragen für einen von Ihnen definierten Messwert. Derzeit werden nur Limits pro Minute und Projekt unterstützt.
x-google-quota.metricCosts: metricCosts ordnet Messwerten Methoden zu (m:n-Beziehung). Eine Anfrage an eine Methode weist für jeden der zugeordneten Messwerte einen Zähler zu. Beim Verknüpfen einer Methode mit einem Messwert müssen immer Kosten für die Anfrage definiert werden. Sie können die Kosten für jede Methode einzeln konfigurieren. So können verschiedene Methoden denselben benannten Messwert zu unterschiedlichen Preisen nutzen. Wenn Ihre Kontingentanforderungen nicht allzu komplex sind, können Sie die Kosten für alle Messwerte auf 1 festlegen.

So konfigurieren Sie Kontingente für Ihre API:

Öffnen Sie die openapi.yaml-Datei Ihres Projekts in einem Texteditor.
Wenn Sie es noch nicht getan haben, fügen Sie die x-google-management-Erweiterung im Rootverzeichnis der Datei (nicht eingerückt oder verschachtelt) oberhalb des Bereichs ein, in dem die Pfade definiert sind.
Fügen Sie die metrics-Definition eingerückt unter x-google-management hinzu.
```
x-google-management:
  metrics:
    - name: "YOUR_METRIC_NAME"
      displayName: "YOUR_METRIC-DISPLAY_NAME"
      valueType: INT64
      metricKind: DELTA
```
- Ersetzen Sie YOUR_METRIC_NAME durch einen Namen, der den API-Anfragezähler beschreibt.
- Ersetzen Sie YOUR_METRIC_DISPLAY_NAME durch den Text, der auf der Seite Endpoints > Dienste > Kontingente angezeigt wird, um den Messwert anzugeben.
- Das Feld valueType muss INT64 lauten.
- Das Feld metricKind muss DELTA lauten.
Fügen Sie das Feld quota auf der gleichen Ebene wie metrics und das Feld limits verschachtelt im Abschnitt quota ein:
```
quota:
  limits:
    - name: "YOUR_LIMIT_NAME"
      metric: "YOUR_METRIC_NAME"
      unit: "1/min/{project}"
      values:
        STANDARD: VALUE_FOR_THE_LIMIT
```
- Ersetzen Sie YOUR_LIMIT_NAME durch einen Namen, der das Limit beschreibt.
- Ersetzen Sie YOUR_METRIC_NAME durch einen zuvor definierten metric.name.
- Das Feld unit muss "1/min/{project}" lauten. Das ist die Kennzeichnung für das Limit "Pro Minute pro Projekt".
- Das Feld values muss STANDARD enthalten.
- Ersetzen Sie VALUE_FOR_THE_LIMIT durch eine Ganzzahl. Das ist die Anzahl der Anfragen, die eine mit einem Google Cloud-Nutzerprojekt verknüpfte Anwendung in einer Minute senden kann.
Definieren Sie optional weitere Messwerte und Limits für jeden Messwert.
Im Abschnitt paths der Datei openapi.yaml fügen Sie die Erweiterung x-google-quota eingerückt unter jeder Methode hinzu, auf die Sie ein Kontingent anwenden möchten.
```
x-google-quota:
  metricCosts:
    YOUR_METRIC_NAME: YOUR_METRIC_COST
```
- Ersetzen Sie YOUR_METRIC_NAME durch einen zuvor definierten metric.name.
- Ersetzen Sie YOUR_METRIC_COST durch eine Ganzzahl. Der Anfragezähler des Messwerts wird bei jeder Anfrage um die Zahl erhöht, die Sie für die Kosten angeben.
Speichern Sie die Datei openapi.yaml.

Beispiele für die Kontingentkonfiguration

Die folgenden drei Beispiele zeigen, wie Sie in Ihrer API Kontingente konfigurieren.

Das folgende Beispiel zeigt, wie das Feld metric konfiguriert wird:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA

Das folgende Beispiel zeigt, wie die Felder quota und limits im Abschnitt quota konfiguriert werden:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000

Das folgende Beispiel zeigt, wie die Erweiterung x-google-quota im Abschnitt paths konfiguriert wird:

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Define the limit or the read-requests metric.
      - name: "read-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 1000
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          "read-requests": 1
      security:
      - api_key: []

Unter OpenAPI-Erweiterungen finden Sie weitere Beispiele und detaillierte Beschreibungen der Erweiterungen x-google-management und x-google-quota.

`openapi.yaml`-Datei und ESP bereitstellen

Damit das Kontingent wirksam wird, müssen Sie diese Schritte ausführen:

Stellen Sie die openapi.yaml-Datei für Service Management bereit, wodurch die Konfiguration in Endpoints aktualisiert wird.
Stellen Sie den ESP bereit. Die Schritte zum Bereitstellen des ESP variieren je nach Back-End, auf dem die API bereitgestellt wird.

Ausführliche Schritte finden Sie unter API-Backend bereitstellen.