메시지 수신

Pub/Sub에서 제공하는 서브스크립션 유형에 따라 메시지 수신 방법을 설명합니다.

서브스크립션 유형이 `Pull`인 경우

Pub/Sub 서비스에서 서브스크립션 유형을 Pull로 생성한 경우, 사용자는 서브스크립션을 통해 메시지를 수신한 후 확인 응답을 할 수 있습니다. 서브스크립션 생성에 대한 자세한 설명은 서브스크립션 생성을 참고하시기 바랍니다.

안내

API를 통한 메시지 수신 요청을 위해서는 카카오클라우드 콘솔 > 사용자 프로필 > 액세스 키 탭에서 액세스 키 ID와 보안 액세스 키를 발급받아야 합니다.

주요 개념

주요 개념	설명
서브스크립션 유형	`Pull`: 사용자가 메시지 전송을 요청
응답 대기 시간	메시지 확인 응답까지 대기하는 시간 - 시간 범위: 10-600초(10분) 이내 설정
확인 응답	응답 대기 시간 안에 메시지 확인 처리(ack)를 하지 않는 경우, 메시지 재전송

서브스크립션 생성

Pub/Sub 서비스에서 서브스크립션 유형을 Pull로 선택하여 서브스크립션을 생성합니다. 서브스크립션 생성에 대한 자세한 설명은 서브스크립션 생성을 참고하시기 바랍니다.

메시지 수신하기

서브스크립션 유형이 Pull인 경우, 콘솔 또는 API를 통해 메시지를 수신할 수 있습니다.

콘솔
API

토픽에 게시된 메시지를 콘솔 상 수신 테스트를 통해 확인할 수 있습니다.

안내

수신 테스트를 하기 위해서는 사전에 토픽에서 메시지를 게시해야 합니다. 자세한 내용은 메시지 게시를 참고하시기 바랍니다.

카카오클라우드 콘솔 > Analytics > Pub/Sub 메뉴로 이동합니다.
Topic 메뉴에서 수신 테스트할 서브스크립션이 있는 토픽을 선택합니다.

메시지 탭에서 수신 테스트 항목을 설정 후, [메시지 가져오기] 버튼을 클릭합니다.

메시지 탭

No	구분	설명
①	서브스크립션 선택	서브스크립션 선택 박스
②	가져올 메시지 건수	가져올 메시지 건 수
③	메시지 내용	게시된 메시지 본문의 내용, 없는 경우 - 으로 노출
④	게시 시간	메시지가 게시된 시간
⑤	속성	게시된 메시지의 속성값, 속성 보기를 클릭해 Key, Value 확인 가능
⑥	재처리 횟수	해당 메시지가 재처리된 횟수
⑦	확인	메시지 응답 대기 시간에 따른 확인 상태 확인: 응답 대기 시간이 지나지 않아 확인 가능한 상태, 클릭 시 확인 처리 되어 해당 메시지는 다시 가져와지지 않음 확인 기간 만료: 응답 대기 시간이 지나 콘솔에서 확인 처리가 불가능한 상태

수신 테스트 목록에서 메시지 내용 또는 속성 보기를 클릭해 상세한 메시지 내용을 확인할 수 있습니다.

속성 보기 팝업

안내

메시지 가져오기는 서브스크립션 상세 페이지의 메시지 탭에서도 수행할 수 있습니다.

💡 본문에서 안내하는 API 수신 테스트는 Default 토픽에 대한 수신 테스트입니다. 사용자가 생성한 토픽에 대한 수신 테스트는 Pub/Sub API 문서를 참고하시기 바랍니다.

Pull

토픽에 게시된 메시지를 가져옵니다.

Request Syntax

메시지 요청 Request Syntax
curl -k --location --request POST 'https://{endpoint-url}/pub-sub/kc-event/v1/projects/{project_id}/subscriptions/{subscription-name}/pull' \
  --header "Credential-ID: ****" \
  --header "Credential-Secret: ****" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "maxMessages": 1
  }'

API 호출 방식

메서드	요청 URL
POST	`/pub-sub/kc-event/v1/projects/{project_id}/subscriptions/{subscription-name}/pull`

Path	유형	필수 여부	설명
project_id	String	필수	KakaoCloud 프로젝트 ID - 해당 프로젝트의 콘솔 주소창에 표시되는 URI(`project_id`의 값)
subscription-name	String	필수	서브스크립션의 이름

Request Header

Request	유형	필수 여부	설명
Credential-ID	String	필수	액세스 키 ID
Credential-Secret	String	필수	보안 액세스 키

Request Elements

Request	유형	설명
maxMessages	Integer	최대 메시지 요청 수 1개 ~ 4,096개

Response Syntax

