API に認証が必要で、Android クライアントをサポートしている場合は必須です。Google ID トークンの場合はクライアント ID のリストであり、これらの ID の代わりにトークンがリクエストされます。トークンの発行元がサードパーティの認証プロバイダ（Auth0 など）である場合は、認証の発行元の名前からオーディエンス リストにマッピングするディクショナリが必要です。詳しくは、許可されたクライアント ID とオーディエンスをご覧ください。
OAuth2 による認証では、OAuth2 トークンは特定のクライアント ID に対して発行されます。つまり、クライアント ID によって API へのアクセスが制限されています。 Google Cloud コンソールで Android アプリケーションを登録するときは、このためのクライアント ID を作ります。このクライアント ID は認証用に Google に対して OAuth2 トークンをリクエストします。バックエンド API が認証によって保護されている場合、OAuth2 アクセス トークンが送信され、App Engine 用 Endpoints Frameworks によって開かれます。このトークンからクライアント ID が抽出され、バックエンドが宣言した、許容可能なクライアント ID のリスト（allowed_client_ids リスト）と比較されます。
allowed_client_ids リストには、ウェブアプリ、Android アプリなどのクライアント アプリに対して Google Cloud console から取得したすべてのクライアント ID を含めます。つまり、API のビルド時にこれらのクライアントを把握しておく必要があります。空のリストを指定した場合、どのクライアントも API にアクセスできません。
適切な認証を確認する各 API メソッドでは、endpoints.get_current_user() を呼び出す必要があります。
詳細については、ユーザーの認証をご覧ください。
allowed_client_ids 引数を使用し、API Explorer を使用して API への認証済み呼び出しをテストするには、そのクライアント ID を allowed_client_ids のリストに指定する必要があります。これには、定数 endpoints.API_EXPLORER_CLIENT_ID を指定します。allowed_client_ids に endpoints.API_EXPLORER_CLIENT_ID のみが含まれた状態で API をデプロイすると、API は一般に検索可能となり、API Explorer でも一般にアクセス可能となることに注意してください。
オーディエンスについて
allowed_client_ids リストは、権限のないクライアントからバックエンド API を保護します。ただし、認証トークンが対象のバックエンド API のみに対して機能するようにクライアントを保護するには、さらなる措置が必要です。Android クライアントの場合は、そのための機能が audiences 引数です。この引数を使用すると、バックエンド API のクライアント ID を指定できます。
Google Cloud コンソール プロジェクトを作成する場合は、作成したプロジェクトで使用するデフォルトのクライアント ID が自動的に作成され、命名されることに注意してください。App Engine にバックエンド API をアップロードするときは、そのクライアント ID が使用されます。これは、API 認証で説明されているウェブ クライアント ID です。
サードパーティの認証トークン発行元
Google ID トークンではなく、サードパーティから発行される認証トークンをアプリケーションで受け入れる場合は、@endpoints.api に audiences と issuers の引数を適切に設定し、このサードパーティ発行元の情報を提供する必要があります。次に例を示します。
audiences、scopes、allowed_client_ids を API 全体に設定するには、@endpoints.api を使用し、メソッドに設定するには @endpoints.method を使用します。これらの設定が API とメソッド両方のレベルで指定された場合は、メソッドの設定が優先します。
API にメソッドを作成するには、@endpoints.method を使って対応する Python のメソッドを修飾し、メソッドの構成方法を設定する引数を指定します。たとえば、使用するリクエストとレスポンスの Message クラスを指定します。
# This ResourceContainer is similar to the one used for get_greeting, but# this one also contains a request body in the form of a Greeting message.MULTIPLY_RESOURCE=endpoints.ResourceContainer(Greeting,times=messages.IntegerField(2,variant=messages.Variant.INT32,required=True),)@endpoints.method(# This method accepts a request body containing a Greeting message# and a URL parameter specifying how many times to multiply the# message.MULTIPLY_RESOURCE,# This method returns a Greeting message.Greeting,path="greetings/multiply/{times}",http_method="POST",name="greetings.multiply",)defmultiply_greeting(self,request):returnGreeting(message=request.message*request.times)
示されたとおりに API を含む path パラメータを追加します。
ResourceContainer に必須の引数がある場合、クライアント リクエストのクエリ文字列（yourApi?times=2 など）または URL パス（yourApi/2 など）にその引数を含める必要があります。ただし、この URL パスを使用して API が引数値を受け取るようにするには、path='yourApi/{times} の引数 {times} に示すように、引数名も API パスに追加する必要があります。
[[["わかりやすい","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\u003eThe \u003ccode\u003e@endpoints.api\u003c/code\u003e decorator is used to define the API, allowing configuration through arguments like \u003ccode\u003ename\u003c/code\u003e, \u003ccode\u003eversion\u003c/code\u003e, \u003ccode\u003eallowed_client_ids\u003c/code\u003e, \u003ccode\u003eaudiences\u003c/code\u003e, and more, which control various aspects such as API name, access, and authentication.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003e@endpoints.method\u003c/code\u003e decorator is used to configure individual API methods, allowing for the specification of \u003ccode\u003ehttp_method\u003c/code\u003e, \u003ccode\u003epath\u003c/code\u003e, \u003ccode\u003eRequest Message\u003c/code\u003e class, \u003ccode\u003eResponse Message\u003c/code\u003e class, \u003ccode\u003eallowed_client_ids\u003c/code\u003e, and \u003ccode\u003eaudiences\u003c/code\u003e, overriding the settings in \u003ccode\u003e@endpoints.api\u003c/code\u003e if necessary.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003eResourceContainer\u003c/code\u003e is utilized when an API method requires path or query string arguments, defining a structure that combines a request body \u003ccode\u003eMessage\u003c/code\u003e class with additional parameters in the URL, while having a \u003ccode\u003epath\u003c/code\u003e parameter in the method that determines how the arguments are received.\u003c/p\u003e\n"],["\u003cp\u003eQuotas can be defined for an API by using the \u003ccode\u003elimit_definitions\u003c/code\u003e argument in \u003ccode\u003e@endpoints.api\u003c/code\u003e, combined with the \u003ccode\u003emetric_costs\u003c/code\u003e argument in \u003ccode\u003e@endpoints.method\u003c/code\u003e, which allows for setting request limits and varying costs per method.\u003c/p\u003e\n"],["\u003cp\u003eFor APIs that require authentication, \u003ccode\u003eallowed_client_ids\u003c/code\u003e specifies the permitted client IDs, while \u003ccode\u003eaudiences\u003c/code\u003e are used to protect clients, primarily Android, by ensuring authentication tokens are intended for the correct backend API, and \u003ccode\u003eissuers\u003c/code\u003e are needed for authentication tokens from a third-party.\u003c/p\u003e\n"]]],[],null,["# Decorators\n\nThe Cloud Endpoints Frameworks for Python decorators describe API configuration,\nmethods, parameters, and other vital details that define the properties and\nbehavior of the Endpoint.\n\nThis page describes the available decorators in detail. For information about\nusing the decorators to create your API, see the following:\n\n- [Creating the API](/endpoints/docs/frameworks/python/create_api)\n- [Creating an API implemented with multiple classes](/endpoints/docs/frameworks/python/create-multi-class-api)\n\nDefining the API (`@endpoints.api`)\n-----------------------------------\n\nYou can supply several arguments to `@endpoints.api` to define\nyour API. The following table describes the available arguments:\n\n### `limit_definitions`\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\nTo define [quotas](/endpoints/docs/frameworks/quotas-overview) for your API,\nyou specify the optional `limit_definitions` argument to `@endpoints.api`. To\nconfigure a quota, you must also:\n\n- Install version 2.4.5 or later of the Endpoints Frameworks library.\n- Add the `metric_costs` argument to the [method decorator](#defining_an_api_method_endpointsmethod) for each method that you want to apply a quota to.\n\nSee [Configuring quotas](/endpoints/docs/frameworks/quotas-configure) for all\nthe steps required to set up a quota.\n\nYou specify a list of one or more `LimitDefinition` instances, similar to the\nfollowing: \n\n quota_limits = [\n endpoints.LimitDefinition(\n \"name\",\n \"Display name\",\n limit)\n ]\n\nEach `LimitDefinition` instance must have the following values:\n\n#### Example\n\n```python\nquota_limits = [\n endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),\n endpoints.LimitDefinition('list-requests', 'List Requests', 100),\n endpoints.LimitDefinition('write-requests', 'Write Requests', 50)\n]\n\n@endpoints.api(name='bookstore',\n version='v1',\n limit_definitions=quota_limits)\n```\n\n### Allowed client IDs and audiences\n\nFor OAuth2 authentication, an OAuth2 token is issued to a specific client ID,\nwhich means that this client ID can be used for restricting access to your APIs.\nWhen you register Android applications in the Google Cloud console,\nyou create a client ID for it. This client ID is the one requesting an OAuth2\ntoken from Google for authentication purposes. When the backend API is protected\nby auth, an OAuth2 access token is sent and opened by Endpoints Frameworks\nfor App Engine, the client ID is extracted from the token, and then the\nID is compared to the backend's declared acceptable client ID list\n(the `allowed_client_ids` list).\n\nThe `allowed_client_ids` list should consist of all the\nclient IDs you have obtained through the [Google Cloud console](https://console.cloud.google.com/) for your web,\n[Android](/endpoints/docs/frameworks/python/consume_android),\nand other client apps. This means that the clients must be known at API\nbuild-time. If you specify an empty list, *no* clients can access the API.\n\nNote that in each API method where you want to check for proper authentication,\nyou must call `endpoints.get_current_user()`.\nSee [Authenticating users](/endpoints/docs/frameworks/python/authenticating-users)\nfor more information.\n\nIf you use the `allowed_client_ids` argument and you want to test authenticated\ncalls to your API by using the API Explorer, you must supply its client ID\nin the list of `allowed_client_ids` by specifying the constant\n`endpoints.API_EXPLORER_CLIENT_ID`. Notice that if `allowed_client_ids` contains\nonly `endpoints.API_EXPLORER_CLIENT_ID`, and you deploy your API, your API is\nstill publicly discoverable and publicly accessible in the API Explorer.\n| **Note:** If you don't use the `allowed_client_ids` argument, you don't need to supply the API Explorer client ID.\n\n#### About audiences\n\n| **Note:** The `audiences` argument is currently used *only for Android clients*.\n\nThe `allowed_client_ids` list *protects the backend API* from unauthorized\nclients. But further protection is needed to *protect the clients* , so that\ntheir authentication token works only for the intended backend API. For Android\nclients, this mechanism is the `audiences` argument, in which you specify the\nclient ID of the backend API.\n\nNote that when you create a Google Cloud console project, a default client ID is\nautomatically created and named for use by the project. When you upload your\nbackend API into App Engine, it uses that client ID. This is the web\nclient ID mentioned in API [auth](/endpoints/docs/frameworks/python/auth).\n\n#### Third-party authentication token issuer\n\nIf your application accepts authentication tokens that aren't Google ID tokens\nand are issued by third-party issuers, you need to properly set `audiences` and\n`issuers` arguments in `@endpoints.api` to provide the information about the\nthird-party issuers. For example: \n\n @endpoints.api(\n audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},\n issuers={'auth0': endpoints.Issuer('https://test.auth0.com',\n 'https://test.auth0.com/.well-known/jwks.json')})\n class GreetingApi(remote.Service):\n\nDefining an API method (`@endpoints.method`)\n--------------------------------------------\n\nYou can set the `audiences`, `scopes`, and `allowed_client_ids` settings\nfor the entire API by using `@endpoints.api`, or for a method, by using\n`@endpoints.method`. If these settings are specified at both the API and the\nmethod level, the method setting overrides.\n\nTo create a method in your API, decorate the corresponding Python\nmethod with `@endpoints.method`, supplying arguments to configure the\nuse of the method. For example, you specify which request and response `Message`\nclasses to use.\n| **Important:** Certain query parameters are reserved and cannot be used in an API method. For a list of these, see [Standard query parameters](https://developers.google.com/drive/web/query-parameters)\n\nThe available arguments are listed in the following table:\n\nUsing `ResourceContainer` for path or query string arguments\n------------------------------------------------------------\n\nIf the request contains path or query string arguments, you cannot use a simple\n`Message` class as described in\n[Create the API](/endpoints/docs/frameworks/python/create_api#creating_the_api).\nInstead, you must use a `ResourceContainer` class, as follows:\n\n1. Define a `Message` class that has all the arguments that are passed in\n the request body. If there aren't any arguments in the request body, you don't\n need to define a `Message` class: simply use `message_types.VoidMessage`.) For\n example:\n\n class Greeting(messages.Message):\n \"\"\"Greeting that stores a message.\"\"\"\n\n message = messages.StringField(1)\n\n2. Define a `ResourceContainer` with the `Message` class that you defined in the\n previous step as the first parameter. Specify the path and query string\n arguments in the subsequent parameters. For example:\n\n MULTIPLY_RESOURCE = endpoints.ResourceContainer(\n Greeting,\n times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),\n\n where the first argument is the `Message` class for the data in the request\n body and `times` is a number expected in the path or query string accompanying\n the request.\n3. Supply the `ResourceContainer` to the method handling the request, in the\n first parameter replacing the request `Message` class that would otherwise be\n supplied in that location. This snippet shows both the `ResourceContainer` and\n the `endpoints.method`:\n\n # This ResourceContainer is similar to the one used for get_greeting, but\n # this one also contains a request body in the form of a Greeting message.\n MULTIPLY_RESOURCE = endpoints.ResourceContainer(\n Greeting,\n times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),\n )\n\n @endpoints.method(\n # This method accepts a request body containing a Greeting message\n # and a URL parameter specifying how many times to multiply the\n # message.\n MULTIPLY_RESOURCE,\n # This method returns a Greeting message.\n Greeting,\n path=\"greetings/multiply/{times}\",\n http_method=\"POST\",\n name=\"greetings.multiply\",\n )\n def multiply_greeting(self, request):\n return Greeting(message=request.message * request.times)\n\n4. Add the `path` parameter as shown, to include your API.\n\n5. If your `ResourceContainer` has a required argument, a client request must\n include it either in a query string (for example, `yourApi?times=2`), or the\n URL path (for example, `yourApi/2`). However, in order for your API to receive\n an argument value by using the URL path, you must also add the argument name to\n the API path as shown for the `{times}` argument in `path='yourApi/{times}`.\n\nWhat's next\n-----------\n\n- [Creating the API](/endpoints/docs/frameworks/python/create_api)\n- [Creating an API implemented with multiple classes](/endpoints/docs/frameworks/python/create-multi-class-api)"]]
