기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # WebSockets를 사용하여 Amazon Chime SDK 메시징에서 메시지 수신 [Amazon Chime JS SDK](https://github.com/aws/amazon-chime-sdk-js)로 WebSocket을 사용하여 메시지를 수신하거나 원하는 WebSocket 클라이언트 라이브러리를 사용할 수 있습니다. WebSocket 사용을 시작하려면 다음 항목을 나열된 순서대로 따르세요. **Topics** + [IAM 정책 정의](#define-iam-policy) + [엔드포인트 검색](#retrieve-endpoint) + [연결 설정하기](#connect-api) + [미리 가져오기를 사용하여 채널 세부 정보 전달하기](#prefetch) + [이벤트 처리](#process-events) ## 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 연결에 사용되는 엔드포인트를 검색하는 방법을 설명합니다. 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API를 사용하여 WebSocket 엔드포인트를 검색합니다. 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API에서 반환된 URL을 사용하여 서명 버전 4로 서명된 WebSocket URL을 구성합니다. 도움이 필요한 경우 [연결 설정하기](#connect-api) 섹션의 지침을 따르세요. **참고** WebSocket URL의 형식은 다음과 같습니다. `id.region.ws-messaging.chime.aws` ## 연결 설정하기 엔드포인트를 검색한 후에는 연결 API를 사용하여 Amazon Chime SDK 백엔드 서버에 대한 WebSocket 연결을 설정하고 `AppInstanceUser`에 대한 메시지를 수신합니다. 요청에 서명하려면 AWS 서명 버전 4를 사용해야 합니다. 요청에 서명하는 자세한 방법은 [서명 버전 4를 사용하여 AWS 요청에 서명](https://docs.aws.amazon.com/general/latest/gr/Signature Version 4_signing.html) 단원을 참조하세요. **참고** 엔드포인트를 검색하려면 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) 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 리전 및 서비스, 즉 범위를 제공합니다. 이 값은 서명 계산에 사용하는 범위와 일치해야 합니다. 이 파라미터의 값의 일반적인 형식은 다음과 같습니다. `////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-\$1 헤더. **참고** 보안을 강화하려면 요청에 포함하려는 모든 요청 헤더에 서명해야 합니다. **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/](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html)를 참조하세요. **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** - [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) 객체의 목록으로, `CreatedTimestamp`를 기준으로 내림차순 정렬됩니다. 사용자에게 표시된 최근 20개의 메시지만 포함됩니다. 채널에 현재 사용자에게 표시되지 않는 대상 메시지가 있는 경우에는 20개 미만의 메시지가 반환될 수 있습니다. 더 많은 메시지가 있으면 `ChannelMessagesHasMore` 부울이 설정됩니다. 소프트 제한, AWS 계정 수준에서 조정 가능. + **ChannelMemberships** – [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html) 객체의 목록입니다. 최대 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: [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelSummary.html) ChannelMessages: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMessageSummary.html) ChannelMemberships: List of [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_ChannelMembershipSummary.html ) ReadMarkerTimestamp: Timestamp ChannelMessagesHasMore: Boolean }) } ``` ## 이벤트 처리 연결을 설정한 후 `AppInstanceUser`가 메시지를 수신하려면 채널에 메시지를 추가해야 합니다. 이를 위해서는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API를 사용합니다. **참고** `AppInstanceUser`는 항상 자신이 속한 모든 채널에 대한 메시지를 수신합니다. `AppInstance`가 연결을 끊으면 메시징이 중지됩니다. `AppInstanceAdmin`과 `ChannelModerator`는 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_CreateChannelMembership.html) API를 사용하여 채널에 대한 메시지를 명시적으로 추가하지 않는 한 메시지를 수신하지 않습니다. 다음 항목에서는 이벤트 처리 방법을 설명합니다. **Topics** + [메시지 구조 이해](#message-structures) + [연결 끊김 처리](#handle-disconnects) ### 메시지 구조 이해 수신되는 모든 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` 값과 페이로드가 나열되어 있습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/chime-sdk/latest/dg/websockets.html) **x-amz-chime-message-type** 다음 표에는 `x-amz-chime-message-type` 메시지 유형이 나와 있습니다. | 메시지 유형 | 설명 | | --- | --- | | `STANDARD` | 웹 소켓이 STANDARD 채널 메시지를 수신할 때 전송됩니다. | | `CONTROL` | 웹소켓이 CONTROL 채널 메시지를 수신할 때 전송됩니다. | | `SYSTEM` | Amazon Chime SDK 메시징을 통해 전송되는 기타 모든 웹 소켓 메시지입니다. | **x-amz-chime-event-reason** 특정 사용 사례에서 지원되는 선택적 헤더입니다. 헤더는 특정 이벤트가 수신된 이유에 대한 정보를 제공합니다. | 이벤트 이유 | 설명 | | --- | --- | | subchannel\$1DELETED | 엘라스틱 채널 중재자가 수신한 `DELETE_CHANNEL_MEMBERSHIP` 이벤트입니다. 멤버십 밸런싱으로 자신이 속했던 하위 채널이 삭제된 이후에만 중재자가 볼 수 있습니다. | ### 연결 끊김 처리 네트워크 연결이 변경되거나 자격 증명이 만료되면 WebSocket의 연결이 끊길 수 있습니다. WebSocket을 열면 Amazon Chime SDK가 메시징 클라이언트에 정기적인 핑을 전송하여 여전히 연결되어 있는지 확인합니다. 연결이 종료되면 클라이언트는 WebSocket 종료 코드를 수신합니다. 클라이언트는 종료 코드에 따라 재연결을 시도하거나 시도하지 않을 수 있습니다. 다음 표에는 클라이언트가 재연결에 사용할 수 있는 종료 코드가 나와 있습니다. 1000번대부터 4000번대의 클로저 코드의 경우 다음 메시지가 나타나는 경우에만 다시 연결하세요. | 클로저 코드 | 재연결 가능 여부 | 이유 | | --- | --- | --- | | 1001 | 예 | 정상 종료 | | 1006 | 예 | 비정상적 종료 | | 1011 | 예 | 내부 서버 오류 | | 1012 | 예 | 서비스 재시작 | | 1013 | 예 | 나중에 다시 시도 | | 1014 | 예 | 서버가 게이트웨이 또는 프록시 역할을 하고 있으며 업스트림 서버로부터 잘못된 응답을 받았습니다. 이는 502 HTTP 상태 코드와 유사합니다. | 4XXX 코드의 경우 다음 메시지가 나타나는 경우를 *제외하고* 항상 다시 연결하세요. | 클로저 코드 | 재연결 가능 여부 | 이유 | | --- | --- | --- | | 4002 | 아니요 | 클라이언트가 시작됨 | | 4003 | 아니요 | 금지됨 | | 4401 | 아니요 | 인증되지 않음 | 애플리케이션이 종료 코드를 사용하여 다시 연결하는 경우 애플리케이션은 다음을 수행해야 합니다. 1. [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_messaging-chime_GetMessagingSessionEndpoint.html) API를 다시 직접 호출하여 새 기본 URL을 가져옵니다. 1. IAM 자격 증명 정보가 만료된 경우 자격 증명 정보를 새로 고칩니다. 1. WebSocket을 통해 연결합니다. amazon-chime-sdk-js 라이브러리를 사용하는 경우 [needsRefresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#needsRefresh-property) 속성 및 [refresh()](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Credentials.html#refresh-property) 메서드를 구현하면 이 작업이 자동으로 처리됩니다. 작동하는 예시는 [https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx\$1L93-L101](https://github.com/aws-samples/amazon-chime-sdk/blob/dc11c4c76c78d28f618577706bba2087919a5635/apps/chat/src/providers/AuthProvider.jsx#L93-L101)을 참조하세요.