裝飾器

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

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

定義 API (@endpoints.api)

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

@endpoints.api 引數 說明 範例
allowed_client_ids 如果 API 使用驗證,則為必要引數。針對可以要求憑證的用戶端,列出用戶端 ID 清單。詳情請參閱允許的用戶端 ID 和目標對象一節。 allowed_client_ids=['1-web-apps.apps.googleusercontent.com','2-android-apps.apps.googleusercontent.com', endpoints.API_EXPLORER_CLIENT_ID]
api_key_required 選用引數。用於限制存取提供 API 金鑰的要求。 api_key_required=True
audiences 如果 API 需要驗證,以及如果您向 Android 用戶端提供支援,則為必要引數。對於 Google ID 憑證,這份用戶端 ID 清單可代表那些遭要求提供憑證的用戶端 ID。如果憑證是由第三方驗證供應商核發 (例如 Auth0),則需為從驗證核發者名稱對應到目標對象名單的字典。詳情請參閱允許的用戶端 ID 和目標對象一節。 audiences=['1-web-apps.apps.googleusercontent.com']audiences={"auth0": ["aud-1.auth0.com", "aud-2.auth0.com"]}
base_path 選用引數。用於透過指定路徑提供您的 API。如果您指定這個引數,也必須更改 app.yaml 檔案中的 handlers 區段。 請參閱透過不同的路徑提供 API
canonical_name 選用引數。用於為用戶端程式庫中的 API 指定不同或較易解讀的名稱。這個名稱用於產生用戶端程式庫中的名稱;後端 API 會繼續使用 name 屬性中指定的值。

例如,如果將 API 的 name 設為 dfaanalytics,您就可以使用這個屬性指定 DFA Group Analytics 的正式名稱;隨後產生的用戶端類別就會包含名稱 DfaGroupAnalytics

您應該在名稱之間包含相關空格,如上所示。這些空格都會替換為適用的駝峰式大小寫或底線。
canonical_name='DFA Analytics'
description API 的簡短說明,會公開顯示在探索服務中,以便使用者瞭解您的 API,也能如產生用戶端程式庫一文所述,視需要用於產生說明文件,。 description='Sample API for a simple game'
documentation 選用引數。方便使用者找到這個 API 版本說明文件的網址。此網址會出現在 API Explorer 頁面頂端醒目顯示的「瞭解詳情」,讓使用者進一步瞭解您的服務。 documentation='http://link_to/docs'
hostname App Engine 應用程式的主機名稱。Endpoints Frameworks 指令列工具會使用您在此處指定的值,來產生探索文件或 OpenAPI 文件。如果您沒有在此處指定主機名稱,則必須在 app.yaml 檔案的 application 欄位中指定主機名稱,或在部署 App Engine 應用程式時指定您的專案 ID。 hostname='your_app_id.appspot.com'
issuers 選用引數。自訂 JWT 核發者設定。這個引數應為從核發者名稱對應到 endpoints.Issuer 物件的字典。 issuers={"auth0": endpoints.Issuer("https://test.auth0.com", "https://test.auth0.com/.well-known/jwks.json")}
name 必要引數。API 的名稱,用於做為所有 API 方法和路徑的前置字串。name 值:
  • 必須以小寫字母開頭。
  • 必須與規則運算式 [a-z]+[A-Za-z0-9] 相符,也就是說,名稱的其餘部分可包含大小寫字母或數字。
如要將多個 API 部署做為單一服務的一部分,則所有 API 名稱都必須與規則運算式 [a-z][a-z0-9]{0,39} 相符。換句話說,名稱皆必須以小寫字母開頭,其餘字元必須為小寫字母或數字,字數上限為 40 個字元。
name='yourApi'name='yourapi'
limit_definitions 選用引數,用於定義 API 的配額,詳情請參閱 limit_definitions 一節。
owner_domain 選用引數,擁有 API 的實體網域名稱。可與 owner_name 搭配使用,讓系統在為這個 API 產生用戶端程式庫時,提供適用的命名方式提示。如有提供,套件路徑就是 owner_domainpackage_path 的相反順序。預設值使用 appid.apppost.com owner_domain='your-company.com'
owner_name 選用引數,擁有 API 的實體網域名稱。可與 owner_domain 搭配使用,讓系統為這個 API 產生用戶端程式庫時,提供適用的命名方式提示。 owner_name='Your-Company'
package_path 選用引數,用於進一步指定這個 API 所屬「套件」的範圍,並使用 / 分隔值以指定 API 的邏輯群組。

