Criar rotas para APIs de WebSocket no API Gateway

Na sua API WebSocket, mensagens JSON de entrada são direcionadas para integrações de backend com base nas rotas que você configurar. (Mensagens que não apresentam o formato JSON são direcionadas para a rota $default que você configurar).

Uma rota inclui uma chave de roteamento, que é o valor esperado quando uma expressão de seleção de rotas é avaliada. O routeSelectionExpression é um atributo definido em nível de API. Ele especifica uma propriedade JSON que deve estar presente na carga da mensagem. Para obter mais informações sobre expressões de seleção de rota, consulte Expressões de seleção de rota.

Por exemplo, se as suas mensagens JSON contiverem uma propriedade action e você desejar executar ações diferentes de acordo com essa propriedade, sua expressão de seleção de rotas poderá ser ${request.body.action}. A tabela de roteamento deve especificar qual ação executar ao corresponder o valor da propriedade action com os valores de chave de rotas personalizada que você definiu na tabela.

Há três rotas predefinidas que podem ser usadas: $connect, $disconnect e $default. Além disso, você pode criar rotas personalizadas.

Expressões de seleção de rota

Uma expressão de seleção de rota é avaliada quando o serviço está selecionando a rota para seguir para uma mensagem recebida. O serviço usa a rota cuja routeKey corresponde exatamente ao valor avaliado. Se não existir nenhuma correspondência e uma rota com a chave $default existir, essa rota será selecionada. Se nenhuma rota corresponder ao valor avaliado e não existir uma rota $default, o serviço retornará uma mensagem de erro. Para APIs com base em WebSocket, a expressão deve ser da forma $request.body.{path_to_body_element}.

Por exemplo, suponha que você está enviando a seguinte mensagem JSON:

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

Você pode selecionar o comportamento da API com base na propriedade action. Nesse caso, você pode definir a seguinte expressão de seleção de rotas:

$request.body.action

Neste exemplo, request.body refere-se à carga JSON da sua mensagem, e .action é uma expressão JSONPath. Você pode usar qualquer expressão de caminho JSON após request.body, mas lembre-se de que o resultado será transformado em string. Por exemplo, se a expressão JSONPath retorna uma matriz de dois elementos, que serão apresentadas como a string "[item1, item2]". Por esse motivo, é uma boa prática ter sua expressão avaliada como um valor e não uma matriz ou um objeto.

Você pode simplesmente usar um valor estático, ou utilizar várias variáveis. A tabela a seguir mostra exemplos e seus resultados avaliados em relação à carga anterior.

O resultado avaliado é usado para encontrar uma rota. Se houver uma rota com uma chave de rota correspondente, a rota será selecionada para processar a mensagem. Se nenhuma rota correspondente for encontrada, o API Gateway tentará encontrar a rota $default, se disponível. Se a rota $default não estiver definida, o API Gateway retornará um erro.

Configurar rotas para uma API WebSocket no API Gateway

Ao criar uma nova API WebSocket pela primeira vez, há três rotas predefinidas: $connect, $disconnect e $default. É possível criá-las ao utilizar o console, a API ou a AWS CLI. Se desejado, você pode criar rotas personalizadas. Para obter mais informações, consulte Visão geral das APIs de WebSocket no API Gateway.

Criar uma rota usando o console do API Gateway

Criar uma rota usando a AWS CLI

Para criar uma rota usando a AWS CLI, chame create-route, conforme mostrado no exemplo a seguir.

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

Exemplos de resultado:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

Especificar as configurações de solicitação de rota para $connect

Quando você configurar a rota $connect para a sua API, as configurações opcionais a seguir serão disponibilizadas para habilitar a autorização para sua API. Para obter mais informações, consulte A rota $connect.

Configurar a solicitação de rota $connect usando o console do API Gateway

Para configurar uma solicitação de rota $connect para uma API WebSocket usando o console do API Gateway: