AWS::Serverless::HttpApi - AWS Serverless Application Model
SintaxePropriedadesValores de retornoExemplos

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 APIs RESTful com menor latência e custos mais baixos do que APIs REST. Para obter mais informações, consulte Trabalhar com APIs HTTP no Guia do desenvolvedor do Gateway da API.

Recomendamos que você use os hooks CloudFormation 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 hooks do CloudFormation, consulte Registering hooks no Guia do usuário do CloudFormation e no repositório apigw-enforce-authorizer do GitHub.

Para obter mais informações sobre o uso de políticas do IAM, consulte Exigir que as rotas de API tenham autorização no Guia do desenvolvedor do API Gateway.

nota

Quando você implanta no AWS CloudFormation, AWS SAM transforma seus recursos AWS SAM em recursos CloudFormation. Para obter mais informações, consulte Recursos gerados do CloudFormation para o AWS SAM.

Sintaxe

Para declarar esta entidade no modelo do AWS Serverless Application Model (AWS SAM), use a seguinte sintaxe:

Propriedades

AccessLogSettings

As configurações para o registro em log de acesso em um estágio.

Type: AccessLogSettings

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade AccessLogSettings de um recurso AWS::ApiGatewayV2::Stage.

Auth

Configura a autorização para controlar o acesso à sua API HTTP do API Gateway.

Para mais informações, consulte Controlar o acesso a APIs HTTP com autorizadores JWT no Guia do desenvolvedor do API Gateway.

Tipo: HttpApiAuth

Obrigatório: não

Compatibilidade CloudFormation: Essa propriedade é exclusiva do AWS SAM e não tem CloudFormation equivalente.

CorsConfiguration

Gerencia o compartilhamento de recursos de origem cruzada (CORS) para todas as APIs HTTP do API Gateway. Especifique o domínio a ser permitido como uma string ou especifique um objeto HttpApiCorsConfiguration. Observe que o CORS exige AWS SAM para modificar sua definição de OpenAPI, então o CORS funciona somente se a propriedade DefinitionBody for especificada.

Para obter mais informações, consulte Configurar o CORS para uma API HTTP no Guia do desenvolvedor do API Gateway.

nota

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

Obrigatório: não

Compatibilidade CloudFormation: Essa propriedade é exclusiva do 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.

Type: RouteSettings

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade RouteSettings de um recurso AWS::ApiGatewayV2::Stage.

DefinitionBody

A definição de OpenAPI que descreve sua API HTTP. Se você não especificar a DefinitionUri ou a DefinitionBody, AWS SAM gera um DefinitionBody para você com base na configuração do seu modelo.

Type: JSON

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade Body de um recurso AWS::ApiGatewayV2::Api. Se determinadas propriedades forem fornecidas, AWS SAM poderá inserir conteúdo ou modificar DefinitionBody antes de ser passado para CloudFormation. As propriedades incluem Auth e um EventSource do tipo HttpAPI para um recurso AWS::Serverless::Function 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 um DefinitionUri ou se um DefinitionBody for especificado, AWS SAM gera 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 externos de definição da OpenAPI aos quais você faz referência com DefinitionUri. Para importar uma definição de OpenAPI para o modelo, use a propriedade DefinitionBody com a transformação Incluir.

Tipo: String | HttpApiDefinition

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade BodyS3Location de um recurso AWS::ApiGatewayV2::Api. 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 definição de openAPI do recurso da API HTTP definindo o campo description. Os seguintes cenários resultarão em um erro:

  • A propriedade DefinitionBody é especificada com o campo description definido na definição da Open API — isso resulta em um conflito do campo description que AWS SAM não resolverá.

  • A propriedade DefinitionUri é especificada — AWS SAM não modificará uma definição de API aberta que é recuperada do Amazon S3.

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: Essa propriedade é exclusiva do 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

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade DisableExecuteApiEndpoint de um recurso AWS::ApiGatewayV2::Api. Ele é passado diretamente para a propriedade disableExecuteApiEndpoint de uma extensão x-amazon-apigateway-endpoint-configuration, que é adicionada à propriedade Body de um recurso AWS::ApiGatewayV2::Api.

Domain

Configura um domínio personalizado para essa API HTTP do API Gateway.

Tipo: HttpApIdoMainConfiguration

Obrigatório: não

Compatibilidade CloudFormation: Essa propriedade é exclusiva do 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

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade FailOnWarnings de um recurso AWS::ApiGatewayV2::Api.

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 campo title. Os seguintes cenários resultarão em um erro:

  • A propriedade DefinitionBody é especificada com o campo title definido na definição da Open API — isso resulta em um conflito do campo title que AWS SAM não resolverá.

  • A propriedade DefinitionUri é especificada — AWS SAM não modificará uma definição de API aberta que é recuperada do Amazon S3.

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: Essa propriedade é exclusiva do 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 gerados. Especifique True para propagar as tags nos recursos gerados.

Tipo: booliano

Obrigatório: não

Padrão: False

Compatibilidade CloudFormation: Essa propriedade é exclusiva do 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 Trabalhar com rotas para APIs HTTP no Guia do desenvolvedor do Gateway da API.

Type: RouteSettings

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade RouteSettings de um recurso AWS::ApiGatewayV2::Stage.

StageName

O nome do estágio da API. Se nenhum nome for especificado, AWS SAM usa o estágio $default do API Gateway.

Tipo: string

Obrigatório: não

Padrão: $default

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade StageName de um recurso AWS::ApiGatewayV2::Stage.

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-._~:/? #&=,] +.

Type: Json

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade StageVariables de um recurso AWS::ApiGatewayV2::Stage.

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

Compatibilidade CloudFormation: Essa propriedade é exclusiva do AWS SAM e não tem CloudFormation equivalente.

Observações adicionais: a propriedade Tags exige AWS SAM para modificar sua definição de OpenAPI. Portanto, as tags são adicionadas somente se a propriedade DefinitionBody for especificada. Nenhuma tag será adicionada se a propriedade DefinitionUri for especificada. AWS SAMadiciona automaticamente uma tag httpapi:createdBy:SAM. 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 Ref no Guia do usuário do AWS CloudFormation.

Exemplos

API HTTP simples

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 para eventos HttpAPI que fazem referência a essa API HTTP. AWS SAM também adiciona todos os caminhos ausentes aos quais os eventos HttpAPI 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 da 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