메시지 요청 Response Syntax
{
  "receivedMessages": [
    {
      "ackId": "Ifaswn660rXu8FZdE2ki7upOjG4pI3Q3eaqNHJxIOXZ4Abj5VpCQRXm/EPoxDHTgImaXz8HK7P5l1rmhLoSJaf0Q330DO10BivvG+yt4sEGMGLc5wB4VKACuzGDTFOAyhFAkualNoKqZLyzQYAJuILZeZfO7BUBmmMkS3O+pZlMvxmthpyDrNnyUmLBb2uXlzig5kBWh0ZFWegioX7nLs/uODqMhlj2U2qEX6E33q0R9qEuJjv4HWEnVRjrTUdrRV6fiahbf7gnH68jN9f0+MisPBqPLzpQBj+eyqt2BZAq9J2cn70I5lzErIpxMBPXwfmM4sF7MhtyvaNvAbq9Sm02IVOIwxHDsoON/yjggIVeY5g+6XvKQgq5/jg==",
      "message": {
        "data": "eyJldmVudF92ZXJzaW9uIjoiMS4wLjAiLCJldmVudF9pZCI6InRyYWlsXzBfNjAzNDUyNjY2XzE2Njg0MTQzNTAzMzQiLCJldmVudF9uYW1lIjoiS2V5cGFpciBjcmVhdGUiLCJldmVudF9zb3VyY2UiOiJWaXJ0dWFsIG1hY2hpbmUiLCJldmVudF90aW1lIjoiMjAyMi0xMS0xNFQwODoyNTo1MC4zMzRaIiwia2ljX3JlZ2lvbiI6Ii0iLCJkb21haW5faWQiOiI5ODJmYzM5MjY5OWQ0Mzg1YjBiMWE5ZDEwYjlmMjM5MyIsImRvbWFpbl9uYW1lIjoia2FrYW9lbnRlcnByaXNlIiwicHJvamVjdF9pZCI6IjM1MzA5NGUxMjJkNjQ5M2Q5ODk5ZjBmMjUyM2Q0Y2MxIiwicHJvamVjdF9uYW1lIjoiYmlnZGF0YSIsInJlc291cmNlX25hbWUiOiJwcHBwcGViIiwicmVzb3VyY2VfaWQiOiItIiwicmVzb3VyY2VfdHlwZSI6IktleXBhaXIiLCJ1c2VyX2lkIjoiY2Q3MGU1M2JkNGYxNDFkM2FhYjZmNjUyOGNjNGM0N2MiLCJ1c2VyX25hbWUiOiJwZWIubGVlQGtha2FvZW50ZXJwcmlzZS5jb20iLCJ1c2VyX2FnZW50IjoiLSIsInNvdXJjZV9pcF9hZGRyZXNzIjoiMTAuMTg3LjcwLjEzMyIsIm90aGVyX2FkZGl0aW9uYWxfaW5mbyI6Int9In0=",
        "messageId": "1430458965141036376811744864924447649781668345309",
        "publishTime": "2022-11-13T13:15:09Z"
      },
      "deliveryAttempt": 1
    }
  ]
}
}

Response Elements

Response	유형	설명
ackId	String	메시지 요청 후 확인에 사용되는 ackIds 값
message	Object	메시지 상세값
data	String	이벤트 로그, Base64 인코딩 처리
messageId	String	메시지 고유 아이디
publishTime	String	메시지 게시 시각
deliveryAttempt	Integer	메시지 전송을 시도한 수

Status Code

HTTP Status	설명
200	성공
400	요청 정보 오류
401, 403	인증 실패, 권한 없음
404	서브스크립션을 찾을 수 없음

Acknowledge (확인 응답)

메시지가 정상적으로 수신된 경우, 확인 응답을 할 수 있습니다.

Request Syntax

메시지 확인 응답 Request Syntax
curl -k --location --request POST 'https://{endpoint-url}/pub-sub/kc-event/v1/projects/{project_id}/subscriptions/{subscription-name}/acknowledge' \
  --header "Credential-ID: ****" \
  --header "Credential-Secret: ****" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "ackIds": [
          "Ifaswn660rXu8FZdE2ki7upOjG4pI3Q3eaqNHJxIOXZ4Abj5VpCQRXm/EPoxDHTgImaXz8HK7P5l1rmhLoSJaf0Q330DO10BivvG+yt4sEGMGLc5wB4VKACuzGDTFOAyhFAkualNoKqZLyzQYAJuILZeZfO7BUBmmMkS3O+pZlMvxmthpyDrNnyUmLBb2uXlzig5kBWh0ZFWegioX7nLs/uODqMhlj2U2qEX6E33q0R9qEuJjv4HWEnVRjrTUdrRV6fiahbf7gnH68jN9f0+MisPBqPLzpQBj+eyqt2BZAq9J2cn70I5lzErIpxMBPXwfmM4sF7MhtyvaNvAbq9Sm02IVOIwxHDsoON/yjggIVeY5g+6XvKQgq5/jg=="
      ]
 }'

API 호출 방식

메서드	요청 URL
POST	`/pub-sub/kc-event/v1/projects/{project_id}/subscriptions/{subscription-name}/acknowledge`

Path	유형	필수 여부	설명
project_id	String	필수	KakaoCloud 프로젝트 이름(고유 ID) - 콘솔 상단에서 확인 가능
subscription-name	String	필수	서브스크립션의 이름

Request Header

