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 AWS::Serverless::Api recurso não precisa ser adicionado explicitamente a um modelo de definição de aplicativo AWS sem servidor. 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 AWS::Serverless::Api recurso deve ser usado para definir e documentar o uso da API OpenApi, o que fornece mais capacidade de configurar os recursos subjacentes do Amazon API Gateway.

Recomendamos que você use AWS 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 AWS CloudFormation ganchos, consulte Registrando ganchos no guia do usuário da AWS CloudFormation CLI e no repositório. 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 no Guia do desenvolvedor do API Gateway.

nota

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

Sintaxe

Para declarar essa entidade em seu modelo AWS Serverless Application Model (AWS SAM), use a sintaxe a seguir.

Propriedades

AccessLogSetting

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

Digite: AccessLogSetting

Obrigatório: não

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

AlwaysDeploy

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

Tipo: booliano

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS 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

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

Auth

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

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

Digite: ApiAuth

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS CloudFormation equivalente.

BinaryMediaTypes

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

Tipo: lista

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é semelhante à BinaryMediaTypes propriedade de um AWS::ApiGateway::RestApi recurso. A lista de BinaryMediaTypes é adicionada ao AWS CloudFormation recurso 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

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

CacheClusterSize

O tamanho do cluster de cache da etapa.

Tipo: string

Obrigatório: não

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

CanarySetting

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

Digite: CanarySetting

Obrigatório: não

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

Cors

Gerencie o compartilhamento de recursos de origem cruzada (CORS) para todo o seu API Gateway. APIs 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 que AWS SAM você modifique sua 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

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS 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

AWS CloudFormation compatibilidade: essa propriedade é semelhante à Body propriedade de um AWS::ApiGateway::RestApi recurso. Se determinadas propriedades forem fornecidas, o conteúdo poderá ser inserido ou modificado no DefinitionBody antes de ser passado para 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 OpenApi arquivos externos referenciados por. DefinitionUri Em vez disso, use a DefinitionBody propriedade com a Transformação Include para importar uma OpenApi definição para o modelo.

Tipo: String | ApiDefinition

Obrigatório: não

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

Description

Uma descrição do recurso da API.

Tipo: string

Obrigatório: não

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

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

AWS CloudFormation compatibilidade: essa propriedade é semelhante à DisableExecuteApiEndpoint propriedade de um AWS::ApiGateway::RestApi recurso. 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.

Digite: DomainConfiguration

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS CloudFormation equivalente.

EndpointConfiguration

O tipo de endpoint de uma API REST.

Digite: EndpointConfiguration

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é semelhante à EndpointConfiguration propriedade de um AWS::ApiGateway::RestApi recurso. 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

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

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 OpenApi extensão Api Gateway para respostas do Gateway.

Tipo: mapa

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS CloudFormation equivalente.

MergeDefinitions

AWS SAM gera uma OpenAPI especificação da sua fonte de eventos de API. Especifique true para AWS SAM mesclar isso na OpenAPI especificação embutida definida em seu AWS::Serverless::Api recurso. 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

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS 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

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

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

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

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

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

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

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS CloudFormation equivalente.

Name

Um nome para o RestApi recurso API Gateway

Tipo: string

Obrigatório: não

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

OpenApiVersion

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

nota

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

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS 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

AWS CloudFormation compatibilidade: essa propriedade é exclusiva AWS SAM e não tem AWS CloudFormation equivalente.

Policy

Um documento de política que contém 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

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

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 AWS CloudFormation recursos gerados quando AWS::Serverless::Api é especificado. Para obter informações gerais sobre AWS CloudFormation os recursos gerados, consulteAWS CloudFormation Recursos gerados para AWS SAM.

Tipo: string

Obrigatório: Sim

AWS CloudFormation compatibilidade: essa propriedade é semelhante à StageName propriedade de um AWS::ApiGateway::Stage recurso. É 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 CloudFormation Guia do usuário.

Tipo: mapa

Obrigatório: não

AWS CloudFormation compatibilidade: essa propriedade é semelhante à Tags propriedade de um AWS::ApiGateway::Stage recurso. A propriedade Tags no SAM consiste em pares de chave-valor; CloudFormation nela 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 Rastreando solicitações do usuário para REST APIs usando o X-Ray no Guia do desenvolvedor do API Gateway.

Tipo: booliano

Obrigatório: não

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

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

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

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 .

Fã:: 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 AWS SAM modelo Hello World que contém uma função Lambda com um endpoint de API. Este é um arquivo AWS SAM de modelo completo para um aplicativo 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 AWS SAM de modelo com uma API definida em um arquivo Swagger externo junto com as integrações do Lambda e as configurações do CORS. Essa é apenas uma parte de um arquivo de AWS SAM modelo que mostra uma AWS::Serverless::Api definição.

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 AWS SAM de modelo com uma API que usa o Amazon Cognito para autorizar solicitações contra a API. Essa é apenas uma parte de um arquivo de AWS SAM modelo que mostra uma AWS::Serverless::Api definição.

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 AWS SAM modelo com uma API que inclui um esquema de modelos. Essa é apenas uma parte de um arquivo de AWS SAM 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 AWS SAM modelo Hello World que contém uma função 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 AWS SAM modelo Hello World que contém uma função Lambda com um endpoint de API mapeado para um domínio privado. O modelo cria uma associação de acesso ao domínio entre um VPC endpoint e o domínio privado. Para obter mais informações, consulte Nomes de domínio personalizados para uso privado APIs 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