die API zur Verwendung eines API-Schlüssels konfiguriert haben. 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.
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.
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 sind von dem Backend abhängig, auf dem Ihre API bereitgestellt wird.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis page details the process of configuring quotas for APIs using OpenAPI, ensuring control over API usage.\u003c/p\u003e\n"],["\u003cp\u003eConfiguring quotas involves adding \u003ccode\u003ex-google-management.metrics\u003c/code\u003e, \u003ccode\u003ex-google-management.quota.limits\u003c/code\u003e, and \u003ccode\u003ex-google-quota.metricCosts\u003c/code\u003e sections to your \u003ccode\u003eopenapi.yaml\u003c/code\u003e file to define metrics, limits, and method costs.\u003c/p\u003e\n"],["\u003cp\u003eTo apply quotas, you must define metrics and their display names, set per-minute, per-project limits, and map these limits to specific methods within your OpenAPI document.\u003c/p\u003e\n"],["\u003cp\u003eImplementing quotas requires deploying both the modified \u003ccode\u003eopenapi.yaml\u003c/code\u003e configuration file and the Extensible Service Proxy (ESP) to Service Management.\u003c/p\u003e\n"],["\u003cp\u003eThe current version is in Beta, and has limited support.\u003c/p\u003e\n"]]],[],null,["# Configuring quotas\n\nOpenAPI \\| [gRPC](/endpoints/docs/grpc/quotas-configure \"View this page for the Cloud Endpoints gRPC docs\")\n\n\u003cbr /\u003e\n\n|\n| **Beta**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis page describes how to configure quotas for your API. At a high level, the\nsteps are:\n\n1. Add the information about the quota to your OpenAPI configuration file.\n2. Deploy your OpenAPI configuration file.\n3. Deploy the Extensible Service Proxy (ESP).\n\nFor an overview of the functionality provided by quotas, see\n[About quotas](/endpoints/docs/openapi/quotas-overview).\n\nPrerequisites\n-------------\n\nAs a starting point, this page assumes that you have:\n\n- [Configured Cloud Endpoints](/endpoints/docs/openapi/configure-endpoints)\n- [Deployed the Endpoints configuration](/endpoints/docs/openapi/deploy-endpoints-config).\n- [Deployed the API backend](/endpoints/docs/openapi/deploy-api-backend).\n- Configured your API to use an API key. This is needed for Endpoints to identify the Google Cloud project that the calling application is associated with. See [Sharing APIs protected by API key](/endpoints/docs/openapi/restricting-api-access-with-api-keys#sharing_apis_protected_by_api_key) for more information.\n\nAdding a quota to your OpenAPI document\n---------------------------------------\n\nThe following procedure describes adding the required extensions to your OpenAPI\ndocument to set up quotas. For simplicity, this page refers to the\nOpenAPI document as the `openapi.yaml` file and provides the OpenAPI extensions\nonly in YAML format.\n\nYou add the following three sections to the `openapi.yaml` file:\n\n- `x-google-management.metrics`: A named metric that counts requests to your\n API. You provide a name that describes the counter. The name can be a\n category, such as `read-requests` or `write-requests`. Alternatively, if you\n are defining a quota for a specific method, you might want to include the\n method name, for example, `echo-api/echo_requests`\n\n- `x-google-management.quota.limits`: Represents a single enforceable limit on\n a named metric. This is where you configure the allowed number of requests\n for a metric that you have defined. Currently, only per-minute, per-project\n limits are supported.\n\n- `x-google-quota.metricCosts`: The `metricCosts` maps methods to metrics\n (many-to-many). A request to a method allocates a counter for each of the\n mapped metrics. When you associate a method with a metric, you always\n specify a cost for the request. You can configure the cost of each method\n independently. This allows different methods to consume at different rates\n from the same named metric. If you don't have a complex quota requirement,\n you can configure the cost of every metric to 1.\n\nTo configure quotas on your API:\n\n1. Open your project's `openapi.yaml` file in a text editor.\n2. If you don't already have it, add the `x-google-management` extension at the root of the file (not indented or nested) before the section that defines the paths.\n3. Add the `metrics` definition indented under `x-google-management`.\n\n ```\n x-google-management:\n metrics:\n - name: \"YOUR_METRIC_NAME\"\n displayName: \"YOUR_METRIC-DISPLAY_NAME\"\n valueType: INT64\n metricKind: DELTA\n ```\n - Replace \u003cvar translate=\"no\"\u003eYOUR_METRIC_NAME\u003c/var\u003e with a name that describes the API requests counter.\n - Replace \u003cvar translate=\"no\"\u003eYOUR_METRIC_DISPLAY_NAME\u003c/var\u003e with the text that is displayed on the **Endpoints** \\\u003e **Services** \\\u003e **Quotas** page to identify the metric.\n - The `valueType` field must be `INT64`.\n - The `metricKind` field must be `DELTA`.\n4. Add a `quota` field at the same level as `metrics`, and add a `limits`\n field nested within the `quota` section.\n\n ```\n quota:\n limits:\n - name: \"YOUR_LIMIT_NAME\"\n metric: \"YOUR_METRIC_NAME\"\n unit: \"1/min/{project}\"\n values:\n STANDARD: VALUE_FOR_THE_LIMIT\n ```\n - Replace \u003cvar translate=\"no\"\u003eYOUR_LIMIT_NAME\u003c/var\u003e with a name that describes the limit.\n - Replace \u003cvar translate=\"no\"\u003eYOUR_METRIC_NAME\u003c/var\u003e with a previously defined `metric.name`.\n - The `unit` field must be `\"1/min/{project}\"`. This is the identifier for the per-minute per-project limit.\n - The `values` field must contain `STANDARD`.\n - Replace \u003cvar translate=\"no\"\u003eVALUE_FOR_THE_LIMIT\u003c/var\u003e with an integer value. This is the number of requests that an application associated with a consumer's Google Cloud project can make in a minute.\n5. Optionally, define additional metrics and limits for each metric.\n\n6. In the `paths` section of the `openapi.yaml` file, add the `x-google-quota`\n extension indented under each method that you want to apply a quota to.\n\n ```\n x-google-quota:\n metricCosts:\n YOUR_METRIC_NAME: YOUR_METRIC_COST\n ```\n - Replace \u003cvar translate=\"no\"\u003eYOUR_METRIC_NAME\u003c/var\u003e with a previously defined `metric.name`.\n - Replace \u003cvar translate=\"no\"\u003eYOUR_METRIC_COST\u003c/var\u003e with an integer. For each request, the request counter for the metric is incremented by the number you specify for the cost.\n7. Save the `openapi.yaml` file.\n\n### Quota configuration examples\n\nThe following three examples show how to configure quotas on your API.\n\nThe following example shows how to configure the `metric` field: \n\n```text\nx-google-management:\n metrics:\n # Define a metric for read requests.\n - name: \"read-requests\"\n displayName: \"Read requests\"\n valueType: INT64\n metricKind: DELTA\n```\n\nThe following example shows how to configure the `quota` and `limits` fields\nwithin the `quota` section: \n\n```text\nx-google-management:\n metrics:\n # Define a metric for read requests.\n - name: \"read-requests\"\n displayName: \"Read requests\"\n valueType: INT64\n metricKind: DELTA\n quota:\n limits:\n # Define the limit or the read-requests metric.\n - name: \"read-limit\"\n metric: \"read-requests\"\n unit: \"1/min/{project}\"\n values:\n STANDARD: 1000\n```\n\nThe following example shows how to configure the `x-google-quota` extension in\nthe `paths` section: \n\n```scdoc\nx-google-management:\n metrics:\n # Define a metric for read requests.\n - name: \"read-requests\"\n displayName: \"Read requests\"\n valueType: INT64\n metricKind: DELTA\n quota:\n limits:\n # Define the limit or the read-requests metric.\n - name: \"read-limit\"\n metric: \"read-requests\"\n unit: \"1/min/{project}\"\n values:\n STANDARD: 1000\npaths:\n \"/echo\":\n post:\n description: \"Echo back a given message.\"\n operationId: \"echo\"\n produces:\n - \"application/json\"\n responses:\n 200:\n description: \"Echo\"\n schema:\n $ref: \"#/definitions/echoMessage\"\n parameters:\n - description: \"Message to echo\"\n in: body\n name: message\n required: true\n schema:\n $ref: \"#/definitions/echoMessage\"\n x-google-quota:\n metricCosts:\n \"read-requests\": 1\n security:\n - api_key: []\n```\n\nSee [OpenAPI extensions](/endpoints/docs/openapi/openapi-extensions)\nfor more examples and detailed descriptions of the `x-google-management` and\n`x-google-quota` extensions.\n\nDeploying the `openapi.yaml` file and the ESP\n---------------------------------------------\n\nFor the quota to take effect, you must:\n\n1. Deploy the `openapi.yaml` file to Service Management, which updates the configuration in Endpoints.\n2. Deploy the ESP. The steps for deploying the ESP vary by the backend that your API is deployed on.\n\nFor detailed steps, see [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend)."]]