例如,指定設為 cloud/platform/<ApiName> 的用戶端程式庫路徑中的 cloud/platform 結果,以及設為 cloud.plaform.<ApiName> 的用戶端程式庫套件。
package_path='cloud/platform'
scopes 如果沒有提供,則預設值是電子郵件範圍 (https://www.googleapis.com/auth/userinfo.email),這對 OAuth 來說是必備項目。如果需要,您可以加以覆寫以指定更多 OAuth 2.0 範圍。您也可透過在 @endpoints.method 裝飾器中指定不同的範圍,覆寫這裡為特定 API 方法指定的範圍。但是請注意,若您定義了多個範圍,而憑證是針對任何指定的範圍所新建,則會通過範圍檢查。如需多個範圍,請指定單一字串,每個範圍之間使用一個半形空格分隔。 scopes=['ss0', 'ss1 and_ss2']
title 選用引數。在 API Explorer 中顯示為 API 標題的文字,並於探索及目錄服務中公開。 title='My Backend API'
version 必要引數。指定您的 Cloud Endpoints 版本。這個值會出現在您的 API 路徑中。如果您指定的版本字串與 SemVer 標準相容,則當您部署 API 時,只有主要版本編號會出現在您的 API 路徑中。例如,API 呼叫含有版本 2.1.0echo 時,路徑會類似於 /echo/v2。如果將您的 echo API 更新為版本 2.2.0,並部署具回溯相容性的變更,路徑仍然為 /echo/v2。這使您可以在進行具回溯相容性的變更時更新 API 版本編號,而不會破壞用戶端的現有路徑。但如果您將 echo API 更新為版本 3.0.0 (因為您正在部署破壞性的變更),路徑將會變更為 /echo/v3 version='v1'version='2.1.0'

limit_definitions

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

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

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

請指定含有一或多個 LimitDefinition 執行個體的清單,內容如下所示:

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

每個 LimitDefinition 執行個體必須擁有以下值:

元素 說明
名稱 API 要求計數器的名稱。通常是能夠唯一識別配額的要求類型 (例如「read-requests」或「write-requests」)。
顯示名稱

在「Endpoints」>「Services」(服務) 頁面的「Quotas」(配額) 分頁標籤中顯示的文字,用於識別配額。您的 API 消費者也會在「IAM 與管理員」及「API 與服務」的「Quotas」(配額) 頁面上看到此文字。顯示名稱長度上限為 40 個字元。

為了便於閱讀,「Quotas」(配額) 頁面會自動為顯示名稱加上「per minute per project」(每個專案每分鐘) 字樣。為了與 API 消費者在「Quotas」(配額) 頁面上看到的 Google 服務顯示名稱能保持一致,我們對於顯示名稱有以下建議:

  • 當您只有一個指標時,請使用「要求數」。
  • 當您有多個指標時,每個指標都應說明要求的類型,並包含「要求數」一詞 (例如「讀取要求數」或「寫入要求數」)。
  • 當這個配額的任何費用大於 1 時,請使用「配額單位」而不要使用「要求數」。

限制 一個整數值,針對某個配額,指定每個消費者專案每分鐘的要求數上限。

範例

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 Platform 主控台中註冊 Android 應用程式時,就等同為應用程式建立用戶端 ID。這個用戶端 ID 會從 Google 要求提供 OAuth2 憑證以進行驗證。當後端 API 受驗證保護時,App Engine 適用的 Endpoints Frameworks 會傳送並開啟 OAuth2 存取憑證,系統會從憑證中擷取用戶端 ID,然後比較 ID 與後端宣告的可接受用戶端 ID 清單 (allowed_client_ids 清單)。

allowed_client_ids 清單應包含您已透過 Google Cloud Platform 主控台為您的網路、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 Platform 主控台專案時,系統會自動建立和命名提供給專案使用的預設用戶端 ID。將後端 API 上傳到 App Engine 時,會使用這個用戶端 ID,這就是 API 驗證說明中提及的網路用戶端 ID。

第三方驗證憑證核發者

如果您的應用程式可接受非 Google ID 憑證,且是由第三方核發者所發出的驗證憑證,則必須在 @endpoints.api 中正確設定 audiencesissuers 引數,以提供有關第三方核發者的資訊。例如:

@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 設定 audiencesscopesallowed_client_ids,或使用 @endpoints.method 針對某個方法進行一樣的設定。如果同時在 API 和方法層級指定這些設定,則方法層級的設定會覆寫 API 層級的設定。

如要在 API 中建立方法,請使用 @endpoints.method 裝飾對應的 Python 方法,並提供引數以設定方法的使用情況。例如,您可以指定要使用的要求和回應 Message 類別。

下列表格包含可用的引數:

@endpoints.method 引數 說明 範例
allowed_client_ids 這項設定會覆寫 @endpoints.api 中指定的對等屬性。詳情請參閱允許的用戶端 ID 和目標對象一節。 ['1-web-apps.apps.googleusercontent.com', '2-android-apps.apps.googleusercontent.com']
api_key_required 選用引數。用於限制存取提供 API 金鑰的要求。 api_key_required=True
audiences 可覆寫 @endpoints.api 中指定的對等引數。詳情請參閱允許的用戶端 ID 和目標對象一節。 ['1-web-apps.apps.googleusercontent.com']
metric_costs 選用引數。表示方法有配額限制。這是包含以下鍵/值組合的字典:
  • 名稱:您在 API 裝飾器的 limit_definitions 引數中指定的名稱。
  • 費用:一個整數,用於指定每次要求的費用。費用可讓方法在相同配額中以不同的速率消耗。例如,如果呼叫應用程式的配額限制為 1000 而費用為 1,則在超過限制之前,每分鐘可以提出 1000 次要求。如果呼叫應用程式在相同配額中費用為 2 時,在超過限制之前,每分鐘只能提出 500 次要求。
metric_costs={'read-requests': 1}
http_method 要使用的 HTTP 方法。如果不設定這個引數,則系統會預設使用 'POST' 'GET'
name 這個方法的別名。name 值:
  • 必須以小寫字母開頭。
  • 必須與規則運算式 [a-z]+[A-Za-z0-9]* 相符。
'yourApi'
path 存取這個方法的 URI 路徑。如果您並未設定這個欄位,則會使用 Python 方法的名稱。如果您打算新增 API 管理,請勿在路徑中使用結尾的斜線。 'yourapi/path'
Request Message 類別 在方法呼叫中使用的 Google Protocol RPC Request Message 類別。您也可以提供類別名稱。 YourRequestClass
Response Message 類別 在方法呼叫中使用的 Google Protocol RPC Response Message 類別。您也可以提供類別名稱。 YourResponseClass

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 類別。下列程式碼片段顯示 ResourceContainerendpoints.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} 引數所示。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