기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
메시지 WebSockets 수신에 사용
Amazon Chime JS SDK를
다음 주제를 나열된 순서대로 따라 사용을 시작하십시오. WebSockets
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 연결에 사용된 엔드포인트를 검색하는 방법을 설명합니다.
GetMessagingSessionEndpointAPI를 사용하여 WebSocket 엔드포인트를 검색합니다.
GetMessagingSessionEndpointAPI에서 반환된 URL을 사용하여 서명 버전 4로 서명된 WebSocket URL을 생성합니다. 도움이 필요한 경우 연결 설정하기 섹션의 지침을 따르세요.
참고
WebSocket URL의 형식은 다음과 같습니다.
id.region.ws-messaging.chime.aws
연결 설정하기
엔드포인트를 검색한 후에는 connect API를 사용하여 Amazon Chime SDK 백엔드 서버에 대한 WebSocket 연결을 설정하고 엔드포인트에 대한 메시지를 수신합니다. AppInstanceUser 요청에 서명하려면 AWS 서명 버전 4를 사용해야 합니다. 요청 서명에 대한 자세한 내용은 서명 버전 4를 사용한 AWS
요청 서명을 참조하십시오.
참고
엔드포인트를 검색하려면 GetMessagingSessionEndpointAPI를 호출할 수 있습니다. 선택한 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
설정 중인 연결의 고유 ID를 나타냅니다. WebSocket
UserArn
연결을 설정하려는 AppInstanceUser의 ID를 나타냅니다. 값은 AppInstanceUser의 ARN이어야 합니다. 예제: arn:aws:chime: us%2Deast%2D1:123456789012:app%2Dinstance/694d2099%2Dcb1e%2D463e%2D9d64%2D697ff5b8950e/user/johndoe
미리 가져오기를 사용하여 채널 세부 정보 전달하기
WebSocket 연결을 설정할 때 쿼리 파라미터에 이벤트를 CHANNEL_DETAILS 전달하도록 지정할 prefetch-on=connect 수 있습니다. 미리 가져오기 기능은 Connect API와 함께 제공되며, 이 기능을 통해 사용자는 추가 API 호출 없이 풍부한 채팅 보기를 볼 수 있습니다. 사용자는 다음을 할 수 있습니다.
마지막 채널 메시지와 타임스탬프를 미리 볼 수 있습니다.
채널 멤버를 볼 수 있습니다.
채널의 읽지 않음 마커를 볼 수 있습니다.
사용자가 지정된 미리 가져오기 파라미터를 사용하여 연결하면 사용자는 연결이 설정되었음을 나타내는 세션 설정 이벤트를 수신합니다. 그러면 사용자는 최대 50개의 CHANNEL_DETAILS 이벤트를 수신합니다. 사용자의 채널이 50개 미만인 경우 연결 API는 CHANNEL_DETAILS 이벤트를 통해 모든 채널을 미리 가져오기합니다. 사용자의 채널이 50개 이상인 경우 API는 읽지 않은 메시지가 포함된 상위 50개 채널과 최신 LastMessageTimestamp 값을 미리 가져오기합니다. CHANNEL_DETAILS 이벤트는 무작위 순서로 도착하며 50개 채널 모두에 대한 이벤트를 수신합니다.
또한 미리 가져오기는 ChannelMessages 및 ChannelMemberships에 대해 다음을 반환합니다.
ChannelMessages—
CreatedTimestamp내림차순으로 정렬된 ChannelMessageSummary개체 목록입니다. 사용자에게 표시된 최근 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가 메시지를 수신하려면 채널에 메시지를 추가해야 합니다. 이를 위해서는 CreateChannelMembershipAPI를 사용하세요.
참고
AppInstanceUser는 항상 자신이 속한 모든 채널에 대한 메시지를 수신합니다. AppInstance가 연결을 끊으면 메시징이 중지됩니다.
CreateChannelMembershipAPI를 사용하여 명시적으로 ChannelModerator 추가하지 않는 한 AppInstanceAdmin An과 a는 채널에서 메시지를 수신하지 않습니다.
다음 항목에서는 이벤트 처리 방법을 설명합니다.
메시지 구조 이해
수신하는 모든 WebSocket 메시지는 다음 형식을 따릅니다.
{ "Headers": {"key": "value"}, "Payload": "{\"key\": \"value\"}" }
헤더
Amazon Chime SDK 메시징은 다음 헤더 키를 사용합니다.
x-amz-chime-event-typex-amz-chime-message-typex-amz-chime-event-reason
다음 섹션에서는 헤더의 가능한 값과 페이로드를 나열하고 설명합니다.
페이로드
웹소켓 메시지는 JSON 문자열을 반환합니다. JSON 문자열의 구조는 x-amz-event-type 헤더에 따라 달라집니다. 다음 표에는 가능한 x-amz-chime-event-type 값과 페이로드가 나열되어 있습니다.
| EventType | 페이로드 형식 |
|---|---|
|
해당 없음. 이 메시지는 사용자가 에 연결한 후에 한 번 전송됩니다. WebSocket 이는 사용자가 메시지를 받은 후 도착하는 채널의 모든 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
x-amz-chime-message-type
다음 표에는 x-amz-chime-message-type 메시지 유형이 나와 있습니다.
| 메시지 유형 | 설명 |
|---|---|
|
웹 소켓이 STANDARD 채널 메시지를 수신할 때 전송됩니다. |
|
CONTROL 채널 메시지를 WebSocket 수신할 때 전송됩니다. |
|
Amazon Chime SDK 메시징을 통해 전송되는 기타 모든 웹 소켓 메시지입니다. |
x-amz-chime-event-reason
특정 사용 사례에서 지원되는 선택적 헤더입니다. 헤더는 특정 이벤트가 수신된 이유에 대한 정보를 제공합니다.
| 이벤트 이유 | 설명 |
|---|---|
subchannel_DELETED |
엘라스틱 채널 중재자가 수신한 |
연결 끊김 처리
네트워크 연결이 변경되거나 자격 증명이 만료되면 WebSocket의 연결이 끊길 수 있습니다. WebSocketa를 열면 Amazon Chime SDK가 메시징 클라이언트에 정기적인 핑을 전송하여 여전히 연결되어 있는지 확인합니다. 연결이 종료되면 클라이언트는 종료 코드를 수신합니다. WebSocket 클라이언트는 종료 코드에 따라 재연결을 시도하거나 시도하지 않을 수 있습니다. 다음 표에는 클라이언트가 재연결에 사용할 수 있는 종료 코드가 나와 있습니다.
1000번대부터 4000번대의 클로저 코드의 경우 다음 메시지가 나타나는 경우에만 다시 연결하세요.
클로저 코드 |
재연결 가능 여부 |
이유 |
|---|---|---|
1001 |
예 |
정상 종료 |
1006 |
예 |
비정상적 종료 |
1011 |
예 |
내부 서버 오류 |
1012 |
예 |
서비스 재시작 |
1013 |
예 |
나중에 다시 시도 |
1014 |
예 |
서버가 게이트웨이 또는 프록시 역할을 하고 있으며 업스트림 서버로부터 잘못된 응답을 받았습니다. 이는 502 HTTP 상태 코드와 유사합니다. |
4XXX 코드의 경우 다음 메시지가 나타나는 경우를 제외하고 항상 다시 연결하세요.
클로저 코드 |
재연결 가능 여부 |
이유 |
|---|---|---|
4002 |
아니요 |
클라이언트가 시작됨 |
4003 |
아니요 |
금지됨 |
4401 |
아니요 |
인증되지 않음 |
애플리케이션이 종료 코드를 사용하여 다시 연결하는 경우 애플리케이션은 다음을 수행해야 합니다.
-
GetMessagingSessionEndpointAPI를 다시 호출하여 새 기본 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
