AWS::Serverless::Api - 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::Api

Cria uma coleção de recursos e métodos do Amazon API Gateway que podem ser invocados por meio de endpoints HTTPS.

Um recurso AWS::Serverless::Api não precisa ser adicionado explicitamente a um modelo de definição de aplicativo com tecnologia sem servidor AWS. Um recurso desse tipo é criado implicitamente a partir da união de eventos de API definidos nos recursos AWS::Serverless::Function definidos no modelo que não se referem a um recurso AWS::Serverless::Api.

Um recurso AWS::Serverless::Api deve ser usado para definir e documentar a API usando o OpenAPI, que fornece mais capacidade de configurar os recursos subjacentes do Amazon API Gateway.

Recomendamos que você use 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 CloudFormation, consulte Registrar ganchos no CloudFormation Guia do usuário da CLI 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

AccessLogSetting

Configura a configuração do log de acesso para um estágio.

Type: AccessLogSetting

Obrigatório: não

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

AlwaysDeploy

Sempre implanta a API, mesmo quando nenhuma alteração na API foi detectada.

Tipo: booliano

Obrigatório: não

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

ApiKeySourceType

A origem da chave de API para as solicitações de medição de acordo com um plano de uso. Os valores válidos são HEADER e AUTHORIZER.

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade ApiKeySourceType de um recurso AWS::ApiGateway::RestApi.

Auth

Configure a autorização para controlar o acesso à sua API API Gateway.

Para obter mais informações sobre como configurar o acesso usando o AWS SAM, consulte Controlar o acesso à API com o modelo do AWS SAM. Para ver um exemplo de como substituir um autorizador global, consulte Substitua um autorizador global para sua API REST do Amazon API Gateway.

Tipo: ApiAuth

Obrigatório: não

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

BinaryMediaTypes

Lista de tipos de MIME que sua API pode retornar. Use isso para ativar o suporte binário para APIs.

Tipo: lista

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade BinaryMediaTypes de um recurso AWS::ApiGateway::RestApi. A lista de BinaryMediaTypes é adicionada ao recurso CloudFormation e ao documento da OpenAPI.

CacheClusterEnabled

Indica se o cache está habilitado para o estágio. Para armazenar respostas em cache, você também deve definir CachingEnabled como true abaixo MethodSettings.

Tipo: booliano

Obrigatório: não

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

CacheClusterSize

O tamanho do cluster de cache da etapa.

Tipo: string

Obrigatório: não

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

CanarySetting

Configure uma configuração de canário para um estágio de uma implantação regular.

Type: CanarySetting

Obrigatório: não

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

Cors

Gerencie o compartilhamento de recursos entre origens (CORS), cross-origin resource sharing) para todas as suas APIs do API Gateway. Especifique o domínio a ser permitido como uma string ou especifique um dicionário com configuração adicional do Cors.

nota

O CORS exige o AWS SAM para modificar a definição de OpenAPI. Crie uma definição de OpenAPI em linha no DefinitionBody para ativar o CORS.

Para obter mais informações sobre o CORS, consulte Habilitar o CORS para um recurso API REST para a API Gateway no Guia do desenvolvedor do API Gateway.

Tipo: String | CorsConfiguration

Obrigatório: não

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

DefinitionBody

Especificação OpenAPI que descreve sua API. Se o DefinitionUri nem o DefinitionBody for especificado, o SAM gerará um DefinitionBody para você com base na configuração do seu modelo.

Para fazer referência a um arquivo OpenAPI local que define sua API, use a transformação AWS::Include. Para saber mais, consulte Como o AWS SAM faz upload de arquivos locais.

Type: JSON

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade Body de um recurso AWS::ApiGateway::RestApi. Se determinadas propriedades forem fornecidas, o conteúdo poderá ser inserido ou modificado no DefinitionBody antes de ser passado para o CloudFormation. As propriedades incluem Auth, BinaryMediaTypes, Cors, GatewayResponses, Models, e um EventSource tipo API para um arquivo AWS::Serverless::Function.

DefinitionUri

Uri do Amazon S3, caminho de arquivo local ou objeto de localização do documento OpenAPI que define a API. O objeto do Amazon S3 a que essa propriedade faz referência deve ser um arquivo OpenAPI válido. Se o DefinitionUri nem o DefinitionBody for especificado, o SAM gerará um DefinitionBody para você com base na configuração do seu modelo.

