本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

直播会话管理外壳

使用 CreateStreamSessionAdminShellAPI 连接到直播会话的实时运行时环境。使用终端连接通过检查日志、检查正在运行的进程、检查 GPU 利用率和实时调试应用程序状态来解决应用程序问题。

先决条件

在使用管理外壳连接到直播会话之前，请安装适用于的 Syst AWS ems Manager 会话管理器插件 AWS Command Line Interface。需要使用插件才能打开终端连接。有关安装说明，请参阅安装会话管理器插件 AWS Command Line Interface。

下面的代码示例要求命令行 JSON 处理器 jq 从 API 响应中提取值。

直播会话必须处于以下状态之一：ACTIVE、CONNECTEDPENDING_CLIENT_RECONNECTION、或RECONNECTING。

使用会话管理器插件连接 AWS Command Line Interface

使用请求管理员 shell 访问凭证，然后使用的 S ession Manager 插件建立终端连接。 AWS CLI AWS Command Line Interface使用以下代码示例进行连接。用您的值替换STREAM_GROUP_IDSTREAM_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"

如果您在建立终端连接时遇到问题，直播会话管理外壳问题请参阅，了解常见错误的解决方案。

直播会话管理外壳问题

本节列出了与使用 CreateStreamSessionAdminShellAPI 在直播会话的实时运行时环境中打开安全终端连接相关的问题的潜在原因和解决方案。

终端连接尚不可用

如果您调用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、CONNECTEDPENDING_CLIENT_RECONNECTION、或RECONNECTING。

要解决此问题，请执行以下操作：

StreamUrl 已过期

如果您连接到返回的 WebSocket 终端节点CreateStreamSessionAdminShell并收到连接错误，则说明StreamUrl已过期。它在您收到后的 60 秒内有效。如果您未在这段时间内建立连接，则 URL 将过期。

要解决此问题，请执行以下操作：

未安装会话管理器插件

如果您尝试使用返回的凭据进行连接，但连接失败CreateStreamSessionAdminShell并显示一条表明缺少会话管理器插件的消息，则需要安装适用于 AWS CLI 的 S AWS ystems Manager 会话管理器插件。

要解决此问题，请执行以下操作：

管理外壳意外关闭

如果您的终端连接在使用过程中突然断开连接，则可能是由于以下原因之一而关闭的：

要解决此问题，请执行以下操作：