Uso de una plantilla de mapeo para invalidar códigos de estado y parámetros de solicitud y de respuesta de una API

Las plantillas de mapeo de parámetros y códigos de respuesta estándar de API Gateway permiten mapear parámetros one-to-one y mapear una familia de códigos de estado de respuesta de integración (que coinciden con una expresión regular) a un único código de estado de respuesta. Las anulaciones de plantillas de mapeo le proporcionan la flexibilidad de realizar asignaciones de many-to-one parámetros; anular parámetros después de aplicar las asignaciones estándar de API Gateway; mapear parámetros condicionalmente en función del contenido del cuerpo u otros valores de parámetros; crear nuevos parámetros sobre la marcha mediante programación; y anular los códigos de estado devueltos por el punto final de integración. Se puede invalidar cualquier tipo de parámetro de solicitud, encabezado de respuesta o código de estado de respuesta.

A continuación se muestran ejemplos de uso de la invalidación de una plantilla de asignación:

• Para crear un nuevo encabezado (o sobrescribir una encabezado existente) como una concatenación de dos parámetros

• Para invalidar el código de respuesta a un código de éxito o error en función del contenido del cuerpo

• Para reasignar condicionalmente un parámetro en función de su contenido o del contenido de cualquier otro parámetro

• Para iterar sobre el contenido de un cuerpo JSON y reasignar pares de clave-valor a encabezados o cadenas de consulta

Para crear una invalidación de plantilla de asignación, utilice una o varias de las siguientes $context variables en una plantilla de asignación:

Plantilla de mapeo del cuerpo de solicitud	Plantilla de mapeo del cuerpo de respuesta
$context.requestOverride.header.header_name	$context.responseOverride.header.header_name
$context.requestOverride.path.path_name	$context.responseOverride.status
$context.requestOverride.querystring.querystring_name

nota

Las invalidaciones de plantillas de asignación no pueden utilizarse con puntos de enlace de integración de proxy, que carecen de asignaciones de datos. Para obtener más información acerca de los tipos de integración, consulte Elegir un tipo de integración de API de API Gateway.

importante

Las invalidaciones son definitivas. Una invalidación solo puede aplicarse a cada parámetro una vez. Los intentos de invalidar varias veces el mismo parámetro producirán respuestas 5XX de Amazon API Gateway. Si tiene que invalidar el mismo parámetro varias veces en la plantilla, le recomendamos crear una variable y aplicar la invalidación al final de la plantilla. Tenga en cuenta que la plantilla solo se aplica una vez analizada en su totalidad. Consulte Tutorial: invalidación de los encabezados y parámetros de solicitud de una API con la consola de API Gateway.

Los siguientes tutoriales muestran cómo crear y probar una invalidación de plantilla de mapeo en la consola de API Gateway. Estos tutoriales utilizan la API de ejemplo como punto de partida. PetStore En ambos tutoriales se asume que ya ha creado la API PetStore de ejemplo.

Tutorial: invalidación del código de estado de respuesta de una API con la consola de API Gateway

Para recuperar una mascota mediante la API de ejemplo, se utiliza el método API request ofGET /pets/{petId}, donde {petId} se PetStore muestra un parámetro de ruta que puede tomar un número en tiempo de ejecución.

En este tutorial, invalidará este código de respuesta del método GET mediante la creación de una plantilla de asignación que asigne $context.responseOverride.status a 400 cuando se detecte una condición de error.

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En API, elige la PetStore API y, a continuación, selecciona Recursos.

3. En el árbol Recursos, elija el método GET en /{petId}.

4. Elija la pestaña Prueba. Puede que tenga que elegir el botón de flecha hacia la derecha para mostrar la pestaña.

5. En petId, introduzca -1 y, a continuación, seleccione Prueba.

   En los resultados, observará dos cosas:

   En primer lugar, el cuerpo de la respuesta indica un out-of-range error:

   {
     "errors": [
       {
         "key": "GetPetRequest.petId",
         "message": "The value is out of range."
       }
     ]
   }

   En segundo lugar, la última línea del cuadro Registros termina con: Method completed with status: 200.

6. En la pestaña Respuesta de integración, en Predeterminado: respuesta, seleccione Editar.

7. Elija Plantillas de mapeo.

8. Elija Add mapping template (Añadir plantilla de asignación).

9. En Tipo de contenido, ingrese application/json.

10. En Cuerpo de la plantilla, introduzca lo siguiente:

    #set($inputRoot = $input.path('$'))
    $input.json("$")
    #if($inputRoot.toString().contains("error"))
    #set($context.responseOverride.status = 400)
    #end