Se um caminho de arquivo local for fornecido, 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 em arquivos OpenAPI externos referenciados por DefinitionUri. Em vez disso, use a propriedade DefinitionBody com o Include Transform para importar uma definição de OpenAPI para o modelo.

Tipo: String | ApiDefinition

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade BodyS3Location de um recurso AWS::ApiGateway::RestApi. As propriedades aninhadas do Amazon S3 têm nomes diferentes.

Description

Uma descrição do recurso da API.

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade Description de um recurso AWS::ApiGateway::RestApi.

DisableExecuteApiEndpoint

Especifica se os clientes podem invocar sua API usando o endpoint execute-api padrão. Por padrão, os clientes podem invocar sua API com o padrão https://{api_id}.execute-api.{region}.amazonaws.com. Para exigir que os clientes usem um nome de domínio personalizado para invocar sua API, especifique True.

Tipo: booliano

Obrigatório: não

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

Domain

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

Tipo: DomainConfiguration

Obrigatório: não

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

EndpointConfiguration

O tipo de endpoint de uma API REST.

Type: EndpointConfiguration

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade EndpointConfiguration de um recurso AWS::ApiGateway::RestApi. As propriedades aninhadas de configuração têm nomes diferentes.

FailOnWarnings

Especifica se deve reverter a criação da API (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::ApiGateway::RestApi.

GatewayResponses

Configura as respostas do Gateway para uma API. As respostas do Gateway são respostas retornadas pelo API Gateway, diretamente ou por meio do uso de autorizadores do Lambda. Para obter mais informações, consulte a documentação da extensão OpenAPI da Api Gateway para respostas do Gateway.

Tipo: mapa

Obrigatório: não

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

MergeDefinitions

O AWS SAM gera uma especificação OpenAPI da sua fonte de eventos de API. Especifique true para o AWS SAM mesclar isso na especificação OpenAPI embutida definida em seu recurso AWS::Serverless::Api. Especifique false para não mesclar.

O MergeDefinitions requer que DefinitionBody a propriedade AWS::Serverless::Api seja definida. O MergeDefinitions não é compatível com a propriedade DefinitionUri para AWS::Serverless::Api.

Valor padrão: false

Tipo: booliano

Obrigatório: não

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

MethodSettings

Define todas as configurações para o estágio da API, incluindo Logging, Métricas, CacheTTL, controle de utilização.

Tipo: lista de MethodSetting

Obrigatório: não

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

MinimumCompressionSize

Permita a compactação dos corpos de resposta com base no cabeçalho Accept-Encoding do cliente. A compressão é acionada quando o tamanho do corpo da resposta é maior ou igual ao limite configurado. O limite máximo de tamanho do corpo é de 10 MB (10.485.760 bytes). - Os seguintes tipos de compactação são suportados: gzip, deflate e identity.

Tipo: inteiro

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade MinimumCompressionSize de um recurso AWS::ApiGateway::RestApi.

Mode

Essa propriedade se aplica somente quando você usa a OpenAPI para definir sua API REST. O Mode determina como o API Gateway trata atualizações de recursos. Para obter mais informações, consulte a propriedade Mode do tipo de recurso AWS::ApiGateway::RestApi.

Valores válidos: overwrite ou merge

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade Mode de um recurso AWS::ApiGateway::RestApi.

Models

Os esquemas a serem usados pelos seus métodos de API. Esses esquemas podem ser descritos usando JSON ou YAML. Consulte a seção Exemplos na parte inferior desta página para ver exemplos de modelos.

Tipo: mapa

Obrigatório: não

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

Name

Um nome para o recurso RestAPI do API Gateway

Tipo: string

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é passada diretamente para a propriedade Name de um recurso AWS::ApiGateway::RestApi.

OpenApiVersion

Versão do OpenAPI a ser usada. Isso pode ser 2.0 para a especificação Swagger ou uma das versões do OpenAPI 3.0, como 3.0.1. Para obter mais informações sobre a OpenAPI, consulte a Especificação da OpenAPI.

nota

O AWS SAM cria um estágio chamado Stage por padrão. Definir essa propriedade com qualquer valor válido impedirá a criação do estágio Stage.

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::Api 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.

Policy

Um documento de política que contenha as permissões para a API. Para definir o ARN da política, use a função intrínseca !Join com "" como delimitador e valores de "execute-api:/" e "*".

Type: JSON

Obrigatório: não

Compatibilidade do CloudFormation: essa propriedade é passada diretamente para a propriedade Policy de um recurso do AWS::ApiGateway::RestApi.

StageName

O nome do estágio, que o API Gateway usa como o primeiro segmento de caminho no URI (Uniform Resource Identifier) invocado.

Para referenciar o recurso do estágio, use <api-logical-id>.Stage. Para obter mais informações sobre como referenciar recursos gerados quando um recurso AWS::Serverless::Api é especificado, consulte CloudFormationrecursos gerados quando AWS::Serverless::Api é especificado. Para obter informações gerais sobre recursos gerados do CloudFormation, consulte Recursos gerados do CloudFormation para o AWS SAM.

Tipo: string

Obrigatório: Sim

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade StageName de um recurso AWS::ApiGateway::Stage. É obrigatório no SAM, mas não no API Gateway

Outras observações: A API implícita tem o nome de estágio de “Prod”.

Tags

Um mapa (string para string) que especifica as tags a serem adicionadas a esse estágio do API Gateway. Para obter detalhes sobre chaves e valores válidos para tags, consulte Etiqueta de recurso no AWS CloudFormationGuia do usuário.

Tipo: mapa

Obrigatório: não

Compatibilidade CloudFormation: essa propriedade é semelhante à propriedade Tags de um recurso AWS::ApiGateway::Stage. A propriedade Tags no SAM consiste em pares Key:Value; no CloudFormation consiste em uma lista de objetos Tag.

TracingEnabled

Indica se o rastreamento ativo com o X-Ray está habilitado para esse estágio. Para obter mais informações sobre o X-Ray, consulte Rastreamento de solicitações de usuários para APIs REST usando o X-Ray no Guia do desenvolvedor do API Gateway.

Tipo: booliano

Obrigatório: não

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

Variables

Um mapa (string para string) que define as variáveis de estágio, onde o nome da variável é a chave e o valor da variável é o valor. Os nomes de variáveis são limitadas a caracteres alfanuméricos. Os valores devem corresponder a expressão regular a seguir: [A-Za-z0-9._~:/?#&=,-]+.

Tipo: mapa

Obrigatório: não

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

Valores de retorno

Ref.

Quando o ID lógico desse recurso é fornecido para a Ref função intrínseca, retorna o ID da API API Gateway subjacente.

Para obter mais informações sobre como usar a função Ref, consulte Ref no Guia do usuário do AWS CloudFormation.

Fn::GetAtt

Fn::GetAtt retorna um valor para um atributo especificado deste tipo. Estes são os atributos disponíveis e os valores de retorno de amostra.

Para obter mais informações sobre o uso do Fn::GetAtt, consulte Fn::GetAtt o AWS CloudFormation Guia do usuário.

RootResourceId

O ID de um recurso raiz RestApi, como a0bc123d4e.

Exemplos

SimpleApiExample

Um arquivo de modelo AWS SAM Hello World que contém uma função do Lambda com um endpoint de API. Esse é um arquivo de modelo AWS SAM completo para um aplicativo com tecnologia sem servidor em funcionamento.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

ApiCorsExample

Um trecho de modelo AWS SAM com uma API definida em um arquivo Swagger externo junto com integrações Lambda e configurações CORS. Essa é apenas uma parte de um arquivo de modelo AWS SAM que mostra uma definição AWS::Serverless::Api.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      # Allows www.example.com to call these APIs
      # SAM will automatically add AllowMethods with a list of methods for this API
      Cors: "'www.example.com'"
      DefinitionBody: # Pull in an OpenApi definition from S3
        'Fn::Transform':
          Name: 'AWS::Include'
          # Replace "bucket" with your bucket name
          Parameters:
            Location: s3://bucket/swagger.yaml

ApiCognitoAuthExample

Um trecho de modelo AWS SAM com uma API que usa o Amazon Cognito para autorizar solicitações contra a API. Essa é apenas uma parte de um arquivo de modelo AWS SAM que mostra uma definição AWS::Serverless::Api.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Cors: "'*'"
      Auth:
        DefaultAuthorizer: MyCognitoAuthorizer
        Authorizers:
          MyCognitoAuthorizer:
            UserPoolArn:
              Fn::GetAtt: [MyCognitoUserPool, Arn]

ApiModelsExample

Um trecho de modelo AWS SAM com uma API que inclui um esquema de modelos. Esta é apenas uma AWS SAM parte de um arquivo de modelo, mostrando uma AWS::Serverless::Api definição com dois esquemas de modelo.

YAML

Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      Models:
        User:
          type: object
          required:
            - username
            - employee_id
          properties:
            username:
              type: string
            employee_id:
              type: integer
            department:
              type: string
        Item:
          type: object
          properties:
            count:
              type: integer
            category:
              type: string
            price:
              type: integer

Exemplo de armazenamento em cache

Um arquivo de modelo AWS SAM Hello World que contém uma função do Lambda com um endpoint de API. A API tem o armazenamento em cache ativado para um recurso e método. Para obter mais informações sobre armazenamento em cache, consulte Habilitar o armazenamento em cache de APIs para melhorar a capacidade de resposta no Guia do desenvolvedor do API Gateway.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template with a simple API definition with caching turned on
Resources:
  ApiGatewayApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      CacheClusterEnabled: true
      CacheClusterSize: '0.5'
      MethodSettings:
        - ResourcePath: /
          HttpMethod: GET
          CachingEnabled: true
          CacheTtlInSeconds: 300
      Tags:
        CacheMethods: All 

  ApiFunction: # Adds a GET method at the root resource via an Api event
    Type: AWS::Serverless::Function
    Properties:
      Events:
        ApiEvent:
          Type: Api
          Properties:
            Path: /
            Method: get
            RestApiId:
              Ref: ApiGatewayApi
      Runtime: python3.10
      Handler: index.handler
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}

Domínio personalizado com um exemplo de API privada

Um arquivo de modelo AWS SAM Hello World que contenha uma função do Lambda com um endpoint de API mapeado para um domínio privado. O modelo cria uma associação de acesso a domínio entre um endpoint da VPC e o domínio privado. Para ter mais informações, consulte Nomes de domínio personalizados para APIs privadas no API Gateway.

YAML

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: AWS SAM template configured with a custom domain using a private API

Parameters:
    DomainName:
      Type: String
      Default: mydomain.example.com
    CertificateArn:
      Type: String
    HostedZoneId:
      Type: String
    VpcEndpointId:
      Type: String
    VpcEndpointDomainName:
      Type: String
    VpcEndpointHostedZoneId:
      Type: String

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      InlineCode: |
        def handler(event, context):
            return {'body': 'Hello World!', 'statusCode': 200}
      Handler: index.handler
      Runtime: python3.13
      Events:
        Fetch:
          Type: Api
          Properties:
            RestApiId:
              Ref: MyApi
            Method: Get
            Path: /get
  MyApi:
    Type: AWS::Serverless::Api
    Properties:
      StageName: Prod
      EndpointConfiguration:
        Type: PRIVATE
        VPCEndpointIds:
        - !Ref VpcEndpointId
      Policy:
        Version: '2012-10-17		 	 	 '
        Statement:
        - Effect: Allow
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
        - Effect: Deny
          Principal: '*'
          Action: execute-api:Invoke
          Resource: execute-api:/*
          Condition:
            StringNotEquals:
              aws:SourceVpce: !Ref VpcEndpointId
      Domain:
        DomainName: !Ref DomainName
        CertificateArn: !Ref CertificateArn
        EndpointConfiguration: PRIVATE
        BasePath:
        - /
        Route53:
          HostedZoneId: !Ref HostedZoneId
          VpcEndpointDomainName: !Ref VpcEndpointDomainName
          VpcEndpointHostedZoneId: !Ref VpcEndpointHostedZoneId
        AccessAssociation:
          VpcEndpointId: !Ref VpcEndpointId
        Policy:
          Version: '2012-10-17		 	 	 '
          Statement:
          - Effect: Allow
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
          - Effect: Deny
            Principal: '*'
            Action: execute-api:Invoke
            Resource: execute-api:/*
            Condition:
              StringNotEquals:
                aws:SourceVpce: !Ref VpcEndpointId