As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# AWS::Serverless::HttpApi
Cria uma API HTTP do Amazon API Gateway, que permite criar RESTful APIs com menor latência e custos mais baixos do que o REST APIs. Para obter mais informações, consulte [Trabalhando com HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html) no *Guia do Desenvolvedor do API Gateway*.
Recomendamos que você use CloudFormation ganchos ou políticas do IAM para verificar se os recursos do API Gateway têm autorizadores vinculados a eles para controlar o acesso a eles.
Para obter mais informações sobre o uso de CloudFormation ganchos, consulte [Registrando ganchos](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/registering-hook-python.html) no guia do *usuário da CloudFormation CLI* e no repositório. [apigw-enforce-authorizer](https://github.com/aws-cloudformation/aws-cloudformation-samples/tree/main/hooks/python-hooks/apigw-enforce-authorizer/) GitHub
Para obter mais informações sobre o uso de políticas do IAM, consulte [Exigir que as rotas de API tenham autorização](https://docs.aws.amazon.com/apigateway/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-require-authorization) no *Guia do desenvolvedor do API Gateway*.
**nota**
Quando você implanta AWS CloudFormation, AWS SAM transforma seus AWS SAM recursos em CloudFormation recursos. Para obter mais informações, consulte [CloudFormation Recursos gerados para AWS SAM](sam-specification-generated-resources.md).
## Sintaxe
Para declarar essa entidade em seu modelo AWS Serverless Application Model (AWS SAM), use a sintaxe a seguir.
### 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
```
## Propriedades
`AccessLogSettings`
As configurações para o registro em log de acesso em um estágio.
*Digite*: [AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.
`Auth`
Configura a autorização para controlar o acesso à sua API HTTP do API Gateway.
Para obter mais informações, consulte [Controle do acesso ao HTTP APIs com autorizadores JWT](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-jwt-authorizer.html) no Guia do *desenvolvedor do API Gateway*.
*Digite*: [HttpApiAuth](sam-property-httpapi-httpapiauth.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`CorsConfiguration`
Gerencia o compartilhamento de recursos de origem cruzada (CORS) para todo o seu API Gateway HTTP. APIs Especifique o domínio a ser permitido como uma string ou especifique um objeto `HttpApiCorsConfiguration`. Observe que o CORS AWS SAM precisa modificar sua definição de OpenAPI, então o CORS funciona somente se `DefinitionBody` a propriedade for especificada.
Para obter mais informações, consulte [Configurar o CORS para uma API HTTP](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html) no *Guia do desenvolvedor do API Gateway*.
Se `CorsConfiguration` for definido em uma definição de OpenAPI e no nível da propriedade, AWS SAM mesclará as duas fontes de configuração com as propriedades que têm precedência. Se essa propriedade for definida como `true`, todas as origens serão permitidas.
*Tipo*: String \$1 [HttpApiCorsConfiguration](sam-property-httpapi-httpapicorsconfiguration.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`DefaultRouteSettings`
As configurações de rota padrão para essa API HTTP. Essas configurações se aplicam a todas as rotas, a menos que sejam substituídas pela propriedade `RouteSettings` para determinadas rotas.
*Digite*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.
`DefinitionBody`
A definição de OpenAPI que descreve sua API HTTP. Se você não especificar um `DefinitionUri` ou um`DefinitionBody`, AWS SAM gera um `DefinitionBody` para você com base na configuração do seu modelo.
*Type*: JSON
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` propriedade de um `AWS::ApiGatewayV2::Api` recurso. Se determinadas propriedades forem fornecidas, AWS SAM poderá inserir conteúdo ou modificar o `DefinitionBody` antes de ser passado para CloudFormation. As propriedades incluem `Auth` e um `EventSource` do tipo HttpApi para um `AWS::Serverless::Function` recurso correspondente.
`DefinitionUri`
O URI, o caminho de arquivo local ou o objeto de localização do Amazon Simple Storage Service (Amazon S3) da definição de OpenAPI que define a API HTTP. O objeto Amazon S3 ao qual essa propriedade faz referência deve ser um arquivo de definição de OpenAPI válido. Se você não especificar a `DefinitionUri` ou se `DefinitionBody` for especificado, AWS SAM gera um `DefinitionBody` para você com base na configuração do seu modelo.
Se você fornecer um caminho de arquivo local, o modelo deverá passar pelo fluxo de trabalho que inclui o comando `sam deploy` ou `sam package` para que a definição seja transformada adequadamente.
As funções intrínsecas não são suportadas nos arquivos de OpenApi definição externos aos quais você faz referência. `DefinitionUri` Para importar uma OpenApi definição para o modelo, use a `DefinitionBody` propriedade com a [transformação 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*: String \$1 [HttpApiDefinition](sam-property-httpapi-httpapidefinition.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-bodys3location)` propriedade de um `AWS::ApiGatewayV2::Api` recurso. As propriedades aninhadas do Amazon S3 têm nomes diferentes.
`Description`
A descrição do recurso de API HTTP.
Quando você especificar`Description`, AWS SAM modificará a OpenApi definição do recurso da API HTTP definindo o `description` campo. Os seguintes cenários resultarão em um erro:
+ A `DefinitionBody` propriedade é especificada com o `description` campo definido na definição da Open API — isso resulta em um conflito do `description` campo que AWS SAM não será resolvido.
+ A `DefinitionUri` propriedade é especificada — AWS SAM não modificará uma definição de API aberta que é recuperada do Amazon S3.
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`DisableExecuteApiEndpoint`
Especifica se os clientes podem invocar sua API HTTP usando o endpoint `execute-api` padrão `https://{api_id}.execute-api.{region}.amazonaws.com`. Por padrão, os clientes podem invocar sua API com o endpoint padrão. Para exigir que os clientes usem somente um nome de domínio personalizado para invocar sua API, desabilite o endpoint padrão.
Para usar essa propriedade, você deve especificar a propriedade `DefinitionBody` em vez da propriedade `DefinitionUri` ou definir `x-amazon-apigateway-endpoint-configuration` com `disableExecuteApiEndpoint` na definição de OpenAPI.
*Tipo*: booliano
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableexecuteapiendpoint)` propriedade de um `AWS::ApiGatewayV2::Api` recurso. Ele é passado diretamente para a propriedade `disableExecuteApiEndpoint` de uma extensão `[ x-amazon-apigateway-endpoint-configuration](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-endpoint-configuration.html)`, que é adicionada à propriedade ` [ Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-body)` de um recurso `AWS::ApiGatewayV2::Api`.
`Domain`
Configura um domínio personalizado para essa API HTTP do API Gateway.
*Digite*: [HttpApiDomainConfiguration](sam-property-httpapi-httpapidomainconfiguration.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`FailOnWarnings`
Especifica se deve reverter a criação da API HTTP (`true`) ou não (`false`) quando um aviso é encontrado. O valor padrão é `false`.
*Tipo*: booliano
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-failonwarnings)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.
`Name`
O nome do recurso API HTTP.
Quando você especificar`Name`, AWS SAM modificará a definição de openAPI do recurso da API HTTP definindo o `title` campo. Os seguintes cenários resultarão em um erro:
+ A `DefinitionBody` propriedade é especificada com o `title` campo definido na definição da Open API — isso resulta em um conflito do `title` campo que AWS SAM não será resolvido.
+ A `DefinitionUri` propriedade é especificada — AWS SAM não modificará uma definição de API aberta que é recuperada do Amazon S3.
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`PropagateTags`
Indique se deseja ou não passar as tags da propriedade `Tags` para os recursos [AWS::Serverless::HttpApi](sam-specification-generated-resources-httpapi.md) gerados. Especifique `True` para propagar as tags nos recursos gerados.
*Tipo*: booliano
*Obrigatório*: não
*Padrão*: `False`
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`RouteSettings`
As configurações de rota, por rota, para essa API HTTP. Para obter mais informações, consulte Como [trabalhar com rotas para HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-routes.html) no *Guia do desenvolvedor do API Gateway*.
*Digite*: [RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.
`StageName`
O nome do estágio da API. Se nenhum nome for especificado, AWS SAM usa o `$default` estágio do API Gateway.
*Tipo:* string
*Obrigatório*: não
*Padrão*: \$1default
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagename)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.
`StageVariables`
Um mapa que define as variáveis da etapa. Os nomes das variáveis podem ter caracteres alfanuméricos e sublinhados. Os valores devem corresponder a [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)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[StageVariables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.
`Tags`
Um mapa (string para string) que especifica as tags a serem adicionadas a esse estágio do API Gateway. As chaves podem ter de 1 a 128 caracteres Unicode e não podem incluir o prefixo `aws:`. Use qualquer um dos seguintes caracteres: o conjunto de letras, dígitos, espaço em branco, `_`, `.`, `/`, `=`, `+` e `-`. Os valores podem ter de 1 a 256 caracteres Unicode.
*Tipo*: mapa
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
*Observações adicionais*: a `Tags` propriedade AWS SAM precisa modificar sua definição de OpenAPI. Portanto, as tags são adicionadas somente se a `DefinitionBody` propriedade for especificada. Nenhuma tag será adicionada se a propriedade for especificada. `DefinitionUri` AWS SAM adiciona automaticamente uma `httpapi:createdBy:SAM` tag. As tags também são adicionadas ao recurso `AWS::ApiGatewayV2::Stage` e ao recurso `AWS::ApiGatewayV2::DomainName` (se `DomainName` for especificado).
## Valores de retorno
### Ref.
Quando você transmite o ID lógico desse recurso para a função intrínseca `Ref`, `Ref` retorna o ID da API do recurso `AWS::ApiGatewayV2::Api` subjacente, como `a1bcdef2gh`.
Para obter mais informações sobre como usar a função `Ref`, consulte [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) no *Guia do usuário do AWS CloudFormation *.
## Exemplos
### Simples HttpApi
O exemplo a seguir mostra o mínimo necessário para configurar um endpoint de API HTTP apoiado por uma função do Lambda. Este exemplo usa a API HTTP padrão que AWS SAM cria.
#### 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 com Auth
O exemplo a seguir mostra como configurar a autorização em endpoints da 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 com definição de OpenAPI
O exemplo a seguir mostra como adicionar uma definição de OpenAPI ao modelo.
Observe que AWS SAM preenche todas as integrações Lambda ausentes HttpApi para eventos que fazem referência a essa API HTTP. AWS SAM também adiciona todos os caminhos ausentes aos quais os HttpApi eventos fazem referência.
#### 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 com definições de configuração
O exemplo a seguir mostra como adicionar configurações da API HTTP e do estágio ao modelo.
#### 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
```