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

# 管理連線的使用者和用戶端應用程式：`$connect` 和 `$disconnect` 路由
<a name="apigateway-websocket-api-route-keys-connect-disconnect"></a>

下一節說明如何使用 WebSocket API 的 `$connect` 和 `$disconnect` 路由。

**Topics**
+ [`$connect` 路由](#apigateway-websocket-api-routes-about-connect)
+ [從 `$connect` 路由傳遞連線資訊](#apigateway-websocket-api-passing-connectionId-on-connect)
+ [`$disconnect` 路由](#apigateway-websocket-api-routes-about-disconnect)

## `$connect` 路由
<a name="apigateway-websocket-api-routes-about-connect"></a>

用戶端應用程式會透過傳送 WebSocket 升級請求來連線到 WebSocket API。如果請求成功，會在建立連線的同時執行 `$connect` 路由。

由於 WebSocket 連線是狀態連接，您可以僅對 `$connect` 路由設定授權。`AuthN`/`AuthZ` 將只會在連線時執行。

在與 `$connect` 路由關聯的整合執行完成後，升級請求會處於等待中，且將不會建立實際的連線。如果 `$connect` 請求失敗 (例如，由於 `AuthN`/`AuthZ` 故障或整合故障)，將不會進行連線。

**注意**  
如果在進行 `$connect` 時授權失敗，就不會建立連線，用戶端將會收到 `401` 或 `403` 回應。

為 `$connect` 設定整合是選用的。您應在以下情況考慮設定 `$connect` 整合：
+ 您想要讓用戶端使用 `Sec-WebSocket-Protocol` 欄位來指定子通訊協定。如需範例程式碼，請參閱[設定需要 WebSocket 子協定的 `$connect` 路由](websocket-connect-route-subprotocol.md)。
+ 您希望在用戶端連線時收到通知。
+ 您想要調節連線或控制連線的人員。
+ 您想要後端使用回呼 URL 將訊息傳回給用戶端。
+ 您想將每個連線 ID 和其他資訊放到資料庫 (例如，Amazon DynamoDB)。

## 從 `$connect` 路由傳遞連線資訊
<a name="apigateway-websocket-api-passing-connectionId-on-connect"></a>

 您可以同時使用代理和非代理整合，將資訊從 `$connect` 路由傳遞至資料庫或其他 AWS 服務。

### 使用代理整合傳遞連線資訊
<a name="websocket-connect-proxy-integration"></a>

您可以從事件中的 Lambda 代理整合存取連線資訊。使用另一個 AWS 服務 或 AWS Lambda 函數來發佈至連線。

下列 Lambda 函數顯示如何使用 `requestContext` 物件來記錄連線 ID、網域名稱、階段名稱和查詢字串。

------
#### [ Node.js ]

```
 export const handler = async(event, context) => {
    const connectId = event["requestContext"]["connectionId"]
    const domainName = event["requestContext"]["domainName"]
    const stageName = event["requestContext"]["stage"]
    const qs = event['queryStringParameters']
    console.log('Connection ID: ', connectId, 'Domain Name: ', domainName, 'Stage Name: ', stageName, 'Query Strings: ', qs )
    return {"statusCode" : 200}
};
```

------
#### [ Python ]

```
import json
import logging
logger = logging.getLogger()
logger.setLevel("INFO")


def lambda_handler(event, context):
    connectId = event["requestContext"]["connectionId"]
    domainName = event["requestContext"]["domainName"]
    stageName = event["requestContext"]["stage"]
    qs = event['queryStringParameters']
    connectionInfo = {
        'Connection ID': connectId,
        'Domain Name': domainName,
        'Stage Name': stageName,
        'Query Strings': qs}
    logging.info(connectionInfo)
    return {"statusCode": 200}
```

------

### 使用非代理整合傳遞連線資訊
<a name="websocket-connect-non-proxy-integration"></a>
+ 您可以透過非代理整合存取連線資訊。設定整合要求並提供 WebSocket API 要求範本。下列 [Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 對應範本以提供整合要求。此要求會將下列詳細資訊傳送至非 Proxy 整合：
  + 連線 ID
  + 網域名稱
  + 階段名稱
  + 路徑
  + 標頭
  + 查詢字串

  此要求會將連線 ID、網域名稱、階段名稱、路徑、標頭和查詢字串傳送至非 Proxy 整合。

  ```
  {
      "connectionId": "$context.connectionId",
      "domain": "$context.domainName",
      "stage": "$context.stage",
      "params": "$input.params()"
  }
  ```

  如需設定資料轉換的詳細資訊，請參閱 [API Gateway 中用於 WebSocket API 的資料轉換](websocket-api-data-transformations.md)。

  如要完成整合請求，請設定整合回應的 `StatusCode: 200`。若要深入瞭解如何設定整合回應，請參閱 [使用 API Gateway 主控台設定整合回應](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-using-console)。

## `$disconnect` 路由
<a name="apigateway-websocket-api-routes-about-disconnect"></a>

`$disconnect` 路由會在連線關閉後執行。

連線可以由伺服器或用戶端關閉。由於連接在執行時已經關閉，`$disconnect` 是一個最佳努力的事件。API Gateway 會盡力將 `$disconnect` 事件傳遞給整合，但無法保證傳遞成功。

後端可以透過使用 `@connections` API 來起使化中斷連線。如需詳細資訊，請參閱[在後端服務使用 `@connections` 命令](apigateway-how-to-call-websocket-api-connections.md)。