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

# 串流工作階段管理員 shell
<a name="troubleshoot-admin-shell-guide"></a>

使用 [CreateStreamSessionAdminShell](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionAdminShell.html) API 連線到串流工作階段的即時執行期環境。透過檢查日誌、檢查執行中的程序、檢查 GPU 使用率，以及即時偵錯應用程式狀態，使用終端機連線來疑難排解應用程式問題。

**重要**  
管理員 shell 會授予與串流工作階段上執行之應用程式相同的存取層級，其中包括使用者輸入、螢幕影像和應用程式資料檔案。僅將`gameliftstreams:CreateStreamSessionAdminShell`許可授予信任的 IAM 身分。

## 先決條件
<a name="troubleshoot-admin-shell-prerequisites"></a>

使用 admin shell 連線到串流工作階段之前，請為 安裝 AWS Systems Manager Session Manager 外掛程式 AWS Command Line Interface。需要 外掛程式才能開啟終端機連線。如需安裝說明，請參閱[安裝 的 Session Manager 外掛程式 AWS Command Line Interface](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)。

下列程式碼範例需要命令列 JSON 處理器 [jq](https://jqlang.github.io/jq/)，才能從 API 回應擷取值。

串流工作階段必須處於下列其中一種狀態：`ACTIVE`、`PENDING_CLIENT_RECONNECTION`、 `CONNECTED`或 `RECONNECTING`。

## 使用適用於 的 Session Manager 外掛程式進行連線 AWS Command Line Interface
<a name="troubleshoot-admin-shell-connect"></a>

使用 AWS CLI 請求管理員 shell 存取憑證，然後使用 [的 Session Manager 外掛程式 AWS Command Line Interface](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)來建立終端機連線。使用以下程式碼範例進行連線。將 `STREAM_GROUP_ID`、 `STREAM_SESSION_ID`和 取代`REGION`為您的值。

**AWS Command Line Interface 使用 Bash 指令碼**

```
#!/bin/bash
# GameLift Streams session with admin shell script
# This script sets up a terminal connection to an Amazon GameLift Streams session
# using the AWS Systems Manager Session Manager Plugin

# Stream group ARN or ID owning the session
STREAM_GROUP_ID="arn:aws:gameliftstreams:us-west-2:123456789012:streamgroup/sg-1AB2C3De4"

# Stream session ARN or ID to connect to
STREAM_SESSION_ID="arn:aws:gameliftstreams:us-west-2:123456789012:streamsession/sg-1AB2C3De4/44wOYoDXlRbtf"

# AWS Region where you created the stream group (primary location)
REGION="us-west-2"

# Request admin shell access
SESSION_ACCESS=$(aws gameliftstreams create-stream-session-admin-shell \
    --identifier "${STREAM_GROUP_ID}" \
    --stream-session-identifier "${STREAM_SESSION_ID}" \
    --region "${REGION}" \
    --output json)

# Extract session ID and connect using Session Manager plugin
SESSION_ID=$(echo "$SESSION_ACCESS" | jq -r .SessionId)

# Connect using the API response (the plugin extracts StreamUrl and TokenValue)
# The connection URL expires 60 seconds after the API response.
session-manager-plugin \
    "$SESSION_ACCESS" \
    "${REGION}" \
    "StartSession" \
    "" \
    "{\"Target\":\"$SESSION_ID\"}" \
    "https://ssm.${REGION}.api.aws"
```

**提示**  
若要尋找串流群組的作用中串流工作階段，請使用 [ListStreamSessions](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_ListStreamSessions.html) API 操作或檢查 Amazon GameLift Streams 主控台。

如果您在建立終端機連線時遇到問題，請參閱 [串流工作階段管理員 shell 問題](#troubleshoot-admin-shell) 以取得常見錯誤的解決方案。

## 串流工作階段管理員 shell 問題
<a name="troubleshoot-admin-shell"></a>

本節識別與使用 [CreateStreamSessionAdminShell](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionAdminShell.html) API 在串流工作階段的即時執行時間環境中開啟安全終端機連線相關問題的潛在原因和解決方案。

### 尚未提供終端機連線
<a name="troubleshoot-admin-shell-not-ready"></a>

如果您呼叫 `CreateStreamSessionAdminShell` 並接收 `StreamSessionAccessNotReadyException`(HTTP 409)，則無法佈建與 Amazon GameLift Streams 工作階段即時執行時間環境的終端機連線。

若要解決此問題：
+ 等待幾秒鐘，然後重試請求。終端機連線通常會在串流工作階段進入 `ACTIVE` 狀態後立即變成可用。
+ 如果重複重試後錯誤仍然存在，請呼叫 [GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html) `RECONNECTING`來驗證串流工作階段是否仍處於下列其中一種狀態：`PENDING_CLIENT_RECONNECTION`、、 `ACTIVE` `CONNECTED`或 。

### 建立管理員 shell 時存取遭拒
<a name="troubleshoot-admin-shell-access-denied"></a>

如果您呼叫 `CreateStreamSessionAdminShell`並收到 `AccessDeniedException`(HTTP 403) 錯誤，呼叫的 IAM 身分沒有必要的許可。若要解決此問題，請確認 IAM 身分具有目標串流群組資源的`gameliftstreams:CreateStreamSessionAdminShell`許可。

### 無法連線至非作用中的串流工作階段
<a name="troubleshoot-admin-shell-not-active"></a>

如果您呼叫 `CreateStreamSessionAdminShell`並收到 `ResourceNotFoundException`(HTTP 404) 或 `ValidationException`(HTTP 400) 錯誤，請確認託管串流工作階段的串流群組處於 `ACTIVE` 狀態，且串流工作階段處於下列其中一種狀態：`ACTIVE`、`PENDING_CLIENT_RECONNECTION`、 `CONNECTED`或 `RECONNECTING`。

若要解決此問題：
+ 呼叫 [GetStreamGroup](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamGroup.html) 驗證串流群組狀態。
+ 呼叫 [GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html) 驗證串流工作階段狀態。
+ 如果工作階段最近開始，請等到工作階段狀態轉換為 ，`ACTIVE`再請求終端機連線。

### StreamUrl 已過期
<a name="troubleshoot-admin-shell-url-expired"></a>

如果您連線到 傳回的 WebSocket 端點`CreateStreamSessionAdminShell`並收到連線錯誤，則 `StreamUrl`已過期。它在您收到後 60 秒內有效。如果您未在這段時間內建立連線，URL 便會過期。

若要解決此問題：
+ `CreateStreamSessionAdminShell` 再次呼叫 以取得新的 `StreamUrl`、 `SessionId`和 `TokenValue`。
+ 在收到回應後 60 秒內建立連線。

### 未安裝 Session Manager 外掛程式
<a name="troubleshoot-admin-shell-plugin-missing"></a>

如果您嘗試使用 傳回的登入資料進行連線，`CreateStreamSessionAdminShell`且連線失敗，且訊息指出缺少 Session Manager 外掛程式，則需要安裝 CLI AWS 的 AWS Systems Manager Session Manager 外掛程式。

若要解決此問題：
+ 安裝 CLI 的 Session Manager AWS 外掛程式。如需安裝說明，請參閱 Systems [Manager 使用者指南中的安裝 CLI AWS 的 Session Manager 外掛程式](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)。 *AWS *
+ `session-manager-plugin` 從終端機執行 ，確認外掛程式已安裝。

### 管理員殼層意外關閉
<a name="troubleshoot-admin-shell-closes"></a>

如果您的終端機連線在使用期間突然中斷連線，可能會因為下列其中一個原因而關閉：
+ 終端機連線的範圍是串流工作階段生命週期，並在串流工作階段轉換為 `TERMINATED`或 `ERROR` 狀態時結束。
+ 終端機連線超過其最長持續時間 30 分鐘。
+ 終端機連線超過閒置逾時 15 分鐘。

若要解決此問題：
+ 呼叫 [GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html)，確認串流工作階段未處於 `TERMINATED`或 `ERROR` 狀態。
+ 如果終端機連線因閒置或最長持續時間而逾時，請`CreateStreamSessionAdminShell`再次呼叫 以開啟新的終端機連線。
+ 如果串流工作階段已結束，請啟動新的串流工作階段以開啟新的終端機連線。