API 키를 사용하도록 API 구성. 이 작업은 Endpoints가 호출 애플리케이션과 연결된 Google Cloud 프로젝트를 식별하기 위해 필요합니다. 자세한 내용은 API 키로 보호되는 API 공유를 참조하세요.
OpenAPI 문서에 할당량 추가
다음 절차는 OpenAPI 문서에 필요한 확장 프로그램을 추가하여 할당량을 설정하는 방법을 설명합니다. 편의를 위해 이 페이지에서는 OpenAPI 문서를 openapi.yaml 파일로 지칭하고 YAML 형식의 OpenAPI 확장 프로그램만 제공합니다.
다음 3개 섹션을 openapi.yaml 파일에 추가합니다.
x-google-management.metrics: API 요청 수를 계산하는 명명된 측정항목입니다. 카운터를 설명하는 이름을 지정하세요. 이 이름은 read-requests 또는 write-requests와 같은 카테고리일 수 있습니다. 또는 특정 메서드에 대한 할당량을 정의할 경우 메서드 이름을 포함할 수 있습니다(예: echo-api/echo_requests).
x-google-management.quota.limits: 명명된 측정항목에 적용 가능한 단일 한도를 나타냅니다. 여기에서는 정의한 측정항목의 허용 요청 수를 구성합니다. 현재는 프로젝트당 분 단위 한도만 지원됩니다.
x-google-quota.metricCosts: metricCosts는 메서드를 측정항목에 매핑합니다(다대다). 메서드에 요청하면 매핑된 측정항목마다 카운터가 할당됩니다. 메서드를 측정항목과 연결할 때는 항상 요청에 대한 비용을 지정합니다. 각 메서드 비용을 독립적으로 구성할 수 있습니다. 이를 통해 서로 다른 메서드가 동일 측정항목에서 서로 다른 가격으로 소비할 수 있습니다. 할당량을 복잡하게 구성할 필요가 없는 경우에는 모든 측정항목 비용을 1로 구성할 수 있습니다.
API에서 할당량을 구성하려면 다음을 따르세요.
텍스트 편집기에서 프로젝트의 openapi.yaml 파일을 엽니다.
아직 추가하지 않았으면 경로를 정의하는 섹션 앞에 있는 파일(들여쓰기 또는 중첩되지 않은)의 루트에 x-google-management 확장 프로그램을 추가합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 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)."]]
