装饰器

Python 版 Cloud Endpoints Frameworks 装饰器描述定义端点的属性和行为的 API 配置、方法、参数以及其他重要细节。

本页面详细介绍可用的装饰器。如需了解如何使用装饰器来创建 API，请参阅以下内容：

• 创建 API
• 创建使用多个类实现的 API

定义 API (@endpoints.api)

您可以通过为 @endpoints.api 提供多个参数来定义 API。下表介绍了可用的参数：

limit_definitions

如需为您的 API 定义配额，请将可选 limit_definitions 参数指定为 @endpoints.api。要配置配额，您还必须执行以下操作：

• 安装 Endpoints Frameworks 客户端库的 2.4.5 版本或更高版本。
• 对于要应用配额的每个方法，将 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 控制台为您的 Web、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 身份验证中提到的 Web 客户端 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 中创建方法，请使用 @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 类，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