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
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.
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.
YAML
Type: AWS::Serverless::HttpApi Properties: AccessLogSettings:AccessLogSettingsAuth:HttpApiAuthCorsConfiguration:String | HttpApiCorsConfigurationDefaultRouteSettings:RouteSettingsDefinitionBody:JSONDefinitionUri:String | HttpApiDefinitionDescription:StringDisableExecuteApiEndpoint:BooleanDomain:HttpApiDomainConfigurationFailOnWarnings:BooleanName:StringPropagateTags:BooleanRouteSettings:RouteSettingsStageName:StringStageVariables:JsonTags:Map
Propiedades
-
AccessLogSettings -
Configuración del registro de acceso en una etapa.
Tipo: AccessLogSettings
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
AccessLogSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso. -
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 siDefinitionBodyse 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.
notaSi
CorsConfigurationse 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 entrue, 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
RouteSettingsla anula para determinadas rutas.Tipo: RouteSettings
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
RouteSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso. -
DefinitionBody -
La definición de OpenAPI que describe tu API HTTP. Si no especificas un
DefinitionUrio unDefinitionBody, AWS SAM genera unDefinitionBodypara usted en función de la configuración de su plantilla.Tipo: JSON
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
Bodypropiedad de unAWS::ApiGatewayV2::Apirecurso. Si se proporcionan ciertas propiedades, AWS SAM puede insertar contenido en elDefinitionBodyantes de pasarlo a CloudFormation. Las propiedades incluyenAuthy unEventSourcede tipo HttpApi para un correspondienteAWS::Serverless::Functionrecurso. -
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
DefinitionUrio unDefinitionBodyse especifican, AWS SAM genera unDefinitionBodypara 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 deployosam packagepara 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 elDefinitionBodypropiedad con Incluir transformación.Escriba: Cadena | HttpApiDefinition
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
BodyS3Locationpropiedad de unAWS::ApiGatewayV2::Apirecurso. 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 dedescriptioncampo. Las siguientes situaciones producirán un error:-
El
DefinitionBodyla propiedad se especifica condescriptioncampo establecido en la definición de Open API: esto da como resultado un conflicto dedescriptioncampo que AWS SAM no se resolverá. -
El
DefinitionUrise 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.compredeterminado. 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
DefinitionBodyen lugar de la propiedadDefinitionUrio definirx-amazon-apigateway-endpoint-configurationcondisableExecuteApiEndpointen su definición de OpenAPI.Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad es similar a
DisableExecuteApiEndpointpropiedad de unAWS::ApiGatewayV2::Apirecurso. Se pasa directamente a la propiedaddisableExecuteApiEndpointde una extensiónx-amazon-apigateway-endpoint-configuration, que se agrega a la propiedadBodyde un recursoAWS::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 esfalse.Tipo: Booleano
Obligatorio: no
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
FailOnWarningspropiedad de unAWS::ApiGatewayV2::Apirecurso. 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 eltitlecampo. Las siguientes situaciones producirán un error:-
El
DefinitionBodyla propiedad se especifica contitlecampo establecido en la definición de Open API: esto da como resultado un conflicto detitlecampo que AWS SAM no se resolverá. -
El
DefinitionUrise 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.
-
-
Indique si quiere pasar o no las etiquetas de la propiedad
Tagsa los recursos generados AWS::Serverless::HttpApi. EspecificaTruepara propagar las etiquetas en los recursos generados.Tipo: Booleano
Obligatorio: no
Valor predeterminado:
FalseCloudFormation 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
RouteSettingspropiedad de unAWS::ApiGatewayV2::Stagerecurso. -
StageName -
Es el nombre de la fase de la API. Si no se especifica ningún nombre, AWS SAM usa el
$defaultetapa desde API Gateway.Tipo: cadena
Obligatorio: no
Valor predeterminado: $default
CloudFormation compatibilidad: Esta propiedad se pasa directamente al
StageNamepropiedad de unAWS::ApiGatewayV2::Stagerecurso. -
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
StageVariablespropiedad de unAWS::ApiGatewayV2::Stagerecurso. -
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
Tagsla propiedad requiere AWS SAM para modificar la definición de OpenAPI, de modo que las etiquetas solo se añadan siDefinitionBodyse especifica la propiedad; no se agrega ninguna etiqueta siDefinitionUrise especifica la propiedad. AWS SAM añade automáticamente unhttpapi:createdBy:SAMetiqueta. Las etiquetas también se añaden al recursoAWS::ApiGatewayV2::Stagey al recursoAWS::ApiGatewayV2::DomainName(siDomainNamese 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