Request	유형	필수 여부	설명
Credential-ID	String	필수	액세스 키 ID
Credential-Secret	String	필수	보안 액세스 키

Request Elements

Request	유형	설명
ackIds	string Array	메시지 요청 후 확인한 ackIds 값

Status Code

HTTP Status	설명
200	성공
400	요청 정보 오류
401, 403	인증 실패, 권한 없음
404	서브스크립션을 찾을 수 없음

서브스크립션 유형이 `Push`인 경우

서브스크립션 유형을 Push로 선택한 경우, 메시지를 수신하는 방법은 다음과 같습니다.

주요 개념

주요 개념	설명
서브스크립션 유형	Push: Pub/Sub에서 사용자가 설정한 Endpoint로 메시지 전송
엔드포인트 URL	토픽에 게시된 메시지를 받을 엔드포인트 서버 URL - PROTOCOL: HTTP/HTTPS - METHOD: POST
응답 대기 시간	메시지 확인 응답까지 대기하는 시간 - 시간 범위: 10-600초(10분) 이내 설정
확인 응답	- 응답 대기 시간 안에 사용자가 등록한 Endpoint에서 HTTP Response가 없는 경우, 메시지 재전송 - HTTP Response Status Code(102, 200, 201, 202, 204) 이외의 코드를 응답받을 경우, 즉시 메시지 재전송

서브스크립션 생성

Pub/Sub 서비스에서 서브스크립션 유형을 Push로 선택하여 서브스크립션을 생성합니다. 서브스크립션 생성에 대한 자세한 설명은 서브스크립션 생성을 참고하시기 바랍니다.

안내

Push 서브스크립션 유형을 사용하는 경우, 카카오클라우드 Public IP를 사용한 엔드포인트 URL로만 Message Push를 할 수 있습니다.

보안 그룹 설정하기

Push 유형의 서브스크립션을 사용하는 경우, 엔드포인트 서버에 메시지를 전송하기 위한 보안 그룹 설정이 필요합니다.

설정한 엔드포인트 URL에 연결된 자원의 보안 그룹에 인바운드 정책을 설정해야 합니다.
Any로 대역을 설정해도 Push를 할 수 있지만, 보안에 취약하기 때문에 Source IP를 지정하는 것을 권장합니다.

주의

보안을 위해 22, 1433, 1521, 3306, 3389, 6379, 27017 포트는 Push 엔드포인트로 설정할 수 없습니다.

안내

Default-Topic의 Push 서브스크립션을 사용하기 위한

kr-central-1 보안 그룹 오픈 Source IP 대역은 210.109.79.7 - 210.109.79.16입니다.
kr-central-2 보안 그룹 오픈 Source IP는 61.109.235.11입니다.

사용자 Topic의 Push 서브스크립션을 사용하기 위한

kr-central-1 보안 그룹 오픈 Source IP는 210.109.60.15, 210.109.60.92, 210.109.60.144, 210.109.61.176, 210.109.62.134입니다.
kr-central-2 보안 그룹 오픈 Source IP는 61.109.238.137, 61.109.238.107, 61.109.237.249, 61.109.238.114, 61.109.238.74, 61.109.236.65입니다.

보안 그룹에 대한 자세한 설명은 보안 그룹 생성 및 관리 문서를 참고하시기 바랍니다.

카카오클라우드 콘솔에서 VPC 메뉴를 선택합니다.
보안 그룹 메뉴를 클릭한 후, 인바운드 정책을 설정할 보안 그룹을 선택합니다.
- 단, 엔드포인트 URL에 연결된 자원의 보안 그룹을 선택해야 합니다.
인바운드 규칙 탭의 [인바운드 정책 관리] 버튼을 클릭한 후, 보안 그룹에 인바운드 정책을 설정합니다.

메시지 수신하기

토픽에 메시지가 게시되면 설정한 엔드포인트에 아래와 같은 포맷으로 메시지가 수신됩니다.

메시지 전송 포맷
"subscription": string
"messages": [
    {
        "message": {
            "data": string,
            "attributes": map[string][]string
            "messageId": string,
            "publishTime": time (RFC3339)
        }
    },
    {
        "message": {
            "data": string,
            "attributes": map[string][]string
            "messageId": string,
            "publishTime": time (RFC3339)
        }
    }
]

서브스크립션 유형이 Pull인 경우​

주요 개념​

서브스크립션 생성​

메시지 수신하기​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

Status Code​

Request Syntax​

API 호출 방식​

Request Header​

Request Elements​

Status Code​

서브스크립션 유형이 Push인 경우​

주요 개념​

서브스크립션 생성​

보안 그룹 설정하기​

메시지 수신하기​

서브스크립션 유형이 `Pull`인 경우

주요 개념

서브스크립션 생성

메시지 수신하기

Request Syntax

API 호출 방식

Request Header

Request Elements

Response Syntax

Response Elements

Status Code

Request Syntax

API 호출 방식

Request Header

Request Elements

Status Code

서브스크립션 유형이 `Push`인 경우

주요 개념

서브스크립션 생성

보안 그룹 설정하기

메시지 수신하기