Sintaxis Propiedades Valores devueltos Ejemplos

AWS::Serverless::HttpApi

Cree una API HTTP de Amazon API Gateway, que permite crear API RESTful con menor latencia y costos que las API de REST. Para obtener más información, consulta Trabajar con API HTTP en la Guía del desarrollador de API Gateway.

Te recomendamos que utilices enlaces de AWS CloudFormation o políticas de IAM para comprobar que los recursos de API Gateway tienen autorizadores adjuntos para controlar el acceso a ellos.

Para obtener más información sobre el uso de enlaces AWS CloudFormation, consulta Registrar enlaces en la Guía del usuario de CLI de AWS CloudFormation y en el repositorio de GitHub apigw-enforce-autorizarr.

Para obtener más información sobre el uso de las políticas de IAM, consulta Exigir que las rutas de API tengan autorización en la Guía para desarrolladores de API Gateway.

nota

Al realizar la implementación en AWS CloudFormation, AWS SAM transforma sus recursos de AWS SAM en recursos de AWS CloudFormation. Para obtener más información, consulta Recursos AWS CloudFormation de AWS SAM generados.

Sintaxis

Para declarar esta entidad en su plantilla de AWS Serverless Application Model (AWS SAM), usa la siguiente sintaxis:

YAML


Type: AWS::Serverless::HttpApi
Properties:
  AccessLogSettings: AccessLogSettings
  Auth: HttpApiAuth
  CorsConfiguration: String | HttpApiCorsConfiguration
  DefaultRouteSettings: RouteSettings
  DefinitionBody: JSON
  DefinitionUri: String | HttpApiDefinition
  Description: String
  DisableExecuteApiEndpoint: Boolean
  Domain: HttpApiDomainConfiguration
  FailOnWarnings: Boolean
  Name: String
  PropagateTags: Boolean
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Propiedades

AccessLogSettings

Configuración del registro de acceso en una etapa.

Type: AccessLogSettings

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad AccessLogSettings de un recurso AWS::ApiGatewayV2::Stage.

Auth

Configure la autorización para controlar el acceso a la API HTTP de API Gateway.

Para obtener más información, consulta Control del acceso a las API HTTP con autorizadores de JWT en la Guía para desarrolladores de API Gateway.

Tipo: HttpAPIAuth

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

CorsConfiguration

Administre el uso compartido de recursos entre orígenes (CORS) para todas las API HTTP Gateway. Especifica el dominio que quieres permitir como cadena o especifica un objeto HttpApiCorsConfiguration. Tenga en cuenta que CORS requiere AWS SAM para modificar su definición de OpenAPI, por lo que CORS solo funciona si se especifica la propiedad DefinitionBody.

Para obtener más información, consulta Configuración de CORS para API HTTP en la Guía para desarrolladores de API Gateway.

nota

Si CorsConfiguration se establece tanto en una definición de OpenAPI como en el nivel de propiedad, entonces AWS SAM fusiona ambas fuentes de configuración dando prioridad a las propiedades. Si esta propiedad está establecida en true, se permiten todos los orígenes.

Tipo: String | HttpApicOrsConfiguration

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

DefaultRouteSettings

Es la configuración de ruta predeterminada para esta API HTTP. Esta configuración se aplica a todas las rutas, a menos que la propiedad RouteSettings la anula para determinadas rutas.

Type: RouteSettings

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad RouteSettings de un recurso AWS::ApiGatewayV2::Stage.

DefinitionBody

La definición de OpenAPI que describe tu API HTTP. Si no especificas un DefinitionUri o DefinitionBody, AWS SAM genera un DefinitionBody para usted en función de la configuración de su plantilla.

Tipo: JSON

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es similar a la propiedad Body de un recurso AWS::ApiGatewayV2::Api. Si se proporcionan determinadas propiedades, AWS SAM puede insertar contenido en ellas o modificar el DefinitionBody antes de pasarlas a AWS CloudFormation. Las propiedades incluyen una Auth y un EventSource del tipo HttpAPI para el recurso AWS::Serverless::Function correspondiente.

DefinitionUri

El URI, ruta de archivo local u objeto de ubicación de Amazon Simple Storage Service (Amazon S3) de la definición de OpenAPI que define la API HTTP. El objeto Amazon S3 al que hace referencia esta propiedad debe ser un archivo de definición de OpenAPI válido. Si no especificas un DefinitionUri o DefinitionBody, AWS SAM genera un DefinitionBody para usted en función de la configuración de su plantilla.

Si proporcionas una ruta de archivo local, la plantilla debe seguir el flujo de trabajo que incluye el comando sam deploy o sam package para que la definición se transforme correctamente.

