# Usar os comandos `@connections` em seu serviço de backend
<a name="apigateway-how-to-call-websocket-api-connections"></a>

Seu serviço de backend pode utilizar as solicitações HTTP de conexão WebSocket a seguir para enviar uma mensagem de retorno a um cliente conectado, obter informações de conexão ou desconectar o cliente.

**Importante**  
Essas solicitações utilizam a [autorização do IAM](apigateway-websocket-control-access-iam.md), portanto, você deve assiná-las com o [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Para fazer isso, você pode usar a API de Gerenciamento do API Gateway. Para obter mais informações, consulte [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html).

No comando a seguir, é necessário substituir `{api-id}` pelo ID de API real que é exibido no console do API Gateway ou retornado pelo comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) da AWS CLI. É necessário estabelecer conexão antes de usar esse comando. 

Para enviar uma mensagem de retorno ao cliente, utilize:

```
POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```

É possível testar essa solicitação usando `[Postman](https://www.postman.com/)` ou chamando `[awscurl](https://github.com/okigan/awscurl)` conforme o exemplo a seguir:

```
awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```

Você precisa codificar o URL no comando, conforme mostrado no exemplo a seguir:

```
awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D
```

Para obter o status de conexão mais recente do cliente, use:

```
GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```

Para desconectar o cliente, use:

```
DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```

Você pode criar dinamicamente uma URL de retorno de chamada ao utilizar as variáveis `$context` em sua integração. Por exemplo, se usar a integração de proxy do Lambda com uma função do Lambda `Node.js`, você poderá criar o URL e enviar uma mensagem para um cliente conectado da seguinte forma:

```
import {
  ApiGatewayManagementApiClient,
  PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";

export const handler = async (event) => {
  const domain = event.requestContext.domainName;
  const stage = event.requestContext.stage;
  const connectionId = event.requestContext.connectionId;
  const callbackUrl = `https://${domain}/${stage}`;
  const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });

  const requestParams = {
    ConnectionId: connectionId,
    Data: "Hello!",
  };

  const command = new PostToConnectionCommand(requestParams);

  try {
    await client.send(command);
  } catch (error) {
    console.log(error);
  }

  return {
    statusCode: 200,
  };
};
```

Se você usar um nome de domínio personalizado para sua API de WebSocket, remova a variável `stage` do código da função.

Ao enviar uma mensagem de retorno de chamada, a função do Lambda deve ter permissão para chamar a API de gerenciamento do API Gateway. Você poderá receber um erro contendo `GoneException` se publicar uma mensagem antes do estabelecimento da conexão ou após a desconexão do cliente.