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::WebSocketApi
<a name="sam-resource-websocketapi"></a>

Cria uma API do Amazon WebSocket API Gateway, que permite criar aplicativos de comunicação interativa bidirecional. WebSocket APIs permitem que o servidor envie mensagens aos clientes sem que o cliente precise solicitá-las. Para obter mais informações, consulte [Trabalhando com WebSocket APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-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
<a name="sam-resource-websocketapi-syntax"></a>

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

### YAML
<a name="sam-resource-websocketapi-syntax.yaml"></a>

```
Type: AWS::Serverless::WebSocketApi
Properties:
  [ApiKeySelectionExpression](#sam-websocketapi-apikeyselectionexpression): {{String}}
  [AccessLogSettings](#sam-websocketapi-accesslogsettings): {{[AccessLogSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-accesslogsettings)}}
  [Auth](#sam-websocketapi-auth): {{WebSocketApiAuth}}
  [DefaultRouteSettings](#sam-websocketapi-defaultroutesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}}
  [Description](#sam-websocketapi-description): {{String}}
  [DisableExecuteApiEndpoint](#sam-websocketapi-disableexecuteapiendpoint): {{Boolean}}
  [DisableSchemaValidation](#sam-websocketapi-disableschemavalidation): {{Boolean}}
  [Domain](#sam-websocketapi-domain): {{WebSocketApiDomainConfiguration}}
  [IpAddressType](#sam-websocketapi-ipaddresstype): {{String}}
  [Name](#sam-websocketapi-name): {{String}}
  [PropagateTags](#sam-websocketapi-propagatetags): {{Boolean}}
  [Routes](#sam-websocketapi-routes): {{RouteConfiguration}}
  [RouteSelectionExpression](#sam-websocketapi-routeselectionexpression): {{String}}
  [RouteSettings](#sam-websocketapi-routesettings): {{[RouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-routesettings)}}
  [StageName](#sam-websocketapi-stagename): {{String}}
  [StageVariables](#sam-websocketapi-stagevariables): {{[Json](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-stagevariables)}}
  [Tags](#sam-websocketapi-tags): {{Map}}
```

## Propriedades
<a name="sam-resource-websocketapi-properties"></a>

 `ApiKeySelectionExpression`   <a name="sam-websocketapi-apikeyselectionexpression"></a>
Uma expressão de seleção de chaves de API. Para obter mais informações, consulte [Expressões de seleção de chaves de API](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-apikey-selection-expressions) no *Guia do desenvolvedor do API Gateway*.  
*Tipo:* string  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[ApiKeySelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-apikeyselectionexpression)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `AccessLogSettings`   <a name="sam-websocketapi-accesslogsettings"></a>
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`   <a name="sam-websocketapi-auth"></a>
Configura a autorização para controlar o acesso à sua WebSocket API. A autorização é aplicada à `$connect` rota.  
Para obter mais informações, consulte Como [controlar o acesso ao WebSocket APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-control-access.html) no *Guia do desenvolvedor do API Gateway*.  
*Digite*: [WebSocketApiAuth](sam-property-websocketapi-websocketapiauth.md)  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.

 `DefaultRouteSettings`   <a name="sam-websocketapi-defaultroutesettings"></a>
As configurações de rota padrão para essa WebSocket API. 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 `[DefaultRouteSettings](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-stage.html#cfn-apigatewayv2-stage-defaultroutesettings)` propriedade de um `AWS::ApiGatewayV2::Stage` recurso.

 `Description`   <a name="sam-websocketapi-description"></a>
Uma descrição da WebSocket 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-apigatewayv2-api.html#cfn-apigatewayv2-api-description)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `DisableExecuteApiEndpoint`   <a name="sam-websocketapi-disableexecuteapiendpoint"></a>
Especifica se os clientes podem invocar sua API usando o endpoint `execute-api` padrão. Para exigir que os clientes usem um nome de domínio personalizado para invocar sua API, desabilite o endpoint padrão.  
*Tipo*: booliano  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[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.

 `DisableSchemaValidation`   <a name="sam-websocketapi-disableschemavalidation"></a>
Evite validar modelos ao criar uma implantação.  
*Tipo*: booliano  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[DisableSchemaValidation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-disableschemavalidation)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `Domain`   <a name="sam-websocketapi-domain"></a>
Configura um domínio personalizado para essa WebSocket API.  
WebSocket APIs não oferecem suporte à autenticação TLS mútua (MTLS). Se você especificar `MutualTlsAuthentication` ou`OwnershipVerificationCertificateArn`, AWS SAM retornará um erro.
*Digite*: [WebSocketApiDomainConfiguration](sam-property-websocketapi-websocketapidomainconfiguration.md)  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.

 `IpAddressType`   <a name="sam-websocketapi-ipaddresstype"></a>
O tipo de endereço IP da API. Os valores válidos são IPv4 somente `ipv4` `dualstack` para IPv4 e para IPv6 e.  
*Tipo:* string  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[IpAddressType](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-ipaddresstype)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `Name`   <a name="sam-websocketapi-name"></a>
Um nome para a WebSocket API. Se você não especificar um nome, AWS SAM gera um nome para você.  
*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-apigatewayv2-api.html#cfn-apigatewayv2-api-name)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `PropagateTags`   <a name="sam-websocketapi-propagatetags"></a>
Se`true`, AWS SAM adiciona a `Tags` propriedade aos `AWS::ApiGatewayV2::DomainName` recursos `AWS::ApiGatewayV2::Stage` e AWS SAM gerados.  
*Tipo*: booliano  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.

 `Routes`   <a name="sam-websocketapi-routes"></a>
As configurações de rota para essa WebSocket API. As rotas definem como as mensagens são roteadas para as funções Lambda. Cada rota consiste em uma chave de rota e um ARN da função Lambda.  
WebSocket APIs suportam três rotas predefinidas: `$connect``$disconnect`, e. `$default` Você também pode definir rotas personalizadas.  
*Digite*: [RouteConfiguration](sam-property-websocketapi-routeconfiguration.md)  
*Obrigatório*: Sim  
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.

 `RouteSelectionExpression`   <a name="sam-websocketapi-routeselectionexpression"></a>
A expressão de seleção de rotas para a WebSocket API. Para obter mais informações, consulte [Expressões de seleção de rotas](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html#apigateway-websocket-api-route-selection-expressions) no *Guia do desenvolvedor do API Gateway*.  
Um valor comum é`$request.body.action`, que roteia mensagens com base em um `action` campo no corpo da mensagem.  
*Tipo:* string  
*Obrigatório*: Sim  
*CloudFormation compatibilidade*: essa propriedade é passada diretamente para a `[RouteSelectionExpression](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html#cfn-apigatewayv2-api-routeselectionexpression)` propriedade de um `AWS::ApiGatewayV2::Api` recurso.

 `RouteSettings`   <a name="sam-websocketapi-routesettings"></a>
As configurações de rota para essa WebSocket API. Essas configurações substituem `DefaultRouteSettings` as rotas específicas.  
*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`   <a name="sam-websocketapi-stagename"></a>
O nome do estágio da API. Se você não especificar um nome, AWS SAM use `default` como nome artístico.  
*Tipo:* string  
*Obrigatório*: não  
*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`   <a name="sam-websocketapi-stagevariables"></a>
Um mapa que define as variáveis da etapa. Os nomes das variáveis podem ter caracteres alfanuméricos e sublinhados, e os valores devem corresponder`[A-Za-z0-9-._~:/?#&=,]+`.  
*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`   <a name="sam-websocketapi-tags"></a>
Um mapa (string a string) que especifica as tags a serem adicionadas a essa WebSocket API. 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 *CloudFormation Guia do usuário*.  
*Tipo*: mapa  
*Obrigatório*: não  
*CloudFormation compatibilidade*: essa propriedade é exclusiva AWS SAM e não tem CloudFormation equivalente.

## Exemplos
<a name="sam-resource-websocketapi-examples"></a>

### WebSocket API simples
<a name="sam-resource-websocketapi-examples-simple"></a>

O exemplo a seguir cria uma WebSocket API com três rotas.

```
Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        $disconnect:
          FunctionArn: !GetAtt DisconnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  DisconnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.disconnect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src
```

### WebSocket API com Lambda Authorizer
<a name="sam-resource-websocketapi-examples-auth"></a>

O exemplo a seguir cria uma WebSocket API com um autorizador Lambda.

```
Resources:
  MyWebSocketApi:
    Type: AWS::Serverless::WebSocketApi
    Properties:
      RouteSelectionExpression: $request.body.action
      Auth:
        AuthType: CUSTOM
        AuthArn: !GetAtt AuthorizerFunction.Arn
        IdentitySource:
          - route.request.header.Authorization
      Routes:
        $connect:
          FunctionArn: !GetAtt ConnectFunction.Arn
        sendMessage:
          FunctionArn: !GetAtt SendMessageFunction.Arn

  AuthorizerFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.authorize
      Runtime: nodejs20.x
      CodeUri: ./src

  ConnectFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.connect
      Runtime: nodejs20.x
      CodeUri: ./src

  SendMessageFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.sendMessage
      Runtime: nodejs20.x
      CodeUri: ./src
```