修飾符

適用於 Python 的 Endpoints Frameworks 裝飾器說明 API 設定、方法、參數，以及其他定義 Endpoint 屬性與行為的重要詳細資料。

本頁面將詳細說明可用的裝飾器。如要瞭解透過裝飾器建立 API 的方式，請參閱以下內容：

• 建立 API
• 建立在多個類別實作的 API

定義 API (@endpoints.api)

您可以將多個引數提供給 @endpoints.api 以定義 API。以下表格說明可用的引數：

limit_definitions

如要為 API 定義配額，請將選用的 limit_definitions 引數指定為 @endpoints.api。您也必須完成以下動作以設定配額：

• 安裝 2.4.5 版或更新版本的 Endpoints Frameworks 程式庫。
• 針對每個您要套用配額的方法，將 metric_costs 引數新增到方法裝飾器。

請參閱設定配額一文，瞭解設定配額必要的完整步驟。

您可以指定一或多個 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 驗證，特定用戶端 ID 會獲派 OAuth2 憑證，即代表您可以使用用戶端 ID 限制他人存取您的 API。當您在 Google Cloud 控制台中註冊 Android 應用程式時，就等同為應用程式建立用戶端 ID。這個用戶端 ID 會從 Google 要求提供 OAuth2 憑證以進行驗證。當後端 API 受驗證保護時，App Engine 適用的 Endpoints Frameworks 會傳送並開啟 OAuth2 存取憑證，系統會從憑證中擷取用戶端 ID，然後比較 ID 與後端宣告的可接受用戶端 ID 清單 (allowed_client_ids 清單)。

allowed_client_ids 清單應包含您已透過 Google Cloud console 為您的網路、Android 和其他用戶端應用程式所取得的所有用戶端 ID。這代表在建構 API 時，即必須提供這些用戶端。如果您指定空白的清單，那表示「沒有」用戶端能夠存取 API。

請注意，您必須在每個要檢查是否適當驗證的 API 方法中呼叫 endpoints.get_current_user()。詳情請參閱驗證使用者一文。

如果您使用 allowed_client_ids 引數，並且要使用 API Explorer 來測試驗證呼叫您的 API，則必須在 allowed_client_ids 的清單中提供用戶端 ID，方法是指定常數 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。將後端 API 上傳到 App Engine 時，會使用這個用戶端 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)

您可以使用 @endpoints.api 為整個 API 設定 audiences、scopes 和 allowed_client_ids，或使用 @endpoints.method 針對某個方法進行一樣的設定。如果同時在 API 和方法層級指定這些設定，則方法層級的設定會覆寫 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. 定義 ResourceContainer，其中包含您在上一個步驟中定義為第一個參數的 Message 類別。在後續的參數中指定路徑和查詢字串引數。例如：

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

   其中第一個引數是要求主體中資料的 Message 類別，times 則是要求中隨附的路徑或查詢字串裡預期的數字。

3. 將 ResourceContainer 提供給處理要求的方法，在第一個參數中替換將在該位置提供的要求 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. 參照範例，新增 path 參數以包含您的 API。

5. 如果您的 ResourceContainer 擁有必要引數，則用戶端要求必須將該引數放入查詢字串 (例如yourApi?times=2) 或網址路徑 (例如yourApi/2) 中。但是，為了讓 API 能使用網址路徑接收引數值，您也必須將引數名稱新增至 API 路徑，如 path='yourApi/{times} 中的 {times} 引數所示。

後續步驟

• 建立 API
• 建立在多個類別實作的 API