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

Crea una API HTTP de Amazon API Gateway, que le permite crear API RESTful con menor latencia y menor coste que las API REST. Para obtener más información, consulteUso de API HTTPen laGuía para desarrolladores de API Gateway.

Recomendamos utilizarAWS CloudFormationhooks o políticas de IAM para verificar que los recursos de API Gateway tienen autorizadores asociados a ellos para controlar el acceso a ellos.

Para obtener más información acerca del uso deAWS CloudFormationEnlaces, consulteRegistro de los anzuelosen laAWS CloudFormationGuía del usuario de CLIy laautorizador apigw-enforce- GitHub .

Para obtener más información sobre el uso de políticas de IAM, consulteRequerir que las rutas API tengan autorizaciónen laGuía para desarrolladores de API Gateway.

Sintaxis

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

Properties

AccessLogSettings

Es la configuración para el registro de acceso en una fase.

Type: AccessLogSettings

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alAccessLogSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso.

Auth

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

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

Type: HTTP: Papiauth

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tiene unAWS CloudFormationequivalente.

CorsConfiguration

Administra el Cross-Origin Resource Sharing (CORS, Uso compartido de recursos entre orígenes) para todas sus API HTTP de Especifique el dominio que se va a permitir como cadena o especifique unHttpApiCorsConfigurationobjeto. Tenga en cuenta que CORS requiereAWS SAMpara modificar su definición de OpenAPI, de modo que CORS solo funciona si elDefinitionBodyse especifica la propiedad.

Para obtener más información, consulteConfiguración de CORS para una API HTTPen laGuía para desarrolladores de API Gateway.

Nota: SiCorsConfigurationse establece tanto en una definición de OpenAPI como en el nivel de propiedad y, a continuaciónAWS SAMfusiona ambos orígenes de configuración con las propiedades que tienen prioridad.

Nota: Si esta propiedad está establecida entrue, entonces se permiten todos los orígenes.

Type: Cadena |Configuración de Httapicors

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tiene unAWS CloudFormationequivalente.

DefaultRouteSettings

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

Type: RouteSettings

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alRouteSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso.

DefinitionBody

La definición de OpenAPI que describe la API HTTP. Si no especifica unDefinitionUrio unDefinitionBody,AWS SAMgenera unDefinitionBodypara ti en función de la configuración de tu plantilla.

Type: JSON

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laBodypropiedad de unAWS::ApiGatewayV2::Apirecurso. Si se proporcionan determinadas propiedades,AWS SAMpuede insertar contenido o modificar elDefinitionBodyantes de que se pase aAWS CloudFormation. Las propiedades incluyenAuthy unEventSourcede tipo HttpApi para un correspondienteAWS::Serverless::Functionrecurso.

DefinitionUri

El URI de Amazon Simple Storage Service (Amazon S3), la ruta de archivo local u objeto de ubicación de la definición 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 especifica unDefinitionUrio unDefinitionBodyse especifican,AWS SAMgenera unDefinitionBodypara ti en función de la configuración de tu plantilla.

Si proporciona una ruta de archivo local, la plantilla debe pasar por el flujo de trabajo que incluye elsam deployosam packagepara que la definición se transforme correctamente.

Las funciones intrínsecas no se admiten en externas OpenApi archivos de definición a los que hace referenciaDefinitionUri. Para importar un OpenApi definición en la plantilla, utilice laDefinitionBodypropiedad con elIncluir transformación.

Type: Cadena |Definición HTTP PAP

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es similar a laBodyS3Locationpropiedad de unAWS::ApiGatewayV2::Apirecurso. Las propiedades de Amazon S3 anidadas tienen un nombre diferente.

Description

Una descripción de la HttpApi recurso.

Nota: Esta propiedad requiereAWS SAMpara modificar el HttpApi definición de openAPI del recurso, para configurar ladescription. Los dos escenarios siguientes producen un error: 1) ElDefinitionBodyse especifica con eldescriptionconjunto de campo en la definición de OpenAPI (ya que se trata de un conflicto queAWS SAMno se resolverá) o 2) ElDefinitionUrise especifica la propiedad (desdeAWS SAMno modificará una definición de OpenAPI que recupera de Amazon S3).

Type: Cadena

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tiene unAWS CloudFormationequivalente.

DisableExecuteApiEndpoint

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

Type: Booleano

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alDisableExecuteApiEndpointpropiedad de unAWS::ApiGatewayV2::Apirecurso.

Domain

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

Type: Configuración de dominio HTTP

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tiene unAWS CloudFormationequivalente.

FailOnWarnings

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

Type: Booleano

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alFailOnWarningspropiedad de unAWS::ApiGatewayV2::Apirecurso.

RouteSettings

La configuración de ruta, por ruta, de esta API HTTP. Para obtener más información, consulteUso de rutas para API HTTPen laGuía para desarrolladores de API Gateway.

Type: RouteSettings

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alRouteSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso.

StageName

El nombre de la etapa de la API. Si no se especifica ningún nombre,AWS SAMutiliza el$defaultetapa desde API Gateway.

Type: Cadena

Obligatorio: No

Predeterminado: $default

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alStageNamepropiedad de unAWS::ApiGatewayV2::Stagerecurso.

StageVariables

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

Type: Json

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad se transfiere directamente alStageVariablespropiedad de unAWS::ApiGatewayV2::Stagerecurso.

Tags

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

Type: Mapeo

Obligatorio: No

AWS CloudFormationcompatibilidad: Esta propiedad es específica deAWS SAMy no tiene unAWS CloudFormationequivalente.

Notas adicionales: LaTagsLa propiedad requiereAWS SAMpara modificar la definición de OpenAPI, de modo que las etiquetas solo se añadirán siDefinitionBodyse especifica la propiedad: no se agregan etiquetas si elDefinitionUrise especifica la propiedad.AWS SAMañade automáticamente unhttpapi:createdBy:SAMetiqueta. Las etiquetas también se añaden alAWS::ApiGatewayV2::Stagerecurso y elAWS::ApiGatewayV2::DomainNamerecurso (siDomainNamese especifica).

Valores devueltos

Ref.

Cuando se transfiere el ID lógico de este recurso al intrínsecoReffunción,Refdevuelve el ID de API del subyacenteAWS::ApiGatewayV2::Apirecurso, por ejemplo,a1bcdef2gh.

Para obtener más información acerca del uso deReffunción, consulteRefen laAWS CloudFormationGuía del usuario de.

Ejemplos

HttpApi simple

En el ejemplo siguiente se muestra el mínimo necesario para configurar un extremo de API HTTP respaldado por una función Lambda. Este ejemplo utiliza la API HTTP predeterminada queAWS SAMcrea.

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 enlace 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" OpenIdAuth: AuthorizationScopes: - scope1 - scope2 OpenIdConnectUrl: "https://www.example.com/v1/connect/oidc/.well-known/openid-configuration" JwtConfiguration: issuer: "https://www.example.com/v1/connect/oidc" audience: - MyApi IdentitySource: "$request.querystring.param"

HttpAPI con definición de OpenAPI

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

Tenga en cuenta queAWS SAMrellena las integraciones Lambda faltantes para HttpApi eventos que hacen referencia a esta API HTTP.AWS SAMtambién añade cualquier ruta que falte 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 configuraciones de fase y API HTTP 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