Las funciones intrínsecas no se admiten en los archivos de definición de OpenAPI externos a los que se hace referencia con DefinitionUri. Para importar una definición de OpenAPI a la plantilla, utilice la propiedad DefinitionBody con Include transform.

Tipo: String | HttpApidDefinition

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es similar a la propiedad BodyS3Location de un recurso AWS::ApiGatewayV2::Api. Las propiedades anidadas de Amazon S3 tienen un nombre diferente.

Description

La descripción del recurso de la API HTTP.

Cuando especifica Description, AWS SAM modificará la definición de OpenAPI del recurso de la API HTTP configurando el campo description. Las siguientes situaciones producirán un error:

La propiedad DefinitionBody se especifica con el campo description establecido en la definición de API abierta. Esto provoca un conflicto en el campo description que AWS SAM no resuelve.
La propiedad DefinitionUri está especificada: AWS SAM no modificará una definición de API abierta que se recupere de Amazon S3.

Tipo: cadena

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

DisableExecuteApiEndpoint

Especifica si los clientes pueden invocar su API HTTP utilizando el execute-apipunto de conexiónhttps://{api_id}.execute-api.{region}.amazonaws.com predeterminado. De forma predeterminada, los clientes pueden invocar su API con el punto de enlace predeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar la API, desactive el punto de conexión predeterminado.

Para usar esta propiedad, debe especificar la DefinitionBody propiedad en lugar de la DefinitionUri propiedad o definirla x-amazon-apigateway-endpoint-configuration disableExecuteApiEndpoint en su definición de OpenAPI.

Tipo: Booleano

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es similar a la propiedad DisableExecuteApiEndpoint de un recurso AWS::ApiGatewayV2::Api. Se pasa directamente a la propiedad disableExecuteApiEndpoint de una extensión x-amazon-apigateway-endpoint-configuration, que se agrega a la propiedad Body de un recurso AWS::ApiGatewayV2::Api.

Domain

Configura un dominio personalizado para esta API HTTP de API Gateway.

Tipo: HttpAPIDomainConfiguration

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

FailOnWarnings

Especifica si se va a restaurar la creación de HTTP API (true) o no (false) cuando se encuentra una advertencia. El valor predeterminado es false.

Tipo: Booleano

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad FailOnWarnings de un recurso AWS::ApiGatewayV2::Api.

Name

El nombre del recurso de HTTP API.

Cuando especifica Name, AWS SAM modificará la definición de OpenAPI del recurso de la API HTTP configurando el campo title. Las siguientes situaciones producirán un error:

La propiedad DefinitionBody se especifica con el campo title establecido en la definición de API abierta. Esto provoca un conflicto en el campo title que AWS SAM no resuelve.
La propiedad DefinitionUri está especificada: AWS SAM no modificará una definición de API abierta que se recupere de Amazon S3.

Tipo: cadena

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

PropagateTags

Indique si quiere pasar o no las etiquetas de la propiedad Tags a los recursos generados AWS::Serverless::HttpApi. Especifica True para propagar las etiquetas en los recursos generados.

Tipo: Booleano

Obligatorio: no

Valor predeterminado: False

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

RouteSettings

La configuración de ruta, por ruta, para esta API HTTP. Para obtener más información, consulta Trabajar con rutas para API HTTP en la Guía para desarrolladores de API Gateway.

Type: RouteSettings

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad RouteSettings de un recurso AWS::ApiGatewayV2::Stage.

StageName

Es el nombre de la fase de la API. Si no se especifica ningún nombre, AWS SAM utiliza la etapa $default de API Gateway.

Tipo: cadena

Obligatorio: no

Valor predeterminado: $default

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad StageName de un recurso AWS::ApiGatewayV2::Stage.

StageVariables

