기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
WebSockets를 사용하여 Amazon Chime SDK 메시징에서 메시지 수신
Amazon Chime JS SDK
WebSocket 사용을 시작하려면 다음 항목을 나열된 순서대로 따르세요.
IAM 정책 정의
시작하려면 WebSocket 연결을 설정할 수 있는 권한을 부여하는 IAM 정책을 정의합니다. 다음 예제 정책은 WebSocket 연결을 설정할 수 있는 AppInstanceUser 권한을 제공합니다.
"Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action: [ "chime:Connect" ], "Resource": [ "arn:aws:chime:region:{aws_account_id}:app-instance/{app_instance_id}/user/{app_instance_user_id}" ] }, { "Effect": "Allow", "Action: [ "chime:GetMessagingSessionEndpoint" ], "Resource": [ "*" ] } ] }
엔드포인트 검색
다음 단계에서는 WebSocket 연결에 사용되는 엔드포인트를 검색하는 방법을 설명합니다.
-
GetMessagingSessionEndpoint API를 사용하여 WebSocket 엔드포인트를 검색합니다.
-
GetMessagingSessionEndpoint API에서 반환된 URL을 사용하여 서명 버전 4로 서명된 WebSocket URL을 구성합니다. 도움이 필요한 경우 연결 설정하기 섹션의 지침을 따르세요.
참고
WebSocket URL의 형식은 다음과 같습니다.
id.region.ws-messaging.chime.aws
연결 설정하기
엔드포인트를 검색한 후에는 연결 API를 사용하여 Amazon Chime SDK 백엔드 서버에 대한 WebSocket 연결을 설정하고 AppInstanceUser에 대한 메시지를 수신합니다. 요청에 서명하려면 AWS 서명 버전 4를 사용해야 합니다. 요청에 서명하는 자세한 방법은 서명 버전 4를 사용하여 AWS
요청에 서명 단원을 참조하세요.
참고
엔드포인트를 검색하려면 GetMessagingSessionEndpoint API를 간접 호출하면 됩니다. 선택한 WebSocket 클라이언트 라이브러리를 사용하여 엔드포인트에 연결할 수 있습니다.
요청 구문
GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request &X-Amz-Date=20201214T171359Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host &sessionId={sessionId} &userArn={appInstanceUserArn} &X-Amz-Signature=db75397d79583EXAMPLE
URI 요청 파라미터
모든 URI 요청 쿼리 파라미터는 URL로 인코딩되어야 합니다.
X-Amz-Algorithm
AWS 서명 버전과 서명을 계산하는 데 사용한 알고리즘을 식별합니다. Amazon Chime SDK는 AWS 서명 버전 4 인증만 지원하므로, 이 항목의 값은 AWS4-HMAC-SHA256입니다.
X-Amz-Credential
이 파라미터는 액세스 키 ID 외에도 서명이 유효한 AWS 리전 및 서비스, 즉 범위를 제공합니다. 이 값은 서명 계산에 사용하는 범위와 일치해야 합니다. 이 파라미터의 값의 일반적인 형식은 다음과 같습니다.
<yourAccessKeyId>/<date>/<awsRegion>/<awsService
>/aws4_request
예시:
AKIAIOSFODNN7EXAMPLE/20201214/us-east-1/chime/aws4_request
X-Amz-Date
날짜 및 시간 형식은 ISO 8601 표준을 따르고, yyyyMMddTHHmmssZ 형식을 사용해야 합니다. 예를 들어, 08/01/2020 15:32:41.982-700를 협정 세계시(UTC)로 변환하고 이를 20200801T083241Z로 제출해야 합니다.
X-Amz-Signed-Headers
서명 계산에 사용한 헤더를 나열합니다. 서명 계산에는 다음 헤더가 필요합니다.
HTTP 호스트 헤더.
요청에 추가하려는 모든 x-amz-* 헤더.
참고
보안을 강화하려면 요청에 포함하려는 모든 요청 헤더에 서명해야 합니다.
X-Amz-Signatures
요청을 인증하기 위한 서명을 제공합니다. 이 서명은 Amazon Chime SDK가 계산하는 서명과 일치해야 합니다. 그렇지 않으면 Amazon Chime SDK는 요청을 거부합니다. 예: 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.
X-Amz-Security-Token
Security Token Service에서 가져온 자격 증명 정보를 사용하는 경우의 선택적 자격 증명 파라미터입니다. 서비스에 대한 자세한 정보는 https://docs.aws.amazon.com/STS/latest/APIReference/를 참조하세요.
SessionId
설정 중인 WebSocket 연결의 고유 ID를 나타냅니다.
UserArn
연결을 설정하려는 AppInstanceUser의 ID를 나타냅니다. 값은 AppInstanceUser의 ARN이어야 합니다. 예제: arn:aws:chime: us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe
미리 가져오기를 사용하여 채널 세부 정보 전달하기
WebSocket 연결을 설정할 때 쿼리 파라미터에 prefetch-on=connect를 지정하여 CHANNEL_DETAILS 이벤트를 전달할 수 있습니다. 미리 가져오기 기능은 Connect API와 함께 제공되며, 이 기능을 통해 사용자는 추가 API 호출 없이 풍부한 채팅 보기를 볼 수 있습니다. 사용자는 다음을 할 수 있습니다.
마지막 채널 메시지와 타임스탬프를 미리 볼 수 있습니다.
채널 멤버를 볼 수 있습니다.
채널의 읽지 않음 마커를 볼 수 있습니다.
사용자가 지정된 미리 가져오기 파라미터를 사용하여 연결하면 사용자는 연결이 설정되었음을 나타내는 세션 설정 이벤트를 수신합니다. 그러면 사용자는 최대 50개의 CHANNEL_DETAILS 이벤트를 수신합니다. 사용자의 채널이 50개 미만인 경우 연결 API는 CHANNEL_DETAILS 이벤트를 통해 모든 채널을 미리 가져오기합니다. 사용자의 채널이 50개 이상인 경우 API는 읽지 않은 메시지가 포함된 상위 50개 채널과 최신 LastMessageTimestamp 값을 미리 가져오기합니다. CHANNEL_DETAILS 이벤트는 무작위 순서로 도착하며 50개 채널 모두에 대한 이벤트를 수신합니다.
또한 미리 가져오기는 ChannelMessages 및 ChannelMemberships에 대해 다음을 반환합니다.
ChannelMessages - ChannelMessageSummary 객체의 목록으로,
CreatedTimestamp를 기준으로 내림차순 정렬됩니다. 사용자에게 표시된 최근 20개의 메시지만 포함됩니다. 채널에 현재 사용자에게 표시되지 않는 대상 메시지가 있는 경우에는 20개 미만의 메시지가 반환될 수 있습니다. 더 많은 메시지가 있으면ChannelMessagesHasMore부울이 설정됩니다. 소프트 제한, AWS 계정 수준에서 조정 가능.ChannelMemberships – ChannelMembershipSummary 객체의 목록입니다. 최대 30명의 채널 멤버를 포함합니다. 소프트 제한, AWS 계정 수준에서 조정 가능.
이 예시에서는 prefetch-on=connect를 사용하는 방법을 보여 줍니다.
GET /connect ?X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIARALLEXAMPLE%2F20201214%2Fregion%2Fchime%2Faws4_request &X-Amz-Date=20201214T171359Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host &sessionId=sessionId&prefetch-on=connect &userArn=appInstanceUserArn&X-Amz-Signature=db75397d79583EXAMPLE
이 예시는 한 채널에 대한 응답을 보여 줍니다. 50개 채널 모두에 대한 응답을 받게 됩니다.
{ "Headers": { "x-amz-chime-event-type": "CHANNEL_DETAILS", "x-amz-chime-message-type": "SYSTEM" }, "Payload": JSON.stringify"({ Channel: ChannelSummary ChannelMessages: List of ChannelMessageSummary ChannelMemberships: List of ChannelMembershipSummary ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) }
이벤트 처리
연결을 설정한 후 AppInstanceUser가 메시지를 수신하려면 채널에 메시지를 추가해야 합니다. 이를 위해서는 CreateChannelMembership API를 사용합니다.
참고
AppInstanceUser는 항상 자신이 속한 모든 채널에 대한 메시지를 수신합니다. AppInstance가 연결을 끊으면 메시징이 중지됩니다.
AppInstanceAdmin과 ChannelModerator는 CreateChannelMembership API를 사용하여 채널에 대한 메시지를 명시적으로 추가하지 않는 한 메시지를 수신하지 않습니다.
다음 항목에서는 이벤트 처리 방법을 설명합니다.
메시지 구조 이해
수신되는 모든 WebSocket 메시지는 다음 형식을 따릅니다.
{ "Headers": {"key": "value"}, "Payload": "{\"key\": \"value\"}" }
헤더
Amazon Chime SDK 메시징은 다음 헤더 키를 사용합니다.
-
x-amz-chime-event-type -
x-amz-chime-message-type -
x-amz-chime-event-reason
다음 섹션에서는 헤더의 가능한 값과 페이로드를 나열하고 설명합니다.
페이로드
웹소켓 메시지는 JSON 문자열을 반환합니다. JSON 문자열의 구조는 x-amz-event-type 헤더에 따라 달라집니다. 다음 표에는 가능한 x-amz-chime-event-type 값과 페이로드가 나열되어 있습니다.
| EventType | 페이로드 형식 |
|---|---|
|
해당 없음. 이 메시지는 사용자가 WebSocket에 연결한 후 한 번 전송됩니다. 이는 WebSocket이 열려 있는 한 사용자가 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-type
다음 표에는 x-amz-chime-message-type 메시지 유형이 나와 있습니다.
| 메시지 유형 | 설명 |
|---|---|
|
웹 소켓이 STANDARD 채널 메시지를 수신할 때 전송됩니다. |
|
웹소켓이 CONTROL 채널 메시지를 수신할 때 전송됩니다. |
|
Amazon Chime SDK 메시징을 통해 전송되는 기타 모든 웹 소켓 메시지입니다. |
x-amz-chime-event-reason
특정 사용 사례에서 지원되는 선택적 헤더입니다. 헤더는 특정 이벤트가 수신된 이유에 대한 정보를 제공합니다.
| 이벤트 이유 | 설명 |
|---|---|
subchannel_DELETED |
엘라스틱 채널 중재자가 수신한 |
연결 끊김 처리
네트워크 연결이 변경되거나 자격 증명이 만료되면 WebSocket의 연결이 끊길 수 있습니다. WebSocket을 열면 Amazon Chime SDK가 메시징 클라이언트에 정기적인 핑을 전송하여 여전히 연결되어 있는지 확인합니다. 연결이 종료되면 클라이언트는 WebSocket 종료 코드를 수신합니다. 클라이언트는 종료 코드에 따라 재연결을 시도하거나 시도하지 않을 수 있습니다. 다음 표에는 클라이언트가 재연결에 사용할 수 있는 종료 코드가 나와 있습니다.
1000번대부터 4000번대의 클로저 코드의 경우 다음 메시지가 나타나는 경우에만 다시 연결하세요.
클로저 코드 |
재연결 가능 여부 |
이유 |
|---|---|---|
1001 |
예 |
정상 종료 |
1006 |
예 |
비정상적 종료 |
1011 |
예 |
내부 서버 오류 |
1012 |
예 |
서비스 재시작 |
1013 |
예 |
나중에 다시 시도 |
1014 |
예 |
서버가 게이트웨이 또는 프록시 역할을 하고 있으며 업스트림 서버로부터 잘못된 응답을 받았습니다. 이는 502 HTTP 상태 코드와 유사합니다. |
4XXX 코드의 경우 다음 메시지가 나타나는 경우를 제외하고 항상 다시 연결하세요.
클로저 코드 |
재연결 가능 여부 |
이유 |
|---|---|---|
4002 |
아니요 |
클라이언트가 시작됨 |
4003 |
아니요 |
금지됨 |
4401 |
아니요 |
인증되지 않음 |
애플리케이션이 종료 코드를 사용하여 다시 연결하는 경우 애플리케이션은 다음을 수행해야 합니다.
-
GetMessagingSessionEndpoint API를 다시 직접 호출하여 새 기본 URL을 가져옵니다.
IAM 자격 증명 정보가 만료된 경우 자격 증명 정보를 새로 고칩니다.
-
WebSocket을 통해 연결합니다.
amazon-chime-sdk-js 라이브러리를 사용하는 경우 needsRefresh() 속성 및 refresh() 메서드를 구현하면 이 작업이 자동으로 처리됩니다. 작동하는 예시는 https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101
