기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
WebSockets 를 사용하여 메시지 수신
Amazon Chime JSSDK
나열된 순서대로 다음 주제를 따라 사용을 시작합니다 WebSockets.
IAM 정책 정의
시작하려면 WebSocket 연결을 설정할 수 있는 권한을 부여하는 IAM 정책을 정의합니다. 다음 예제 정책은 연결을 설정할 수 있는 AppInstanceUser WebSocket 권한을 부여합니다.
"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 엔드포인트를 검색합니다.
에서 URL 반환한 를 사용합니다. GetMessagingSessionEndpoint API 서명 버전 4 서명된 를 구성합니다 WebSocket URL. 도움이 필요한 경우 연결 설정하기 섹션의 지침을 따르세요.
참고
WebSocket URLs 에는 다음 양식이 있습니다.
id.region.ws-messaging.chime.aws
연결 설정하기
엔드포인트를 검색한 후 연결을 사용하여 Amazon Chime SDK 백엔드 서버에 대한 WebSocket 연결을 API 설정하고 에 대한 메시지를 수신합니다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은 AWS 서명 버전 4 인증만 SDK 지원하므로 이 값은 입니다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을 Coordinated Universal Time(UTC)으로 변환하고 로 제출해야 합니다20200801T083241Z.
X-Amz-Signed-Headers
서명 계산에 사용한 헤더를 나열합니다. 서명 계산에는 다음 헤더가 필요합니다.
HTTP 호스트 헤더입니다.
요청에 추가하려는 모든 x-amz-* 헤더.
참고
보안을 강화하려면 요청에 포함하려는 모든 요청 헤더에 서명해야 합니다.
X-Amz-Signatures
요청을 인증하기 위한 서명을 제공합니다. 이 서명은 Amazon Chime이 SDK 계산하는 서명과 일치해야 합니다. 그렇지 않으면 Amazon ChimeSDK은 요청을 거부합니다. 예: 733255ef022bec3f2a8701cd61d4b371f3f28c9f19EXAMPLEd48d5193d7.
X-Amz-Security-Token
Security Token Service에서 가져온 자격 증명 정보를 사용하는 경우의 선택적 자격 증명 파라미터입니다. 서비스에 대한 자세한 내용은 https://docs.aws.amazon.com/STS/최신/APIReference/을 참조하세요.
SessionId
설정 중인 WebSocket 연결의 고유한 ID를 나타냅니다.
UserArn
연결을 설정하려는 AppInstanceUser의 ID를 나타냅니다. 값은 ARN 의 이어야 합니다AppInstanceUser. 예제: arn:aws:chime: us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe
미리 가져오기를 사용하여 채널 세부 정보 전달하기
WebSocket 연결을 설정할 때 쿼리 파라미터prefetch-on=connect에 CHANNEL_DETAILS 이벤트를 전달하도록 를 지정할 수 있습니다. 미리 가져오기 기능은 연결 와 함께 제공되며API, 이 기능을 사용하면 추가 API 호출 없이 향상된 채팅 보기를 볼 수 있습니다. 사용자는 다음을 할 수 있습니다.
마지막 채널 메시지와 타임스탬프를 미리 볼 수 있습니다.
채널 멤버를 볼 수 있습니다.
채널의 읽지 않음 마커를 볼 수 있습니다.
사용자가 지정된 미리 가져오기 파라미터를 사용하여 연결하면 사용자는 연결이 설정되었음을 나타내는 세션 설정 이벤트를 수신합니다. 그러면 사용자는 최대 50개의 CHANNEL_DETAILS 이벤트를 수신합니다. 사용자에게 채널이 50개 미만인 경우 연결은 CHANNEL_DETAILS 이벤트를 통해 모든 채널을 API 미리 가져옵니다. 사용자에게 50개 이상의 채널이 있는 경우 는 읽지 않은 메시지와 최신 LastMessageTimestamp 값이 포함된 상위 50개 채널을 API 미리 가져옵니다. 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-typex-amz-chime-message-typex-amz-chime-event-reason
다음 섹션에서는 헤더의 가능한 값과 페이로드를 나열하고 설명합니다.
페이로드
Websocket 메시지는 JSON 문자열을 반환합니다. JSON 문자열의 구조는 x-amz-event-type 헤더에 따라 달라집니다. 다음 표에는 가능한 x-amz-chime-event-type 값과 페이로드가 나열되어 있습니다.
| EventType | 페이로드 형식 |
|---|---|
|
해당 없음. 이 메시지는 사용자가 에 연결한 후 한 번 전송됩니다 WebSocket. 사용자가 메시지를 수신한 후 도착하는 채널의 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-유형
다음 표에는 x-amz-chime-message-type 메시지 유형이 나와 있습니다.
| 메시지 유형 | 설명 |
|---|---|
|
웹 소켓이 STANDARD 채널 메시지를 수신할 때 전송됩니다. |
|
가 CONTROL 채널 메시지를 WebSocket 수신할 때 전송됩니다. |
|
Amazon Chime SDK Messaging에서 보낸 다른 모든 웹소켓 메시지입니다. |
x-amz-chime-event-이유
특정 사용 사례에서 지원되는 선택적 헤더입니다. 헤더는 특정 이벤트가 수신된 이유에 대한 정보를 제공합니다.
| 이벤트 이유 | 설명 |
|---|---|
하위 채널_DELETED |
엘라스틱 채널 중재자가 수신한 |
연결 끊김 처리
네트워크 연결이 변경되거나 자격 증명이 만료되면 WebSocket의 연결이 끊길 수 있습니다. 를 연 후 WebSocketAmazon Chime은 메시징 클라이언트에 일반 ping을 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
