AWS::Serverless::WebSocketApi

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 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 no guia do usuário da 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 CloudFormation recursos. Para obter mais informações, consulte 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.

YAML

Type: AWS::Serverless::WebSocketApi
Properties:
  ApiKeySelectionExpression: String
  AccessLogSettings: AccessLogSettings
  Auth: WebSocketApiAuth
  DefaultRouteSettings: RouteSettings
  Description: String
  DisableExecuteApiEndpoint: Boolean
  DisableSchemaValidation: Boolean
  Domain: WebSocketApiDomainConfiguration
  IpAddressType: String
  Name: String
  PropagateTags: Boolean
  Routes: RouteConfiguration
  RouteSelectionExpression: String
  RouteSettings: RouteSettings
  StageName: String
  StageVariables: Json
  Tags: Map

Propriedades

ApiKeySelectionExpression

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 no Guia do desenvolvedor do API Gateway.

Tipo: string

Obrigatório: não

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

AccessLogSettings

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

Digite: AccessLogSettings

Obrigatório: não

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

Auth

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 no Guia do desenvolvedor do API Gateway.

Digite: WebSocketApiAuth

Obrigatório: não

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

DefaultRouteSettings

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

Obrigatório: não

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

Description

Uma descrição da WebSocket API.

Tipo: string

Obrigatório: não

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

DisableExecuteApiEndpoint

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 propriedade de um AWS::ApiGatewayV2::Api recurso.

DisableSchemaValidation

Evite validar modelos ao criar uma implantação.

Tipo: booliano

Obrigatório: não

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

Domain

Configura um domínio personalizado para essa WebSocket API.

nota

WebSocket APIs não oferecem suporte à autenticação TLS mútua (MTLS). Se você especificar MutualTlsAuthentication ouOwnershipVerificationCertificateArn, AWS SAM retornará um erro.

Digite: WebSocketApiDomainConfiguration

Obrigatório: não

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

IpAddressType

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 propriedade de um AWS::ApiGatewayV2::Api recurso.

Name

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 propriedade de um AWS::ApiGatewayV2::Api recurso.

PropagateTags

Setrue, 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

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

Obrigatório: Sim

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

RouteSelectionExpression

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 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 propriedade de um AWS::ApiGatewayV2::Api recurso.

RouteSettings

As configurações de rota para essa WebSocket API. Essas configurações substituem DefaultRouteSettings as rotas específicas.

Digite: RouteSettings

Obrigatório: não

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

StageName

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 propriedade de um AWS::ApiGatewayV2::Stage recurso.

StageVariables

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

Obrigatório: não

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

Tags

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

WebSocket API simples

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

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