View a markdown version of this page

AWS::Serverless::WebSocketApi - AWS Serverless Application Model
SintaxisPropiedadesvalores devueltosEjemplos

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

AWS::Serverless::WebSocketApi

Crea una API de Amazon WebSocket API Gateway, que le permite crear aplicaciones de comunicación interactiva bidireccional. WebSocket Las API permiten al servidor enviar mensajes a los clientes sin que el cliente tenga que solicitarlos. Para obtener más información, consulte Trabajar con WebSocket las API en la Guía para desarrolladores de API Gateway.

Te recomendamos que utilices CloudFormation enlaces o políticas de IAM para comprobar que los recursos de API Gateway tienen autorizadores adjuntos para controlar el acceso a ellos.

Para obtener más información sobre el uso de CloudFormation ganchos, consulte Registrar ganchos en la guía del usuario de la CloudFormation CLI y en el repositorio GitHub apigw-enforce-authorizer.

Para obtener más información sobre el uso de las políticas de IAM, consulta Exigir que las rutas de API tengan autorización en la Guía para desarrolladores de API Gateway.

nota

Cuando despliegas en, transforma tus recursos en AWS CloudFormation recursos AWS SAM . AWS SAM CloudFormation Para obtener más información, consulte Generado CloudFormation recursos para AWS SAM.

Sintaxis

Para declarar esta entidad en tu plantilla AWS Serverless Application Model (AWS SAM), usa la siguiente sintaxis.

Propiedades

ApiKeySelectionExpression

Es una expresión de selección de clave de API. Para obtener más información, consulte Expresiones de selección de claves de API en la Guía para desarrolladores de API Gateway.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se transfiere directamente a la ApiKeySelectionExpression propiedad de un AWS::ApiGatewayV2::Api recurso.

AccessLogSettings

Configuración del registro de acceso en una etapa.

Tipo: AccessLogSettings

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la AccessLogSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

Auth

Configura la autorización para controlar el acceso a tu WebSocket API. La autorización se aplica a la $connect ruta.

Para obtener más información, consulte Control del acceso a WebSocket las API en la Guía para desarrolladores de API Gateway.

Tipo: WebSocketApiAuth

Obligatorio: no

CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

DefaultRouteSettings

La configuración de ruta predeterminada para esta WebSocket API. Esta configuración se aplica a todas las rutas, a menos que la propiedad RouteSettings la anula para determinadas rutas.

Tipo: RouteSettings

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la DefaultRouteSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

Description

Una descripción de la WebSocket API.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la Description propiedad de un AWS::ApiGatewayV2::Api recurso.

DisableExecuteApiEndpoint

Especifica si los clientes pueden invocar la API mediante el punto de conexión execute-api predeterminado. Para exigir que los clientes utilicen un nombre de dominio personalizado para invocar la API, desactive el punto de enlace predeterminado.

Tipo: Booleano

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la DisableExecuteApiEndpoint propiedad de un AWS::ApiGatewayV2::Api recurso.

DisableSchemaValidation

Evite validar modelos al crear una implementación.

Tipo: Booleano

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la DisableSchemaValidation propiedad de un AWS::ApiGatewayV2::Api recurso.

Domain

Configura un dominio personalizado para esta WebSocket API.

nota

WebSocket Las API no admiten la autenticación TLS mutua (MTLS). Si lo especifica MutualTlsAuthentication oOwnershipVerificationCertificateArn, AWS SAM devolverá un error.

Tipo: WebSocketApiDomainConfiguration

Obligatorio: no

CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

IpAddressType

El tipo de dirección IP de la API. Los valores válidos son solo ipv4 para IPv4 y dualstack para IPv4 e IPv6.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se transfiere directamente a la IpAddressType propiedad de un recurso. AWS::ApiGatewayV2::Api

Name

Un nombre para la WebSocket API. Si no especificas un nombre, AWS SAM generará uno para ti.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la Name propiedad de un AWS::ApiGatewayV2::Api recurso.

PropagateTags

Sitrue, AWS SAM agrega la Tags propiedad a los AWS::ApiGatewayV2::DomainName recursos AWS::ApiGatewayV2::Stage y que AWS SAM genera.

Tipo: Booleano

Obligatorio: no

CloudFormation compatibilidad: esta propiedad es exclusiva AWS SAM y no tiene un CloudFormation equivalente.

Routes

Las configuraciones de ruta para esta WebSocket API. Las rutas definen cómo se enrutan los mensajes a las funciones Lambda. Cada ruta consta de una clave de ruta y un ARN de función Lambda.

WebSocket Las API admiten tres rutas predefinidas: $connect$disconnect, y. $default También puede definir rutas personalizadas.

Tipo: RouteConfiguration

Obligatorio: sí

CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

RouteSelectionExpression

La expresión de selección de rutas de la WebSocket API. Para obtener más información, consulte Expresiones de selección de rutas en la Guía para desarrolladores de API Gateway.

Un valor común es $request.body.action que enruta los mensajes en función de un action campo del cuerpo del mensaje.

Tipo: cadena

Obligatorio: sí

CloudFormation compatibilidad: esta propiedad se transfiere directamente a la RouteSelectionExpression propiedad de un AWS::ApiGatewayV2::Api recurso.

RouteSettings

La configuración de ruta de esta WebSocket API. Esta configuración anula la DefaultRouteSettings de rutas específicas.

Tipo: RouteSettings

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la RouteSettings propiedad de un AWS::ApiGatewayV2::Stage recurso.

StageName

Es el nombre de la fase de la API. Si no especificas un nombre, se AWS SAM usa default como nombre artístico.

Tipo: cadena

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se pasa directamente a la StageName propiedad de un AWS::ApiGatewayV2::Stage recurso.

StageVariables

Una asignación que define las variables de la fase. Los nombres de las variables pueden tener caracteres alfanuméricos y de subrayado, y los valores deben coincidir. [A-Za-z0-9-._~:/?#&=,]+

Type: Json

Obligatorio: no

CloudFormation compatibilidad: esta propiedad se transfiere directamente a la StageVariables propiedad de un AWS::ApiGatewayV2::Stage recurso.

Tags

Un mapa (cadena a cadena) que especifica las etiquetas que se van a añadir a esta WebSocket API. Para obtener más información sobre las claves y los valores válidos de las etiquetas, consulta la etiqueta de recursos en la Guía del usuario de CloudFormation .

Tipo: mapa

Obligatorio: no

CloudFormation compatibilidad: esta propiedad es exclusiva de AWS SAM y no tiene un CloudFormation equivalente.

valores devueltos

Ref.

Cuando se pasa el ID lógico de este recurso a la función intrínseca Ref, Ref devuelve el ID de API del recurso subyacente AWS::ApiGatewayV2::Api, por ejemplo, a1bcdef2gh.

Para obtener más información sobre el uso de la función Ref, consulta Ref en la Guía del usuario de AWS CloudFormation .

Ejemplos

WebSocket API simple

El siguiente ejemplo crea una WebSocket API con tres rutas.

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 con Lambda Authorizer

En el siguiente ejemplo, se crea una WebSocket API con un 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