本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在後端服務使用 `@connections` 命令
<a name="apigateway-how-to-call-websocket-api-connections"></a>

後端服務可以使用以下 WebSocket 連線 HTTP 請求，來將回呼訊息傳送到連線用戶端、取得連線資訊，或中斷用戶端。

**重要**  
這些請求使用 [IAM 授權](apigateway-websocket-control-access-iam.md)，所以您必須使用 [Signature 第 4 版 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) 來進行簽署。若要執行此作業，您可以使用 API Gateway 管理 API。如需詳細資訊，請參閱 [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html)。

在下列命令中，您需要將 取代`{api-id}`為實際的 API ID，該 ID 會顯示在 API Gateway 主控台中，或由 AWS CLI [createe-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) 命令傳回。使用此命令之前，您必須先建立連線。

若要將回呼訊息傳送給用戶端，請使用：

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

您可以使用 `[Postman](https://www.postman.com/)` 或呼叫 `[awscurl](https://github.com/okigan/awscurl)` 來測試此請求，如下範例所示：

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

您需要以 URL 編碼處理命令，如以下範例所示：

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

若要取得用戶端的最新連線狀態，請使用下列命令：

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

若要中斷用戶端連線，請使用下列命令：

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

您可以在整合時使用 `$context` 變數來動態建置回呼 URL。例如，如果您使用 Lambda 代理整合搭配 `Node.js` Lambda 函數，您可以如下所示建置 URL，並傳送訊息到連線用戶端：

```
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,
  };
};
```

如果您使用 WebSocket API 的自訂網域名稱，請從函數程式碼中移除 `stage` 變數。

傳送回呼訊息時，您的 Lambda 函數必須具有呼叫 API Gateway 管理 API 的權限。如果在建立連線前或用戶端中斷連線後張貼訊息，您可能會收到含有 `GoneException` 的錯誤訊息。