Mengonfigurasi API Anda untuk menggunakan kunci API. Hal ini diperlukan agar
Endpoints dapat mengidentifikasi project Google Cloud
yang terkait dengan aplikasi yang melakukan panggilan. Lihat
Membagikan API yang dilindungi oleh kunci API
untuk mengetahui informasi selengkapnya.
Menambahkan kuota ke dokumen OpenAPI
Prosedur berikut menjelaskan cara menambahkan ekstensi yang diperlukan ke dokumen OpenAPI
untuk menyiapkan kuota. Agar lebih sederhana, halaman ini menyebut dokumen OpenAPI sebagai file openapi.yaml dan menyediakan ekstensi OpenAPI hanya dalam format YAML.
Anda menambahkan tiga bagian berikut ke file openapi.yaml:
x-google-management.metrics: Metrik bernama yang menghitung permintaan ke
API Anda. Anda memberikan nama yang mendeskripsikan penghitung. Nama dapat berupa
kategori, seperti read-requests atau write-requests. Atau, jika Anda
menentukan kuota untuk metode tertentu, Anda dapat menyertakan
nama metode, misalnya, echo-api/echo_requests
x-google-management.quota.limits: Merepresentasikan satu batas yang dapat diterapkan pada
metrik bernama. Di sinilah Anda mengonfigurasi jumlah permintaan yang diizinkan
untuk metrik yang telah Anda tentukan. Saat ini, hanya batas per menit, per project yang didukung.
x-google-quota.metricCosts: Metode peta metricCosts ke metrik
(banyak-ke-banyak). Permintaan ke suatu metode mengalokasikan penghitung untuk setiap metrik yang dipetakan. Saat mengaitkan metode dengan metrik, Anda selalu
menentukan biaya untuk permintaan. Anda dapat mengonfigurasi biaya setiap metode secara terpisah. Hal ini memungkinkan berbagai metode untuk menggunakan metrik bernama yang sama dengan kecepatan yang berbeda. Jika tidak memiliki persyaratan kuota yang kompleks,
Anda dapat mengonfigurasi biaya setiap metrik menjadi 1.
Untuk mengonfigurasi kuota di API Anda:
Buka file openapi.yaml project Anda di editor teks.
Jika Anda belum memilikinya, tambahkan ekstensi x-google-management di
root file (tidak diindentasi atau bertingkat) sebelum bagian yang menentukan
jalur.
Tambahkan definisi metrics yang diindentasi di bawah x-google-management.
Ganti YOUR_LIMIT_NAME dengan nama yang menjelaskan batas.
Ganti YOUR_METRIC_NAME dengan metric.name yang ditentukan sebelumnya.
Kolom unit harus berupa "1/min/{project}". Ini adalah ID untuk
batas per menit per project.
Kolom values harus berisi STANDARD.
Ganti VALUE_FOR_THE_LIMIT dengan nilai bilangan bulat.
Ini adalah jumlah permintaan yang dapat dibuat oleh aplikasi yang terkait dengan
project konsumen Google Cloud dalam satu menit.
Secara opsional, tentukan metrik dan batas tambahan untuk setiap metrik.
Di bagian paths file openapi.yaml, tambahkan ekstensi x-google-quota
yang diindentasi di setiap metode yang ingin Anda terapkan kuotanya.
Ganti YOUR_METRIC_NAME dengan metric.name yang ditentukan sebelumnya.
Ganti YOUR_METRIC_COST dengan bilangan bulat. Untuk
setiap permintaan, penghitung permintaan untuk metrik akan bertambah sesuai
dengan jumlah yang Anda tentukan untuk biaya.
Simpan file openapi.yaml.
Contoh konfigurasi kuota
Tiga contoh berikut menunjukkan cara mengonfigurasi kuota di API Anda.
Contoh berikut menunjukkan cara mengonfigurasi kolom metric:
x-google-management:
metrics:
# Define a metric for read requests.
- name: "read-requests"
displayName: "Read requests"
valueType: INT64
metricKind: DELTA
Contoh berikut menunjukkan cara mengonfigurasi kolom quota dan limits dalam bagian quota:
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
Contoh berikut menunjukkan cara mengonfigurasi ekstensi x-google-quota di bagian paths:
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: []
Lihat ekstensi OpenAPI
untuk contoh lainnya dan deskripsi mendetail tentang ekstensi x-google-management dan
x-google-quota.
Men-deploy file openapi.yaml dan ESP
Agar kuota berlaku, Anda harus:
Deploy file openapi.yaml ke Pengelolaan Layanan, yang memperbarui
konfigurasi di Endpoint.
Deploy ESP. Langkah-langkah untuk men-deploy ESP
berbeda-beda bergantung pada backend tempat API Anda di-deploy.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)."]]