11. Seleccione Guardar.

12. Elija la pestaña Prueba.

13. En petId, introduzca -1.

14. En los resultados, el cuerpo de la respuesta indica un out-of-range error:

    {
      "errors": [
        {
          "key": "GetPetRequest.petId",
          "message": "The value is out of range."
        }
      ]
    }

    Sin embargo, la última línea del cuadro Logs (Registros) termina ahora con: Method completed with status: 400.

Tutorial: invalidación de los encabezados y parámetros de solicitud de una API con la consola de API Gateway

En este tutorial, invalidará el código del encabezado de solicitud del método GET mediante la creación de una plantilla de asignación que asigna $context.requestOverride.header.header_name a un nuevo encabezado que combina otros dos encabezados.

1. Inicie sesión en la consola de API Gateway en https://console.aws.amazon.com/apigateway.

2. En APIs, elige la PetStore API.

3. En el árbol Recursos, elija el método GET en /pet.

4. En la pestaña Solicitud de método, en Configuración de solicitud de método, elija Editar.

5. Elija Encabezados de solicitud HTTP y, a continuación, elija Agregar encabezado.

6. En Nombre, ingrese header1.

7. Elija Agregar encabezado y, a continuación, cree un segundo encabezado llamado header2.

8. Seleccione Guardar.

9. En la pestaña Solicitud de integración, en Configuración de la solicitud de integración, seleccione Editar.

10. En Acceso directo de cuerpo de la solicitud, elija Cuando no haya plantillas definidas (recomendado).

11. Elija Plantillas de mapeo y, a continuación, haga lo siguiente:

    1. Elija Add mapping template (Añadir plantilla de asignación).

    2. En Tipo de contenido, ingrese application/json.

    3. En Cuerpo de la plantilla, introduzca lo siguiente:

       #set($header1Override = "foo")
       #set($header3Value = "$input.params('header1')$input.params('header2')")
       $input.json("$")
       #set($context.requestOverride.header.header3 = $header3Value)
       #set($context.requestOverride.header.header1 = $header1Override)
       #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])

12. Seleccione Guardar.

13. Elija la pestaña Prueba.

14. En Headers (Encabezados) de {pets}, copie el siguiente código:

    header1:header1Val
    header2:header2Val

15. Seleccione Test (Probar).

    En el registro, debería ver una entrada que incluye este texto:

    Endpoint request headers: {header3=header1Valheader2Val, 
    header2=header2Val, header1=foo, x-amzn-apigateway-api-id=<api-id>,
    Accept=application/json, multivalueheader=foo,header1Valheader2Val}

Ejemplos: invalidación de los encabezados y parámetros de solicitud de una API con la CLI de API Gateway

En el ejemplo siguiente de la CLI se muestra cómo utilizar el comando put-integration para invalidar un código de respuesta:

aws apigateway put-integration --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --type <INTEGRATION_TYPE> --request-templates <REQUEST_TEMPLATE_MAP>

donde <REQUEST_TEMPLATE_MAP> es una asignación de tipo de contenido a una cadena de la plantilla que se va a aplicar. La estructura de esa asignación es la siguiente:

Content_type1=template_string,Content_type2=template_string

o en la sintaxis JSON:

{"content_type1": "template_string"
...}

El siguiente ejemplo muestra cómo utilizar el comando put-integration-response para invalidar un código de respuesta de API:

aws apigateway put-integration-response --rest-api-id <API_ID> --resource-id <PATH_TO_RESOURCE_ID> --http-method <METHOD> 
            --status-code <STATUS_CODE> --response-templates <RESPONSE_TEMPLATE_MAP>

donde <RESPONSE_TEMPLATE_MAP> tiene el mismo formato que el <REQUEST_TEMPLATE_MAP> anterior.

Ejemplo: anule los parámetros y encabezados de las solicitudes de una API mediante el SDK para JavaScript

En el ejemplo siguiente se muestra cómo utilizar el comando put-integration para invalidar un código de respuesta:

Solicitud:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  type: HTTP | AWS | MOCK | HTTP_PROXY | AWS_PROXY, /* required */
  requestTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegration(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Respuesta:

var params = {
  httpMethod: 'STRING_VALUE', /* required */
  resourceId: 'STRING_VALUE', /* required */
  restApiId: 'STRING_VALUE', /* required */
  statusCode: 'STRING_VALUE', /* required */
  responseTemplates: {
    '<Content_type>': 'TEMPLATE_STRING',
    /* '<String>': ... */
  },
};
apigateway.putIntegrationResponse(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});