기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 스트림 세션 관리자 셸
[CreateStreamSessionAdminShell](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionAdminShell.html) API를 사용하여 스트림 세션의 라이브 런타임 환경에 연결합니다. 터미널 연결을 사용하여 로그를 검사하고, 실행 중인 프로세스를 확인하고, GPU 사용률을 검사하고, 애플리케이션 상태를 실시간으로 디버깅하여 애플리케이션 문제를 해결합니다.
**중요**
관리자 쉘은 스트림 세션에서 실행되는 애플리케이션과 동일한 수준의 액세스 권한을 부여하며, 여기에는 사용자 입력, 화면 이미지 및 애플리케이션 데이터 파일이 포함될 수 있습니다. 신뢰할 수 있는 IAM 자격 증명에만 `gameliftstreams:CreateStreamSessionAdminShell` 권한을 부여합니다.
## 사전 조건
관리자 쉘을 사용하여 스트림 세션에 연결하기 전에 용 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`, `CONNECTED`, `PENDING_CLIENT_RECONNECTION`또는 상태 중 하나여야 합니다`RECONNECTING`.
## 용 Session Manager 플러그인을 사용하여 연결 AWS Command Line Interface
를 사용하여 관리자 AWS CLI 셸 액세스 자격 증명을 요청한 다음에 [대한 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 콘솔을 확인합니다.
터미널 연결을 설정하는 데 문제가 있는 경우 일반적인 오류에 [스트림 세션 관리자 셸 문제](#troubleshoot-admin-shell) 대한 해결 방법은 섹션을 참조하세요.
## 스트림 세션 관리자 셸 문제
이 섹션에서는 [CreateStreamSessionAdminShell](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_CreateStreamSessionAdminShell.html) API를 사용하여 스트림 세션의 라이브 런타임 환경에 대한 보안 터미널 연결을 여는 것과 관련된 문제의 잠재적 원인과 해결 방법을 설명합니다.
### 터미널 연결을 아직 사용할 수 없음
`StreamSessionAccessNotReadyException` (HTTP 409)를 호출`CreateStreamSessionAdminShell`하여 수신하는 경우 Amazon GameLift Streams 세션의 라이브 런타임 환경에 대한 터미널 연결을 아직 프로비저닝할 수 없습니다.
이 문제를 해결하는 방법:
+ 몇 초 정도 기다렸다가 요청을 다시 시도합니다. 일반적으로 스트림 세션이 `ACTIVE` 상태가 된 직후에 터미널 연결을 사용할 수 있게 됩니다.
+ 반복 재시도 후에도 오류가 지속되면 [GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html)을 호출`RECONNECTING`하여 스트림 세션이 여전히 `ACTIVE`, `CONNECTED``PENDING_CLIENT_RECONNECTION`, 또는 상태 중 하나인지 확인합니다.
### 관리자 셸을 생성할 때 액세스가 거부됨
를 호출`CreateStreamSessionAdminShell`하고 `AccessDeniedException` (HTTP 403) 오류를 수신하면 호출하는 IAM 자격 증명에 필요한 권한이 없습니다. 이 문제를 해결하려면 IAM 자격 증명에 대상 스트림 그룹 리소스에 대한 `gameliftstreams:CreateStreamSessionAdminShell` 권한이 있는지 확인합니다.
### 활성 상태가 아닌 스트림 세션에 연결할 수 없음
를 호출`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이 만료되었습니다.
에서 반환한 WebSocket 엔드포인트에 연결하고 연결 오류가 `CreateStreamSessionAdminShell` 발생하면 `StreamUrl`가 만료된 것입니다. 수신 후 60초 동안 유효합니다. 이 시간 내에 연결을 설정하지 않으면 URL이 만료됩니다.
이 문제를 해결하는 방법:
+ 를 `CreateStreamSessionAdminShell` 다시 호출하여 새 `StreamUrl`, 및 `SessionId`를 가져옵니다`TokenValue`.
+ 응답을 받은 후 60초 이내에 연결을 설정합니다.
### 세션 관리자 플러그인이 설치되지 않음
에서 반환한 자격 증명을 사용하여 연결을 시도`CreateStreamSessionAdminShell`했지만 세션 관리자 플러그인이 누락되었다는 메시지와 함께 연결이 실패하는 경우 AWS CLI용 AWS Systems Manager 세션 관리자 플러그인을 설치해야 합니다.
이 문제를 해결하는 방법:
+ AWS CLI용 Session Manager 플러그인을 설치합니다. 설치 지침은 Systems [Manager 사용 설명서의 AWS CLI용 Session Manager 플러그인 설치를](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) 참조하세요. *AWS *
+ 터미널`session-manager-plugin`에서를 실행하여 플러그인이 설치되어 있는지 확인합니다.
### 관리자 셸이 예기치 않게 닫힘
사용 중에 터미널 연결이 갑자기 끊어지면 다음 이유 중 하나로 인해 종료되었을 수 있습니다.
+ 터미널 연결은 스트림 세션 수명 주기로 범위가 지정되며 스트림 세션이 `TERMINATED` 또는 `ERROR` 상태로 전환될 때 종료됩니다.
+ 터미널 연결이 최대 지속 시간인 30분을 초과했습니다.
+ 터미널 연결이 유휴 제한 시간인 15분을 초과했습니다.
이 문제를 해결하는 방법:
+ [GetStreamSession](https://docs.aws.amazon.com/gameliftstreams/latest/apireference/API_GetStreamSession.html)을 호출하여 스트림 세션이 `TERMINATED` 또는 `ERROR` 상태가 아닌지 확인합니다.
+ 유휴 또는 최대 기간으로 인해 터미널 연결 시간이 초과된 경우를 `CreateStreamSessionAdminShell` 다시 호출하여 새 터미널 연결을 엽니다.
+ 스트림 세션이 종료된 경우 새 스트림 세션을 시작하여 새 터미널 연결을 엽니다.