Lumberyard
Guía del usuario (Version 1.19)

Operaciones

Una API de servicio de la gema en la nube puede implementar varias operaciones diferentes. Puede definir las operaciones en el archivo swagger.json mediante la adición de instancias operationObject a una pathItemObject. Para cada operación, puede definir los datos de entrada que requiere la operación y los datos de salida que produce. Los datos de entrada pueden incluir parámetros de ruta, consulta y cuerpo. Para obtener más información sobre la utilización de swagger para definir las API, consulte http://swagger.io/.

API Gateway enruta las solicitudes de API para la función Lambda de la gema en la nube. Cuando carga los recursos de la gema en la nube en AWS, se procesa el archivo swagger.json de la gema en la nube. Este procesamiento crea la solicitud y los mapeos de respuesta que API Gateway utiliza para llamar a la función Lambda de la gema en la nube. Esta configuración se controla mediante los objetos de extensión x-amazon-cloud-canvas-lambda-dispatch en el archivo swagger.json.

Las operaciones de la API de servicio se implementan en el recurso de la función AWS Lambda ServiceLambda. El código de la función Lambda proviene del directorio lambda-function-code de la gema en la nube. Cloud Gem Framework proporciona un módulo de envío de solicitud de servicio. Para obtener más información, consulte Ejecución de solicitud.

El siguiente diagrama ilustra el procesamiento de solicitudes y de carga.


            Operaciones de procesamiento de solicitudes y carga

Mapeo de solicitudes predeterminado

Un objeto JSON que implementa la operación de solicitud se envía a la función de Lambda. El objeto JSON contiene el nombre del módulo y el de la función y los parámetros de la operación, como muestra la siguiente sintaxis esquelética.

{ "module": "<module-name>", "function": "<function-name>", "parameters": { "<parameter-name>": <parameter-value>, ... } }

El nombre del módulo predeterminado se obtiene de la ruta de la operación. Una ruta como /player/{id}/highscoresda como resultado un nombre como player_highscores. Los parámetros de la ruta se omitirán. Las rutas /player y /player/{id} se asignan al nombre de módulo player. En este caso, la función del gestor en dicho módulo puede utilizar la existencia de un valor de parámetro id para determinar el comportamiento correspondiente. La ruta / (y /{param}) se asigna al nombre de módulo root.

El nombre de función predeterminado es el nombre de la operación como GET, POST o PUT.

Estos valores predeterminados pueden anularse especificando las propiedades del módulo y/o función de un objeto de extensión x-amazon-cloud-canvas-lambda-dispatch. Para obtener más información, consulte Objeto de extensión de Cloud Gem Framework.

Los nombres de parámetros se toman de las definiciones de parámetros en el archivo swagger.json. Los tipos de parámetro de ruta, consulta y cuerpo son compatibles.

Mapeado de respuesta predeterminado

La función Lambda devuelve el valor para al cliente como un objeto JSON como el siguiente.

{ "result":<lambda-return-value> }

Si la función Lambda sale con un error (por ejemplo, mostrando una excepción no gestionada), devuelve el objeto JSON en el siguiente formato.

{ "errorMessage":"<error-message>", "errorType":"<error-type>" }

Si el mensaje de error recibido desde la función Lambda comienza con el texto Client Error:, a continuación, se envía una respuesta HTTP 400 al cliente. Las propiedades errorMessage y errorType recibidas desde la función Lambda se reenvían al cliente.

Si el mensaje de error recibido desde la función Lambda no empieza con Client Error: o no se recibe ningún mensaje de error, se envía una respuesta HTTP 500 al cliente. Como medida de seguridad, errorMessage que se devuelve al cliente siempre es Se ha producido un error de servidor interno y errorType es ServiceError. Esto es para evitar el envío de mensajes de excepción al cliente. Si lo hace, podría proporcionar información que podría permitir que un atacante descubriese puntos débiles en su implementación de servicio.

En ambos casos de HTTP 400 y HTTP 500, no se envía ninguna otra información (como, rastreo de pila) al cliente. Esto también es una medida de seguridad.

Ejecución de solicitud

Cloud Gem Framework incorpora compatibilidad con funciones de Lambda de la API de servicio que se implementan en Python. No se proporciona soporte integrado para Node.js o las funciones Java de Lambda. Para admitir estos lenguajes, implemente el controlador de la función Lambda para buscar las propiedades module y function en el objeto de evento que proporciona la función Lambda. También sería necesario anular los valores predeterminados generados por las propiedades x-amazon-cloud-canvas-lambda-dispatch module y function durante el procesamiento del archivo swagger.json.

Se proporciona un archivo de módulo service.py en la función AWS Lambda del servicio. La función dispatch de este módulo utiliza las propiedades module y function del objeto event para enviar la solicitud al código de servicio que proporcione. El mapeo de solicitud que configura API Gateway establece estas propiedades.

Coloque el código de servicio en su grupo de recursos del directorio lambda-function-code\api. El distribuidor utiliza importlib.import_module para cargar los módulos desde dicho directorio. Si la función especificada tiene el decorador @service.api, el expedidor invoca la función en ese módulo, como en el siguiente ejemplo.

import service @service.api def post(request, submission, user_id): ...

El primer argumento pasado a la función es un objeto dispatch.Request. El objeto request incluye las siguientes propiedades.

  • event: el objeto de evento que AWS Lambda pasa al controlador de envío. La plantilla de solicitud determina el contenido del objeto. Otras propiedades añadidas a la plantilla a través de la propiedad x-amazon-cloud-canvas-lambda-dispatch del objeto additional-request-template-content también se encuentran aquí.

Los parámetros del objeto de solicitud se transfieren a la función del controlador como argumentos de palabras clave (es decir, utilizando **parameters de Python).

Control de errores

Se proporciona una clase ClientError en el archivo errors.py. Esta clase amplía RuntimeException y garantiza que el mensaje de error aparece prefijado con Client Error:. Esto activa una respuesta HTTP 400 de API Gateway tal como se describe en Mapeado de respuesta predeterminado.

Si aparecen otras excepciones durante el procesamiento, se envía un mensaje Internal Service Error genérico al cliente.