Decoradores

Los decoradores de Cloud Endpoints Frameworks para Python describen la configuración de la API, los métodos, los parámetros y otros detalles importantes que definen las propiedades y el comportamiento del endpoint.

En esta página se describen los decoradores disponibles en detalle. Para obtener información sobre cómo usar los decoradores para crear tu API, consulta lo siguiente:

• Crear la API
• Crear una API implementada con varias clases

Definir la API (@endpoints.api)

Puedes proporcionar varios argumentos a @endpoints.api para definir tu API. En la siguiente tabla se describen los argumentos disponibles:

limit_definitions

Para definir cuotas para tu API, especifica el argumento opcional limit_definitions en @endpoints.api. Para configurar una cuota, también debes hacer lo siguiente:

• Instala la versión 2.4.5 o una posterior de la biblioteca Endpoints Frameworks.
• Añade el argumento metric_costs al decorador de método de cada método al que quieras aplicar una cuota.

Consulta Configurar cuotas para ver todos los pasos necesarios para configurar una cuota.

Especifica una lista de una o varias instancias de LimitDefinition, como la siguiente:

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

Cada instancia de LimitDefinition debe tener los siguientes valores:

Ejemplo

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 de clientes y audiencias permitidos

En la autenticación de OAuth2, se emite un token de OAuth2 para un ID de cliente específico, lo que significa que este ID de cliente se puede usar para restringir el acceso a tus APIs. Cuando registras aplicaciones Android en la Google Cloud consola, crea un ID de cliente para ella. Este ID de cliente es el que solicita un token de OAuth2 a Google con fines de autenticación. Cuando la API de backend está protegida por autenticación, Endpoints Frameworks para App Engine envía y abre un token de acceso de OAuth 2.0, extrae el ID de cliente del token y, a continuación, compara el ID con la lista de IDs de cliente aceptables declarada por el backend (la lista allowed_client_ids).

La lista allowed_client_ids debe incluir todos los IDs de cliente que hayas obtenido a través de la Google Cloud console para tus aplicaciones web, Android y otras aplicaciones cliente. Esto significa que los clientes deben conocerse en el momento de compilar la API. Si especificas una lista vacía, ningún cliente podrá acceder a la API.

Ten en cuenta que, en cada método de la API en el que quieras comprobar que la autenticación es correcta, debes llamar a endpoints.get_current_user(). Consulta más información sobre cómo autenticar usuarios.

Si usas el argumento allowed_client_ids y quieres probar las llamadas autenticadas a tu API mediante el Explorador de APIs, debes proporcionar su ID de cliente en la lista de allowed_client_ids especificando la constante endpoints.API_EXPLORER_CLIENT_ID. Ten en cuenta que, si allowed_client_ids solo contiene endpoints.API_EXPLORER_CLIENT_ID y despliegas tu API, esta seguirá siendo visible y accesible públicamente en el Explorador de APIs.

Acerca de las audiencias

La lista allowed_client_ids protege la API de backend frente a clientes no autorizados. Sin embargo, se necesita más protección para proteger a los clientes, de modo que su token de autenticación solo funcione con la API backend prevista. En el caso de los clientes Android, este mecanismo es el argumento audiences, en el que se especifica el ID de cliente de la API de backend.

Ten en cuenta que, al crear un proyecto de consola, se crea automáticamente un ID de cliente predeterminado con el nombre del proyecto para que lo use. Google Cloud Cuando subes tu API backend a App Engine, esta usa ese ID de cliente. Es el ID de cliente web que se menciona en la autenticación de la API.

Emisor de tokens de autenticación de terceros

Si tu aplicación acepta tokens de autenticación que no son tokens de ID de Google y que emiten terceros, debes definir correctamente los argumentos audiences y issuers en @endpoints.api para proporcionar la información sobre los emisores externos. Por ejemplo:

@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):

Definir un método de API (@endpoints.method)

Puede definir los ajustes audiences, scopes y allowed_client_ids de toda la API mediante @endpoints.api o de un método mediante @endpoints.method. Si estos ajustes se especifican tanto en la API como en el nivel de método, prevalece el ajuste del método.

Para crear un método en tu API, decora el método de Python correspondiente con @endpoints.method y proporciona argumentos para configurar el uso del método. Por ejemplo, puedes especificar qué clases de solicitud y respuesta Message quieres usar.

Los argumentos disponibles se indican en la siguiente tabla:

Usar ResourceContainer para argumentos de ruta o de cadena de consulta

Si la solicitud contiene argumentos de ruta o de cadena de consulta, no puedes usar una clase Message simple, tal como se describe en Crear la API. En su lugar, debes usar una clase ResourceContainer, como se indica a continuación:

1. Define una clase Message que tenga todos los argumentos que se transfieren en el cuerpo de la solicitud. Si no hay argumentos en el cuerpo de la solicitud, no es necesario definir una clase Message, sino que basta con usar message_types.VoidMessage. Por ejemplo:

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

2. Define un ResourceContainer con la clase Message que has definido en el paso anterior como primer parámetro. Especifique los argumentos de la ruta y la cadena de consulta en los parámetros posteriores. Por ejemplo:

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

   donde el primer argumento es la clase Message de los datos del cuerpo de la solicitud y times es un número que se espera en la ruta o en la cadena de consulta que acompaña a la solicitud.

3. Proporciona ResourceContainer al método que gestiona la solicitud en el primer parámetro, que sustituye a la clase Message de la solicitud que, de lo contrario, se proporcionaría en esa ubicación. En este fragmento se muestran tanto ResourceContainer como 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. Añade el parámetro path como se muestra para incluir tu API.

5. Si tu ResourceContainer tiene un argumento obligatorio, una solicitud de cliente debe incluirlo en una cadena de consulta (por ejemplo, yourApi?times=2) o en la ruta de la URL (por ejemplo, yourApi/2). Sin embargo, para que tu API reciba un valor de argumento mediante la ruta de la URL, también debes añadir el nombre del argumento a la ruta de la API, como se muestra en el argumento {times} de path='yourApi/{times}.

Siguientes pasos

• Crear la API
• Crear una API implementada con varias clases