Una asignación que define las variables de la fase. Los nombres de las variables pueden tener caracteres alfanuméricos y de subrayado. Los valores deben coincidir con [A-Za-z0-9-._~:/?#&=,]+.

Type: Json

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad se transfiere directamente a la propiedad StageVariables de un recurso AWS::ApiGatewayV2::Stage.

Tags

Un mapa (cadena a cadena) que especifica las etiquetas a añadir a esta etapa de API Gateway. Las claves pueden tener una longitud de entre 1 y 128 caracteres Unicode y no pueden incluir el prefijo aws:. Puede utilizar cualquiera de los siguientes caracteres: el conjunto de letras Unicode, dígitos, espacio en blanco, _, ., /, =, + y -. Los valores pueden tener de 1 a 256 caracteres Unicode.

Tipo: mapa

Obligatorio: no

Compatibilidad con AWS CloudFormation: esta propiedad es exclusiva de AWS SAM y no tiene un equivalente AWS CloudFormation.

Notas adicionales: La propiedad Tags requiere AWS SAM para modificar la definición de OpenAPI, por lo que las etiquetas se añaden solo si se especifica la propiedad DefinitionBody; no se añaden etiquetas si se especifica la propiedad DefinitionUri. AWS SAM añade automáticamente una etiqueta httpapi:createdBy:SAM Las etiquetas también se añaden al recurso AWS::ApiGatewayV2::Stage y al recurso AWS::ApiGatewayV2::DomainName (si DomainName se especifica).

Valores devueltos

Ref.

Cuando se pasa el ID lógico de este recurso a la función intrínseca Ref, Ref devuelve el ID de API del recurso subyacente AWS::ApiGatewayV2::Api, por ejemplo, a1bcdef2gh.

Para obtener más información sobre el uso de la función Ref, consulta Ref en la Guía del usuario de AWS CloudFormation.

Ejemplos

API HTTP sencilla

El siguiente ejemplo muestra el mínimo necesario para configurar un punto de conexión de la API HTTP respaldado por una función de Lambda. En este ejemplo, se utiliza la API HTTP predeterminada que crea AWS SAM.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Description: AWS SAM template with a simple API definition
Resources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: HttpApi
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Runtime: python3.7
Transform: AWS::Serverless-2016-10-31

HttpAPI con autenticación

El siguiente ejemplo muestra cómo configurar la autorización en puntos de conexión de API HTTP.

YAML


Properties:
  FailOnWarnings: true
  Auth:
    DefaultAuthorizer: OAuth2
    Authorizers:
      OAuth2:
        AuthorizationScopes:
          - scope4
        JwtConfiguration:
          issuer: "https://www.example.com/v1/connect/oauth2"
          audience:
            - MyApi
        IdentitySource: "$request.querystring.param"

HttpAPI con definición OpenAPI

El siguiente ejemplo muestra cómo añadir una definición de OpenAPI a la plantilla.

Tenga en cuenta que AWS SAM rellena las integraciones de Lambda que falten para los eventos HttpAPI que hacen referencia a esta API HTTP. AWS SAM también agrega las rutas faltantes a las que hacen referencia los eventos de HttpAPI.

YAML


Properties:
  FailOnWarnings: true
  DefinitionBody:
    info:
      version: '1.0'
      title:
        Ref: AWS::StackName
    paths:
      "/":
        get:
          security:
          - OpenIdAuth:
            - scope1
            - scope2
          responses: {}
    openapi: 3.0.1
    securitySchemes:
      OpenIdAuth:
        type: openIdConnect
        x-amazon-apigateway-authorizer:
          identitySource: "$request.querystring.param"
          type: jwt
          jwtConfiguration:
            audience:
            - MyApi
            issuer: https://www.example.com/v1/connect/oidc
          openIdConnectUrl: https://www.example.com/v1/connect/oidc/.well-known/openid-configuration

HttpAPI con opciones de configuración

El siguiente ejemplo muestra cómo añadir la API HTTP y configuraciones de escenario a la plantilla.

YAML


AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
  StageName:
    Type: String
    Default: Prod
    
Resources:
  HttpApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
          def handler(event, context):
              import json
              return {
                  "statusCode": 200,
                  "body": json.dumps(event),
              }
      Handler: index.handler
      Runtime: python3.7
      Events:
        ExplicitApi: # warning: creates a public endpoint
          Type: HttpApi
          Properties:
            ApiId: !Ref HttpApi
            Method: GET
            Path: /path
            TimeoutInMillis: 15000
            PayloadFormatVersion: "2.0"
            RouteSettings:
              ThrottlingBurstLimit: 600

  HttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      Tags:
        Tag: Value
      AccessLogSettings:
        DestinationArn: !GetAtt AccessLogs.Arn
        Format: $context.requestId
      DefaultRouteSettings:
        ThrottlingBurstLimit: 200
      RouteSettings:
        "GET /path":
          ThrottlingBurstLimit: 500 # overridden in HttpApi Event
      StageVariables:
        StageVar: Value
      FailOnWarnings: true

  AccessLogs:
    Type: AWS::Logs::LogGroup

Outputs:
  HttpApiUrl:
    Description: URL of your API endpoint
    Value:
      Fn::Sub: 'https://${HttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/'
  HttpApiId:
    Description: Api id of HttpApi
    Value:
      Ref: HttpApi

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Tiempo de ejecución

HttpApiAuth