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 RESTful APIs con menor latencia y costes más bajos que REST APIs. Para obtener más información, consulte [Trabajar con HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) en la *Guía para desarrolladores de API Gateway*.
Te recomendamos que utilices CloudFormation enlaces 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 CloudFormation ganchos, consulte [Registrar ganchos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) en la *guía del usuario de la CloudFormation CLI* y en el [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/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](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) en la *Guía para desarrolladores de API Gateway*.
**nota**
Al realizar la implementación en AWS CloudFormation, AWS SAM transforma AWS SAM los recursos en CloudFormation recursos. Para obtener más información, consulte [CloudFormation Recursos generados para AWS SAM](sam-specification-generated-resources.md).
## Sintaxis
Para declarar esta entidad en tu plantilla AWS Serverless Application Model (AWS SAM), usa la siguiente sintaxis.
### YAML
```
Type: AWS::Serverless::HttpApi
Properties:
[AccessLogSettings](#sam-httpapi-accesslogsettings): [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
[Auth](#sam-httpapi-auth): HttpApiAuth
[CorsConfiguration](#sam-httpapi-corsconfiguration): String | HttpApiCorsConfiguration
[DefaultRouteSettings](#sam-httpapi-defaultroutesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[DefinitionBody](#sam-httpapi-definitionbody): JSON
[DefinitionUri](#sam-httpapi-definitionuri): String | HttpApiDefinition
[Description](#sam-httpapi-description): String
[DisableExecuteApiEndpoint](#sam-httpapi-disableexecuteapiendpoint): Boolean
[Domain](#sam-httpapi-domain): HttpApiDomainConfiguration
[FailOnWarnings](#sam-httpapi-failonwarnings): Boolean
Name: String
PropagateTags: Boolean
[RouteSettings](#sam-httpapi-routesettings): [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
[StageName](#sam-httpapi-stagename): String
[StageVariables](#sam-httpapi-stagevariables): [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
[Tags](#sam-httpapi-tags): Map
```
## Propiedades
`AccessLogSettings`
Configuración del registro de acceso en una etapa.
*Tipo:* [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad se pasa directamente a la `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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, consulte [Control del acceso a HTTP APIs con autorizadores JWT](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) en la Guía para *desarrolladores de API Gateway*.
*Tipo:* [HttpApiAuth](sam-property-httpapi-httpapiauth.md)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.
`CorsConfiguration`
Administra el intercambio de recursos entre orígenes (CORS) para todos sus HTTP de API Gateway. APIs Especifica el dominio que quieres permitir como cadena o especifica un objeto `HttpApiCorsConfiguration`. Tenga en cuenta que CORS requiere AWS SAM modificar su definición de OpenAPI, por lo que CORS solo funciona si se especifica `DefinitionBody` la propiedad.
Para obtener más información, consulta [Configuración de CORS para API HTTP](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html) en la *Guía para desarrolladores de API Gateway*.
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: Cadena \$1 [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md)*
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad es exclusiva 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad se pasa directamente a la `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` propiedad de un `AWS::ApiGatewayV2::Stage` recurso.
`DefinitionBody`
La definición de OpenAPI que describe tu API HTTP. Si no especificas una `DefinitionUri` o una`DefinitionBody`, AWS SAM genera una `DefinitionBody` para ti en función de la configuración de la plantilla.
*Tipo*: JSON
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad es similar a la `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` propiedad de un `AWS::ApiGatewayV2::Api` recurso. Si se proporcionan determinadas propiedades, AWS SAM puede insertar contenido en ellas o modificarlas `DefinitionBody` antes de pasarlas a ellas CloudFormation. Las propiedades incluyen `Auth` un `EventSource` tipo HttpApi para el `AWS::Serverless::Function` recurso 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 especifica una `DefinitionUri` o `DefinitionBody` se especifica una, AWS SAM genera una `DefinitionBody` para usted en función de la configuración de la 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 OpenApi definición externos a los que haga referencia`DefinitionUri`. Para importar una OpenApi definición a la plantilla, utilice la `DefinitionBody` propiedad con la [transformación Include](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html).
*Tipo*: Cadena \$1 [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad es similar a la `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-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 lo especifiques`Description`, AWS SAM modificará la OpenApi definición del recurso de la API HTTP configurando el `description` campo. Las siguientes situaciones producirán un error:
+ La `DefinitionBody` propiedad se especifica con el `description` campo establecido en la definición de API abierta. Esto provoca un conflicto en el `description` campo que AWS SAM no se resuelve.
+ La `DefinitionUri` propiedad está especificada: 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-api`punto de conexión`https://{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 la `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` propiedad de un `AWS::ApiGatewayV2::Api` recurso. Se pasa directamente a la propiedad `disableExecuteApiEndpoint` de una extensión `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)`, que se agrega a la propiedad ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` de un recurso `AWS::ApiGatewayV2::Api`.
`Domain`
Configura un dominio personalizado para esta API HTTP de API Gateway.
*Tipo:* [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad es exclusiva 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 a la `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)` propiedad de un `AWS::ApiGatewayV2::Api` recurso.
`Name`
El nombre del recurso de HTTP API.
Cuando lo especifiques`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:
+ La `DefinitionBody` propiedad se especifica con el `title` campo establecido en la definición de API abierta. Esto provoca un conflicto en el `title` campo que AWS SAM no se resuelve.
+ La `DefinitionUri` propiedad está especificada: 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](sam-specification-generated-resources-httpapi.md). Especifica `True` para propagar las etiquetas en los recursos generados.
*Tipo*: Booleano
*Obligatorio*: no
*Valor predeterminado*: `False`
*CloudFormation compatibilidad*: esta propiedad es exclusiva 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, consulte [Trabajar con rutas para HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html) en la *Guía para desarrolladores de API Gateway*.
*Tipo:* [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad se transfiere directamente a la `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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 utiliza la `$default` etapa de API Gateway.
*Tipo:* cadena
*Obligatorio*: no
*Valor predeterminado*: \$1default
*CloudFormation compatibilidad*: esta propiedad se pasa directamente a la `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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-.\$1\$1:/?\$1&=,]\$1.
*Type*: [Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)
*Obligatorio*: no
*CloudFormation compatibilidad*: esta propiedad se pasa directamente a la `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-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 AWS SAM y no tiene un CloudFormation equivalente.
*Notas adicionales*: La `Tags` propiedad requiere AWS SAM modificar la definición de OpenAPI, por lo que las etiquetas se añaden solo si se especifica la `DefinitionBody` propiedad; 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 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html) en la *Guía del usuario de AWS CloudFormation *.
## Ejemplos
### Sencillo HttpApi
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 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 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 falten para HttpApi los eventos que hacen referencia a esta API HTTP. AWS SAM también agrega las rutas faltantes a las que hacen referencia HttpApi los 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
```