Decoradores

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

En esta página, se describen en detalle los decoradores disponibles. Si quieres obtener información acerca del uso de los decoradores para crear tu API, visita los vínculos siguientes:

• Crea la API
• Cómo crear una API implementada con varias clases

Define 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

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

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

Consulta Cómo configurar cuotas para ver todos los pasos necesarios a fin de configurar una cuota.

Especificas una lista de una o más de instancias de LimitDefinition, similar a 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 cliente y públicos permitidos

Para la autenticación de OAuth2, se emite un token de OAuth2 a un ID de cliente específico, lo que significa que este ID de cliente se puede usar para restringir el acceso a tus API. Cuando registras aplicaciones para Android en la consola de Google Cloud, creas un ID de cliente para ellas. Este ID de cliente es con el que se solicita un token de OAuth2 desde Google con fines de autenticación. Cuando la autenticación protege a la API de backend, se envía un token de acceso de OAuth2, y Endpoints Frameworks para App Engine lo abre. Luego, se extrae el ID de cliente del token y se compara con la lista de ID de cliente declarada como aceptada del backend (la lista allowed_client_ids).

En la lista allowed_client_ids, se deben incluir todos los ID de cliente que obtuviste a través de la consola de Google Cloud para tus aplicaciones web y de Android y otras aplicaciones cliente. Esto significa que se deben tener todos los ID de cliente al momento de compilar la API. Si se especifica una lista vacía, ningún cliente puede acceder a la API.

Ten en cuenta que debes llamar a endpoints.get_current_user() en cada método de API donde quieras verificar la autenticación correcta. Consulta Cómo autenticar usuarios para obtener más información.

Si usas el argumento allowed_client_ids y quieres probar las llamadas a tu API autenticadas mediante el Explorador de API, debes proporcionar su ID de cliente en la lista de allowed_client_ids mediante la determinación de la constante endpoints.API_EXPLORER_CLIENT_ID. Ten en cuenta que tu API aún tendrá visibilidad pública y que se podrá acceder a ella con el Explorador de API si allowed_client_ids solo contiene endpoints.API_EXPLORER_CLIENT_ID y tú implementas la API.

Acerca de los públicos

La lista allowed_client_ids protege a la API de backend de clientes no autorizados. Aun así, se necesita una protección mayor para proteger a los clientes, de manera que el token de autenticación solo funcione con la API de backend deseada. Para clientes Android, este mecanismo es el argumento audiences, en el cual se especifica el ID de cliente de la API de backend.

Ten en cuenta que cuando creas un proyecto de la consola de Google Cloud, se crea automáticamente un ID de cliente predeterminado con un nombre para que se use en el proyecto. Cuando subes tu API de backend en App Engine, en esta se usa el ID de cliente. Este es el ID de cliente web mencionado 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 están provistos por emisores de terceros, debes configurar de forma correcta los argumentos audiences y issuers en @endpoints.api para proporcionar la información sobre los emisores de terceros. 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):

Cómo definir un método de API (@endpoints.method)

Puedes configurar audiences, scopes y allowed_client_ids para toda la API mediante @endpoints.api, o para un método mediante @endpoints.method. Si esta configuración se especifica en el nivel de la API y en el del método, se anula la configuración de este último.

Para crear un método en tu API, decora el método de Python correspondiente con @endpoints.method y proporciona argumentos a fin de configurar el uso del método. Por ejemplo, se puede especificar qué clase Message de solicitud y respuesta usar.

Los argumentos disponibles se enumeran en la siguiente tabla:

Utiliza ResourceContainer para los argumentos de ruta o de string de consulta

Si la solicitud contiene argumentos de ruta o de string de consulta, no puedes usar una clase Message simple como se describe en Cómo crear la API. En su lugar, debes usar una clase ResourceContainer, de la siguiente manera:

1. Define una clase Message que tenga todos los argumentos que se pasan en el cuerpo de la solicitud. Si no hay argumentos en el cuerpo de la solicitud, no necesitas definir una clase Message, solo usa 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 definiste en el paso anterior como el primer parámetro. Especifica la ruta y los argumentos de string de consulta en los parámetros subsiguientes. Por ejemplo:

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

   En el ejemplo anterior, el primer argumento es la clase Message para los datos en el cuerpo de la solicitud y times es un número esperado en la ruta o string de consulta que acompaña a la solicitud.

3. Proporciona el ResourceContainer al método que maneja la solicitud, en el primer parámetro que reemplaza la clase Message de solicitud que, de lo contrario, se proporcionaría en esa ubicación. Este fragmento muestra el ResourceContainer y el 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. Agrega el parámetro path como se muestra para incluir tu API.

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

¿Qué sigue?

• Crea la API
• Cómo crear una API implementada con varias clases