デコレータ

Python 用 Cloud Endpoints Frameworks のデコレータは、API の構成、メソッド、パラメータなど、Endpoints のプロパティや動作を定義する重要な詳細を記述します。

このページでは、使用可能なデコレータについて詳しく説明します。デコレータを使用して API を作成する方法については、次をご覧ください。

• API の作成
• 複数のクラスで実装される API の作成

API の定義（@endpoints.api）

@endpoints.api に複数の引数を渡して API を定義できます。使用可能な引数は、以下の表のとおりです。

limit_definitions

API の割り当てを定義するには、オプションの limit_definitions 引数を @endpoints.api に指定します。割り当てを構成するには、次のことも行う必要があります。

• Endpoints Frameworks ライブラリのバージョン 2.4.5 以降をインストールします。
• 割り当ての適用対象となる各メソッドのメソッド デコレータに、metric_costs 引数を追加します。

割り当ての設定に必要なすべての手順については、割り当ての構成をご覧ください。

次のように、1 つ以上の LimitDefinition インスタンスのリストを指定します。

quota_limits = [
              endpoints.LimitDefinition(
                "name",
                "Display name",
                limit)
]

各 LimitDefinition インスタンスには、次の値が必要です。

例

quota_limits = [
  endpoints.LimitDefinition('read-requests', 'Read Requests', 1000),
  endpoints.LimitDefinition('list-requests', 'List Requests', 100),
  endpoints.LimitDefinition('write-requests', 'Write Requests', 50)
]

@endpoints.api(name='bookstore',
               version='v1',
               limit_definitions=quota_limits)

許可されたクライアント 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 コンソール から取得したすべてのクライアント 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 の引数を適切に設定し、このサードパーティ発行元の情報を提供する必要があります。次に例を示します。

@endpoints.api(
        audiences={'auth0': ['aud-1.auth0.com', 'aud-2.auth0.com']},
        issuers={'auth0': endpoints.Issuer('https://test.auth0.com',
                                           'https://test.auth0.com/.well-known/jwks.json')})
class GreetingApi(remote.Service):

API メソッドの定義（@endpoints.method）

audiences、scopes、allowed_client_ids を API 全体に設定するには、@endpoints.api を使用し、メソッドに設定するには @endpoints.method を使用します。これらの設定が API とメソッド両方のレベルで指定された場合は、メソッドの設定が優先します。

API にメソッドを作成するには、@endpoints.method を使って対応する Python のメソッドを修飾し、メソッドの構成方法を設定する引数を指定します。たとえば、使用するリクエストとレスポンスの Message クラスを指定します。

利用可能な引数のリストは、下表のとおりです。

パスまたはクエリの文字列の引数に ResourceContainer を使用する

リクエストにパスまたはクエリの文字列の引数が含まれている場合は、API の作成で説明されているように、単純な Message クラスを作成することはできません。 その場合は、次のようにして ResourceContainer クラスを使用する必要があります。

1. リクエスト本文に渡される引数をすべて含む Message クラスを定義します。リクエスト本文に引数がまったく含まれない場合は、Message クラスを定義する必要はなく、単純に message_types.VoidMessage を使用します。次に例を示します。

   class Greeting(messages.Message):
       """Greeting that stores a message."""
   
       message = messages.StringField(1)

2. 最初のパラメータとして、前の手順で定義した Message クラスを使用して ResourceContainer を定義します。以降のパラメータには、パスとクエリの文字列の引数を指定します。次に例を示します。

   MULTIPLY_RESOURCE = endpoints.ResourceContainer(
       Greeting,
       times=messages.IntegerField(2, variant=messages.Variant.INT32, required=True),

   ここでは、リクエスト本文にあるデータの Message クラスが 1 つ目の引数であり、times はリクエストが持つパスかクエリ文字列に含まれる数字です。

3. リクエストを処理するメソッドに ResourceContainer を渡して、1 つ目のパラメータを、その位置に入力されるリクエストの Message クラスと置き換えます。次のスニペットは、ResourceContainer と endpoints.method の両方を示します。

   # 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",
   )
   def multiply_greeting(self, request):
       return Greeting(message=request.message * request.times)
   

4. 示されたとおりに API を含む path パラメータを追加します。

5. ResourceContainer に必須の引数がある場合、クライアント リクエストのクエリ文字列（yourApi?times=2 など）または URL パス（yourApi/2 など）にその引数を含める必要があります。ただし、この URL パスを使用して API が引数値を受け取るようにするには、path='yourApi/{times} の引数 {times} に示すように、引数名も API パスに追加する必要があります。

次のステップ

• API の作成
• 複数のクラスで実装される API の作成