Uso de integraciones de servicios de AWS para API HTTP

Puede integrar su API HTTP en los servicios de AWS usando integraciones de primera clase. La integración de primera clase conecta una ruta de API HTTP a una API de servicio de AWS. Cuando un cliente invoca una ruta respaldada por una integración de primera clase, API Gateway invoca una API de servicio de AWS por usted. Por ejemplo, puede utilizar integraciones de primera clase para enviar un mensaje a una cola de Amazon Simple Queue Service o para iniciar una máquina de estado de AWS Step Functions. Para ver las acciones de servicio compatibles, consulte Referencia del subtipo de integración.

Asignar parámetros de solicitud

Las integraciones de primera clase tienen parámetros obligatorios y opcionales. Debe configurar todos los parámetros que son obligatorios para crear una integración. Puede utilizar valores estáticos o parámetros de asignación que se evalúan dinámicamente en el tiempo de ejecución. Para obtener una lista completa de las integraciones y parámetros admitidos, consulte Referencia del subtipo de integración.

Asignación de parámetros
Tipo	Ejemplo	Notas
Valor del encabezado	$request.header.name	Los nombres del encabezado no distinguen entre mayúsculas y minúsculas. API Gateway combina varios valores de encabezado con comas, por ejemplo, "header1": "value1,value2".
Valor de la cadena de consulta	$request.querystring.name	Los nombres de las cadenas de consulta distinguen mayúsculas y minúsculas. API Gateway combina varios valores con comas, por ejemplo, "querystring1": "Value1,Value2".
Parámetro de ruta	$request.path.name	El valor de un parámetro de ruta en la solicitud. Por ejemplo, si la ruta es /pets/{petId}, puede asignar el parámetro petId de la solicitud con $request.path.petId.
Solicitar acceso directo del cuerpo	$request.body	API Gateway transfiere todo el cuerpo de la solicitud directamente.
Cuerpo de la solicitud	$request.body.name	Una expresión de ruta de acceso JSON. El descenso recursivo ($request.body..name) y las expresiones de filtro (?(expression)) no son compatibles. nota Cuando se especifica una ruta JSON, API Gateway trunca el cuerpo de la solicitud en 100 KB y, a continuación, aplica la expresión de selección. Para enviar cargas de más de 100 KB, especifique $request.body.
Variable de contexto	$contexto.variableName	El valor de una variable de contexto compatible.
Variable de etapa	$stageVariables.variableName	El valor de una variable de etapa.
Valor estático	string	Un valor constante.

Crear una integración de primera clase

Antes de crear una integración de primera clase, debe crear un rol de IAM que conceda a API Gateway permisos para invocar la acción de servicio de AWS en la que se está integrando. Para obtener más información, consulte Creación de un rol para un servicio de AWS.

Para crear una integración de primera clase, elija una acción de servicio de AWS admitido, como SQS-SendMessage, configure los parámetros de la solicitud y proporcione un rol que conceda a API Gateway permisos para invocar la API de servicio de AWS integrada. Dependiendo del subtipo de integración, se requieren diferentes parámetros de solicitud. Para obtener más información, consulte Referencia del subtipo de integración.

El siguiente comando de la AWS CLI crea una integración que envía un mensaje de Amazon SQS.

aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-subtype SQS-SendMessage \
    --integration-type AWS_PROXY \
    --payload-format-version 1.0 \
    --credentials-arn arn:aws:iam::123456789012:role/apigateway-sqs \
    --request-parameters '{"QueueUrl": "$request.header.queueUrl", "MessageBody": "$request.body.message"}'

Creación de una integración de primera clase con AWS CloudFormation

El siguiente ejemplo muestra un fragmento de AWS CloudFormation que crea una ruta de /{source}/{detailType} con una integración de primera clase con Amazon EventBridge.

El parámetro Source se asigna al parámetro de ruta {source}, el DetailType se asigna al parámetro de ruta {DetailType} y el parámetro Detail se asigna al cuerpo de la solicitud.

El fragmento no muestra el bus de eventos ni el rol de IAM que otorga permisos a API Gateway para invocar la acción PutEvents.

Route:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId: !Ref HttpApi
      AuthorizationType: None
      RouteKey: 'POST /{source}/{detailType}'
      Target: !Join 
        - /
        - - integrations
          - !Ref Integration
  Integration:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId: !Ref HttpApi
      IntegrationType: AWS_PROXY
      IntegrationSubtype: EventBridge-PutEvents
      CredentialsArn: !GetAtt EventBridgeRole.Arn
      RequestParameters:
        Source: $request.path.source
        DetailType: $request.path.detailType
        Detail: $request.body
        EventBusName: !GetAtt EventBus.Arn
      PayloadFormatVersion: "1.0"