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](#sam-resource-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](sam-resource-function.md) definidos no modelo que não se referem a um recurso [AWS::Serverless::Api](#sam-resource-api).
Um [AWS::Serverless::Api](#sam-resource-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 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::Api
Properties:
[AccessLogSetting](#sam-api-accesslogsetting): {{[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)}}
AlwaysDeploy: {{Boolean}}
[ApiKeySourceType](#sam-api-apikeysourcetype): {{String}}
[Auth](#sam-api-auth): {{ApiAuth}}
[BinaryMediaTypes](#sam-api-binarymediatypes): {{List}}
[CacheClusterEnabled](#sam-api-cacheclusterenabled): {{Boolean}}
[CacheClusterSize](#sam-api-cacheclustersize): {{String}}
[CanarySetting](#sam-api-canarysetting): {{[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)}}
[Cors](#sam-api-cors): {{String | CorsConfiguration}}
[DefinitionBody](#sam-api-definitionbody): {{JSON}}
[DefinitionUri](#sam-api-definitionuri): {{String | ApiDefinition}}
[Description](#sam-api-description): {{String}}
[DisableExecuteApiEndpoint](#sam-api-disableexecuteapiendpoint): {{Boolean}}
[Domain](#sam-api-domain): {{DomainConfiguration}}
[EndpointAccessMode](#sam-api-endpointaccessmode): {{String}}
[EndpointConfiguration](#sam-api-endpointconfiguration): {{EndpointConfiguration}}
[FailOnWarnings](#sam-api-failonwarnings): {{Boolean}}
[GatewayResponses](#sam-api-gatewayresponses): {{Map}}
MergeDefinitions: {{Boolean}}
[MethodSettings](#sam-api-methodsettings): {{MethodSettings}}
[MinimumCompressionSize](#sam-api-minimumcompressionsize): {{Integer}}
[Mode](#sam-api-mode): {{String}}
[Models](#sam-api-models): {{Map}}
[Name](#sam-api-name): {{String}}
[OpenApiVersion](#sam-api-openapiversion): {{String}}
PropagateTags: {{Boolean}}
[Policy](#sam-api-policy): {{JSON}}
[SecurityPolicy](#sam-api-securitypolicy): {{String}}
[StageName](#sam-api-stagename): {{String}}
[Tags](#sam-api-tags): {{Map}}
[TracingEnabled](#sam-api-tracingenabled): {{Boolean}}
[Variables](#sam-api-variables): {{Map}}
```
## Propriedades
`AccessLogSetting`
Configura a configuração do log de acesso para um estágio.
*Digite*: [AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-accesslogsetting)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[AccessLogSetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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
*CloudFormation compatibilidade*: essa propriedade é exclusiva 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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[ApiKeySourceType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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 consulte[Controle o acesso à API com seu AWS SAM modelo](serverless-controlling-access-to-apis.md). Para ver um exemplo de como substituir um autorizador global, consulte [Substitua um autorizador global para sua API REST do Amazon API Gateway](sam-property-function-apifunctionauth.md#sam-property-function-apifunctionauth--examples--override).
*Digite*: [ApiAuth](sam-property-api-apiauth.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva 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 paraAPIs.
*Tipo*: lista
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[BinaryMediaTypes](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-binarymediatypes)` propriedade de um `AWS::ApiGateway::RestApi` recurso. A lista de BinaryMediaTypes é adicionada ao 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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[CacheClusterEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-cacheclusterenabled)` propriedade de um `AWS::ApiGateway::Stage` recurso.
`CacheClusterSize`
O tamanho do cluster de cache da etapa.
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[CacheClusterSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-canarysetting)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[CanarySetting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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.
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](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors.html) no *Guia do desenvolvedor do API Gateway*.
*Tipo*: String \| [CorsConfiguration](sam-property-api-corsconfiguration.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva 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 AWS SAM carrega arquivos locais](deploy-upload-local-files.md).
*Type*: JSON
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[Body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/create-reusable-transform-function-snippets-and-add-to-your-template-with-aws-include-transform.html) para importar uma OpenApi definição para o modelo.
*Tipo*: String \| [ApiDefinition](sam-property-api-apidefinition.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[BodyS3Location](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[Description](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[ DisableExecuteApiEndpoint](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-disableexecuteapiendpoint)` propriedade de um `AWS::ApiGateway::RestApi` 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-apigateway-restapi.html#cfn-apigateway-restapi-body)` de um recurso `AWS::ApiGateway::RestApi`.
`Domain`
Configura um domínio personalizado para essa API do API Gateway.
*Digite*: [DomainConfiguration](sam-property-api-domainconfiguration.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`EndpointConfiguration`
O tipo de endpoint de uma API REST.
*Digite*: [EndpointConfiguration](sam-property-api-endpointconfiguration.md)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[EndpointConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointconfiguration)` propriedade de um `AWS::ApiGateway::RestApi` recurso. As propriedades aninhadas de configuração têm nomes diferentes.
`EndpointAccessMode`
O modo de acesso para o endpoint da API REST. Obrigatório ao usar políticas de segurança aprimoradas (aquelas prefixadas com`SecurityPolicy_`).
*Valores válidos*: `STRICT` ou `BASIC`
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[EndpointAccessMode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-endpointaccessmode)` propriedade de um `AWS::ApiGateway::RestApi` recurso.
`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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[FailOnWarnings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-gateway-responses.html).
*Tipo*: mapa
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem 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
*CloudFormation compatibilidade*: essa propriedade é exclusiva 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-apigateway-stage-methodsetting.html)
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[MethodSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[MinimumCompressionSize](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-mode) do tipo de recurso [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html).
*Valores válidos*: `overwrite` ou `merge`
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[Mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.
`Name`
Um nome para o RestApi recurso API Gateway
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-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.](https://swagger.io/specification/)
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
*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::Api](sam-specification-generated-resources-api.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.
`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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a propriedade [Policy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-policy) de um `AWS::ApiGateway::RestApi` recurso.
`SecurityPolicy`
A versão TLS mais o pacote de criptografia para a API REST. Ao usar políticas de segurança aprimoradas (aquelas prefixadas com`SecurityPolicy>`), você também deve definir o. `EndpointAccessMode`
*Tipo:* string
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[SecurityPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-securitypolicy)` propriedade 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 `{{}}.Stage`. Para obter mais informações sobre como referenciar recursos gerados quando um recurso [AWS::Serverless::Api](#sam-resource-api) é especificado, consulte [CloudFormation recursos gerados quando AWS::Serverless::Api é especificado](sam-specification-generated-resources-api.md). Para obter informações gerais sobre CloudFormation os recursos gerados, consulte[CloudFormation Recursos gerados para AWS SAM](sam-specification-generated-resources.md).
*Tipo:* string
*Obrigatório*: Sim
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[StageName](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-resource-tags.html) no *AWS CloudFormation Guia do usuário*.
*Tipo*: mapa
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é semelhante à `[Tags](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-xray.html) no *Guia do desenvolvedor do API Gateway*.
*Tipo*: booliano
*Obrigatório*: não
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[TracingEnabled](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[Variables](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-stage.html#cfn-apigateway-stage-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 [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 *.
### 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 [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html) 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. Esse é 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](#sam-resource-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](#sam-resource-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](#sam-resource-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 ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html) 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 a domínio entre um endpoint da VPC e o domínio privado. Para obter mais informações, consulte [Nomes de domínio personalizados para uso privado APIs no API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-custom-domains.html).
#### 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
```