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

# 直播会话管理外壳
<a name="troubleshoot-admin-shell-guide"></a>

使用 [CreateStreamSessionAdminShell](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionAdminShell.html)API 连接到直播会话的实时运行时环境。使用终端连接通过检查日志、检查正在运行的进程、检查 GPU 利用率和实时调试应用程序状态来解决应用程序问题。

**重要**  
管理外壳授予的访问权限级别与在流会话中运行的应用程序相同，其中可以包括用户输入、屏幕图像和应用程序数据文件。仅向可信的 IAM 身份授予`gameliftstreams:CreateStreamSessionAdminShell`权限。

## 先决条件
<a name="troubleshoot-admin-shell-prerequisites"></a>

在使用管理外壳连接到直播会话之前，请安装适用于的 Syst AWS ems Manager 会话管理器插件 AWS Command Line Interface。需要使用插件才能打开终端连接。有关安装说明，请参阅[安装会话管理器插件 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`、`CONNECTED``PENDING_CLIENT_RECONNECTION`、或`RECONNECTING`。

## 使用会话管理器插件连接 AWS Command Line Interface
<a name="troubleshoot-admin-shell-connect"></a>

使用请求管理员 shell 访问凭证，然后使用的 S [ession Manager 插件](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)建立终端连接。 AWS CLI 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"
```

**提示**  
要查找直播组的活跃直播会话，请使用 [ListStreamSessions](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_ListStreamSessions.html)API 操作或查看 Amazon GameLift Streams 控制台。

如果您在建立终端连接时遇到问题，[直播会话管理外壳问题](#troubleshoot-admin-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`状态后不久就可用。
+ 如果重复重试后错误仍然存在，请验证直播会话是否仍处于以下状态之一：`ACTIVE`、`CONNECTED``PENDING_CLIENT_RECONNECTION`、或`RECONNECTING`通过调用[GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html)。

### 创建管理员 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`、`CONNECTED``PENDING_CLIENT_RECONNECTION`、或`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 秒内建立连接。

### 未安装会话管理器插件
<a name="troubleshoot-admin-shell-plugin-missing"></a>

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

要解决此问题，请执行以下操作：
+ 安装 AWS CLI 的会话管理器插件。有关安装说明，请参阅[《Syst *AWS ems Manager 用户指南》中的 AWS CLI 安装会话管理器*插件](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)。
+ 通过`session-manager-plugin`从终端运行来验证插件是否已安装。

### 管理外壳意外关闭
<a name="troubleshoot-admin-shell-closes"></a>

如果您的终端连接在使用过程中突然断开连接，则可能是由于以下原因之一而关闭的：
+ 终端连接的作用域限于直播会话生命周期，并在直播会话转换到`TERMINATED`或`ERROR`状态时结束。
+ 终端连接超过了其最长持续时间（30 分钟）。
+ 终端连接超过了 15 分钟的空闲超时时间。

要解决此问题，请执行以下操作：
+ 通过调用验证直播会话是否未处于`TERMINATED`或`ERROR`状态[GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html)。
+ 如果终端连接由于空闲或最长持续时间而超时，请`CreateStreamSessionAdminShell`再次调用以打开新的终端连接。
+ 如果直播会话已结束，请启动新的直播会话以打开新的终端连接。