View a markdown version of this page

AWS::Serverless::HttpApi - AWS Serverless Application Model

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

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.

Le recomendamos que utilice CloudFormation ganchos o políticas de IAM para verificar que los recursos de API Gateway tengan autorizadores adjuntos para controlar el acceso a ellos.

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

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.

Este recurso también es compatible con Connectors recurso Attribute. Para obtener más información, consulte Administrar los permisos de recursos con AWS SAM conectores.

nota

Cuando se implementa en AWS CloudFormation, AWS SAM transforma tu AWS SAM recursos en CloudFormation recursos. Para obtener más información, consulte Generado CloudFormation recursos para AWS SAM.

Sintaxis

Para declarar esta entidad en su AWS Serverless Application Model (AWS SAM), utilice la siguiente sintaxis.

Propiedades

AccessLogSettings

Configuración del registro de acceso en una etapa.

Tipo: AccessLogSettings

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad se pasa directamente al AccessLogSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

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

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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 DefinitionBody se especifica la propiedad.

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 a nivel de propiedad, entonces AWS SAM fusiona ambas fuentes de configuración con las propiedades que tienen prioridad. Si esta propiedad está establecida en true, se permiten todos los orígenes.

Escriba: Cadena | HttpApiCorsConfiguration

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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.

Tipo: RouteSettings

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad se pasa directamente al RouteSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

DefinitionBody

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

Tipo: JSON

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es similar a Body propiedad de un AWS::ApiGatewayV2::Api recurso. Si se proporcionan ciertas propiedades, AWS SAM puede insertar contenido en el DefinitionBody antes de pasarlo a CloudFormation. Las propiedades incluyen Auth y un EventSource de tipo HttpApi para un correspondiente AWS::Serverless::Function recurso.

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 un DefinitionBody se especifican, 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 son compatibles con las funciones externas OpenApi archivos de definición a los que hace referencia DefinitionUri. Para importar un OpenApi definición en la plantilla, utilice el DefinitionBody propiedad con Incluir transformación.

Escriba: Cadena | HttpApiDefinition

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es similar a BodyS3Location propiedad de un AWS::ApiGatewayV2::Api recurso. Las propiedades anidadas de Amazon S3 tienen un nombre diferente.

Description

La descripción del recurso de la API HTTP.

Cuando especificas Description, AWS SAM modificará los recursos de la API HTTP OpenApi definición mediante el establecimiento de description campo. Las siguientes situaciones producirán un error:

  • El DefinitionBody la propiedad se especifica con description campo establecido en la definición de Open API: esto da como resultado un conflicto de description campo que AWS SAM no se resolverá.

  • El DefinitionUri se especifica la propiedad — AWS SAM no modificará una definición de API abierta que se recupere de Amazon S3.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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 propiedad DefinitionBody en lugar de la propiedad DefinitionUri o definir x-amazon-apigateway-endpoint-configuration con disableExecuteApiEndpoint en su definición de OpenAPI.

Tipo: Booleano

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es similar a DisableExecuteApiEndpoint propiedad de un AWS::ApiGatewayV2::Api recurso. 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

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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

CloudFormation compatibilidad: Esta propiedad se pasa directamente al FailOnWarnings propiedad de un AWS::ApiGatewayV2::Api recurso.

Name

El nombre del recurso de HTTP API.

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

  • El DefinitionBody la propiedad se especifica con title campo establecido en la definición de Open API: esto da como resultado un conflicto de title campo que AWS SAM no se resolverá.

  • El DefinitionUri se especifica la propiedad — AWS SAM no modificará una definición de API abierta que se recupere de Amazon S3.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

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.

Tipo: RouteSettings

Obligatorio: no

CloudFormation compatibilidad: Esta propiedad se pasa directamente al RouteSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

StageName

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

Tipo: cadena

Obligatorio: no

Valor predeterminado: $default

CloudFormation compatibilidad: Esta propiedad se pasa directamente al StageName propiedad de un AWS::ApiGatewayV2::Stage recurso.

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

CloudFormation compatibilidad: Esta propiedad se pasa directamente al StageVariables propiedad de un AWS::ApiGatewayV2::Stage recurso.

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

CloudFormation compatibilidad: Esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

Notas adicionales: El Tags la propiedad requiere AWS SAM para modificar la definición de OpenAPI, de modo que las etiquetas solo se añadan si DefinitionBody se especifica la propiedad; no se agrega ninguna etiqueta si DefinitionUri se especifica la propiedad. AWS SAM añade automáticamente un httpapi:createdBy:SAM etiqueta. 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

Sencillo HttpApi

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

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 Auth

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 la definición de 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 faltan para HttpApi eventos que hacen referencia a esta API HTTP. AWS SAM también agrega las rutas faltantes que HttpApi referencia de eventos.

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 ajustes 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