AWS::Serverless::WebSocketApi

Crea un'API Amazon WebSocket API Gateway, che consente di creare applicazioni di comunicazione interattive bidirezionali. WebSocket APIs consente al server di inviare messaggi ai client senza che il client debba richiederli. Per ulteriori informazioni, consulta Working with WebSocket APIs nella API Gateway Developer Guide.

Ti consigliamo di utilizzare CloudFormation hook o policy IAM per verificare che alle risorse API Gateway siano associate autorizzazioni per controllarne l'accesso.

Per ulteriori informazioni sull'uso degli CloudFormation hook, consulta Registrazione degli hook nella guida per l'utente della CloudFormation CLI e nel repository. apigw-enforce-authorizer GitHub

Per ulteriori informazioni sull'utilizzo delle policy IAM, consulta Require che le route API abbiano l'autorizzazione nella API Gateway Developer Guide.

Nota

Quando esegui la distribuzione a AWS CloudFormation, AWS SAM trasforma le tue AWS SAM risorse in CloudFormation risorse. Per ulteriori informazioni, consulta CloudFormation Risorse generate per AWS SAM.

Sintassi

Per dichiarare questa entità nel tuo modello AWS Serverless Application Model (AWS SAM), usa la seguente sintassi.

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

Properties

ApiKeySelectionExpression

Un'espressione di selezione della chiave API. Per ulteriori informazioni, consulta API Key Selection Expressions nella API Gateway Developer Guide.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla ApiKeySelectionExpression proprietà di una AWS::ApiGatewayV2::Api risorsa.

AccessLogSettings

Le impostazioni per la registrazione degli accessi in una fase.

Tipo: AccessLogSettings

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla AccessLogSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

Auth

Configura l'autorizzazione per il controllo dell'accesso alla tua WebSocket API. L'autorizzazione viene applicata al $connect percorso.

Per ulteriori informazioni, consulta Controlling access to WebSocket APIs nella API Gateway Developer Guide.

Tipo: WebSocketApiAuth

Obbligatorio: no

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

DefaultRouteSettings

Le impostazioni di routing predefinite per questa WebSocket API. Queste impostazioni si applicano a tutti i percorsi a meno che non vengano sovrascritte dalla RouteSettings proprietà per determinati percorsi.

Tipo: RouteSettings

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla DefaultRouteSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

Description

Una descrizione dell' WebSocket API.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Description proprietà di una AWS::ApiGatewayV2::Api risorsa.

DisableExecuteApiEndpoint

Specifica se i client possono richiamare l'API utilizzando l'endpoint execute-api predefinito. Per richiedere che i client utilizzino un nome di dominio personalizzato per richiamare l'API, disabilitare l'endpoint predefinito.

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla DisableExecuteApiEndpoint proprietà di una AWS::ApiGatewayV2::Api risorsa.

DisableSchemaValidation

Esclude la convalida dei modelli durante la creazione di una distribuzione.

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla DisableSchemaValidation proprietà di una AWS::ApiGatewayV2::Api risorsa.

Domain

Configura un dominio personalizzato per questa WebSocket API.

Nota

WebSocket APIs non supportano l'autenticazione TLS reciproca (MTLS). Se si specifica MutualTlsAuthentication oOwnershipVerificationCertificateArn, AWS SAM verrà restituito un errore.

Tipo: WebSocketApiDomainConfiguration

Obbligatorio: no

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

IpAddressType

Il tipo di indirizzo IP per l'API. I valori validi sono IPv4 solo ipv4 dualstack per IPv4 e IPv6.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla IpAddressType proprietà di una AWS::ApiGatewayV2::Api risorsa.

Name

Un nome per l' WebSocket API. Se non specifichi un nome, AWS SAM genera un nome per te.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla Name proprietà di una AWS::ApiGatewayV2::Api risorsa.

PropagateTags

Iftrue, AWS SAM aggiunge la Tags proprietà alle AWS::ApiGatewayV2::DomainName risorse AWS::ApiGatewayV2::Stage e alle risorse che AWS SAM genera.

Tipo: Booleano

Obbligatorio: no

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

Routes

Le configurazioni delle rotte per questa WebSocket API. Le route definiscono il modo in cui i messaggi vengono instradati alle funzioni Lambda. Ogni percorso è composto da una chiave di percorso e da una funzione Lambda ARN.

WebSocket APIs supporta tre percorsi predefiniti:$connect,, e$disconnect. $default Puoi anche definire percorsi personalizzati.

Tipo: RouteConfiguration

Obbligatorio: sì

CloudFormation compatibilità: Questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

RouteSelectionExpression

L'espressione di selezione del percorso per l' WebSocket API. Per ulteriori informazioni, consulta Route Selection Expressions nella Guida per sviluppatori di API Gateway.

Un valore comune è$request.body.action, che indirizza i messaggi in base a un action campo nel corpo del messaggio.

▬Tipo: stringa

Obbligatorio: sì

CloudFormation compatibilità: questa proprietà viene passata direttamente alla RouteSelectionExpression proprietà di una AWS::ApiGatewayV2::Api risorsa.

RouteSettings

Le impostazioni del percorso per questa WebSocket API. Queste impostazioni hanno la precedenza su quelle DefaultRouteSettings relative a percorsi specifici.

Tipo: RouteSettings

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla RouteSettings proprietà di una AWS::ApiGatewayV2::Stage risorsa.

StageName

Il nome della fase API. Se non specificate un nome, AWS SAM lo usa default come nome dello stage.

▬Tipo: stringa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla StageName proprietà di una AWS::ApiGatewayV2::Stage risorsa.

StageVariables

Mappa che definisce le variabili delle fasi. I nomi delle variabili possono contenere caratteri alfanumerici e caratteri di sottolineatura e i valori devono corrispondere. [A-Za-z0-9-._~:/?#&=,]+

Type: Json

Obbligatorio: no

CloudFormation compatibilità: questa proprietà viene passata direttamente alla StageVariables proprietà di una risorsa. AWS::ApiGatewayV2::Stage

Tags

Una mappa (da stringa a stringa) che specifica i tag da aggiungere a questa WebSocket API. Per informazioni dettagliate sulle chiavi e i valori validi per i tag, consulta Resource tag nella Guida per l'CloudFormation utente.

Tipo: Mappa

Obbligatorio: no

CloudFormation compatibilità: questa proprietà è unica AWS SAM e non ha un CloudFormation equivalente.

Esempi

WebSocket API semplice

L'esempio seguente crea un' WebSocket API con tre percorsi.

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

L'esempio seguente crea un' WebSocket API con un autorizzatore 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