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

串流工作階段管理員 shell

使用 CreateStreamSessionAdminShell API 連線到串流工作階段的即時執行期環境。透過檢查日誌、檢查執行中的程序、檢查 GPU 使用率，以及即時偵錯應用程式狀態，使用終端機連線來疑難排解應用程式問題。

先決條件

使用 admin shell 連線到串流工作階段之前，請為 安裝 AWS Systems Manager Session Manager 外掛程式 AWS Command Line Interface。需要 外掛程式才能開啟終端機連線。如需安裝說明，請參閱安裝 的 Session Manager 外掛程式 AWS Command Line Interface。

下列程式碼範例需要命令列 JSON 處理器 jq，才能從 API 回應擷取值。

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

使用適用於 的 Session Manager 外掛程式進行連線 AWS Command Line Interface

使用 AWS CLI 請求管理員 shell 存取憑證，然後使用 的 Session Manager 外掛程式 AWS Command Line Interface來建立終端機連線。使用以下程式碼範例進行連線。將 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"

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

串流工作階段管理員 shell 問題

本節識別與使用 CreateStreamSessionAdminShell API 在串流工作階段的即時執行時間環境中開啟安全終端機連線相關問題的潛在原因和解決方案。

尚未提供終端機連線

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

若要解決此問題：

建立管理員 shell 時存取遭拒

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

無法連線至非作用中的串流工作階段

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

若要解決此問題：

StreamUrl 已過期

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

若要解決此問題：

未安裝 Session Manager 外掛程式

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

若要解決此問題：

管理員殼層意外關閉

如果您的終端機連線在使用期間突然中斷連線，可能會因為下列其中一個原因而關閉：

若要解決此問題：