Pub/Sub API

안내

토픽, 서브스크립션의 생성/삭제는 카카오클라우드 콘솔에서만 가능합니다.

공통 에러 코드

Response Error Syntax

{
    "error": {
        "code": int,
        "message": string
    }
}

// Example
{
    "error": {
        "code": 3,
        "message": "you have passed an invalid ack ID to the service (ack_id=MTZBRklHTVZTREZTJEpTLkFQSQ==)"
    }
}

에러 메시지 및 트러블슈팅

Error Code	HTTP Code	응답 내용 및 해결 방법
3 (INVALID_ARGUMENT)	400	유효하지 않은 요청 The request is invalid; a required argument may be missing, exceeds limits, or has an invalid value. 해결 방법: 에러메시지 확인 후 요청 내용 재시도 권장
9 (FAILED_PRECONDITION)	400	사전 조건 실패 Something must be done in the system to allow this operation. 해결 방법: 요청 재확인 권장
7 (PERMISSION_DENIED)	403	권한 없음 The certification is invalid. 해결 방법: 권한 획득 후 재시도 권장
5 (NOT_FOUND)	404	토픽, 서브스크립션을 찾을 수 없음 The topic or subscription referenced has not been found. In the case of JSON requests, it may also happen if the URL path is not a correct REST path. For publish and pull operations, the propagation of an object creation may take a few seconds. 해결 방법: 리소스 생성 직후라면 재 요청 권장 또는 해당 토픽, 서브스크립션 생성 후 재시도 권장
13 (INTERNAL)	500	내부 서버 에러 This error indicates an internal server error; it should not occur. If this error occurs, please report to cloud support. The error should be transient. 해결 방법: 재시도 권장

Topic

토픽과 관련한 API는 다음과 같습니다.

토픽 목록 조회

프로젝트에 생성된 토픽의 목록을 가져옵니다.

API 호출 방식

메서드	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직의 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID

Request Header

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

Query Params

Request	유형	설명
pageSize	Integer	한 번에 조회할 목록 개수
pageToken	String	다음 목록을 불러오기 위한 변수

Response Syntax

토픽 목록 조회 Response Syntax

{
    "topics": [
        {
             object (Topic)
        }
    ],
    "nextPageToken": string
}

//object (Topic) Example
{
    "id": string,
    "name": string,
    "description": string,
    "domain": string,
    "project": string,
    "messageRetentionDuration": string,
    "subscriptionCount": integer,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명
topics	Object Array (Topic)	토픽 목록 및 정보
nextPageToken	String	다음 토픽을 가져오기 위한 토큰

Object Array (Topic)

Response	유형	설명	Output Only
id	String	토픽 ID	o
name	String	토픽 이름
설명	String	토픽 설명
domain	String	토픽이 포함된 조직 ID
project	String	토픽이 포함된 프로젝트 ID
messageRetentionDuration	String	토픽의 메시지 보존 기간
subscriptionCount	Integer	토픽에 연결된 서브스크립션의 개수	o
creator	String	생성자	o
createdAt	timestamp	생성시간	o

토픽 상세 조회

특정 토픽의 상세 정보를 조회합니다.

API 호출 방식

메서드	요청 URL
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직의 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
topic-name	String	필수	토픽 이름

Request Header

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

Response Syntax

토픽 상세 조회 Response Syntax

{
    "id": string,
    "name": string,
    "description": string,
    "domain": string,
    "project": string,
    "messageRetentionDuration": string,
    "subscriptionCount": integer,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명	Output Only
id	String	토픽 ID	o
name	String	토픽 이름
설명	String	토픽 설명
domain	String	토픽이 포함된 조직 ID
project	String	토픽이 포함된 프로젝트 ID
messageRetentionDuration	String	토픽의 메시지 보존기간
subscriptionCount	Integer	토픽에 연결된 서브스크립션의 개수	o
creator	String	생성자	o
createdAt	timestamp	생성시간	o

메시지 게시하기

토픽에 1개 이상의 메시지를 보냅니다.

Request Syntax

메시지 게시하기 Request Syntax

{
  "messages": [
    {
      "data": "message-1",
      "attributes": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "data": "message-2"
    }
  ]
}

API 호출 방식

메서드	요청 URL
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}/publish

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직의 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
topic-name	String	필수	토픽 이름

Request Header

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

Request Elements

Request	유형	필수 여부	설명
messages	Object Array	필수	토픽에 보낼 메시지 목록 - Max : 100
message.data	String	필수	메시지 내용 - 최대 용량: 1 MiB - data 혹은 attributes 중 하나는 포함되어야 함 ⚠️ 주의: Base64로 인코딩되어 있어야 합니다.
message.attributes	map [string : string]	필수	메시지 속성 - 최대 개수: 100개 - Key : 1~256 자 - Value : 1~1024 자 - Key,Value의 총 사이즈는 60KiB를 초과할 수 없습니다. ⚠️ 주의: kakaoc로 시작하는 키는 사용할 수 없습니다.

Response Syntax

메시지 게시하기 Response Syntax

{
    "messageIds": [
        string,
        string
    ]
}

Response Elements

Response	유형	설명
messageIds	string Array	메시지 별로 발급된 고유 ID

토픽 수정

토픽의 설명, 메시지 보존기간 등을 수정할 수 있습니다. 메시지 보존기간은 기존에 설정한 시간을 기준으로 연장만 할 수 있습니다. 사용자 생성 토픽은 7일까지, 디폴트 토픽은 31일까지 수정할 수 있습니다.

Request Syntax

토픽 수정 Request Syntax

{
  "topic": {
    "description": "topic description",
    "messageRetentionDuration": "604800s"
  },
  "updateMask": "messageRetentionDuration,description"
}

API 호출 방식

메서드	요청 URL
PATCH	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직의 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
topic-name	String	필수	토픽 이름

Request Header

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

Request Elements

Request	유형	필수 여부	설명
topic.description	String	필수	토픽에 대한 설명
topic.messageRetentionDuration	String	선택	메시지 보존기간 - 기존에 설정한 시간보다 길게만 수정 가능(seconds 기준)
updateMask	String	필수	업데이트할 목록 - 쉼표(,)로 구분

Response Syntax

토픽 수정 Response Syntax

{
        object (Topic) // 토픽 상세 정보
}


// object (Topic) Example
{
    "id": string,
    "name": string,
    "description": string,
    "domain": string,
    "project": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

필드	유형	설명	Output Only
id	String	토픽 ID	o
name	string (required)	토픽 이름
설명	String	토픽 설명
domain	String	토픽이 포함된 조직 ID
project	String	토픽이 포함된 프로젝트 ID
messageRetentionDuration	String	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	o
creator	String	생성자	o
createdAt	timestamp	생성시간	o

토픽의 서브스크립션 조회

토픽에 연결된 서브스크립션 목록을 조회합니다.

API 호출 방식

메서드	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}/subscriptions

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직의 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
topic-name	String	필수	토픽 이름

Request Header

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

Query Params

Request	유형	설명
pageSize	Integer	한 번에 조회할 목록 개수
pageToken	String	다음 목록을 불러오기 위한 변수

Response Syntax

토픽의 서브스크립션 조회 Response Syntax

{
    "subscriptions": [
        string
    ],
    "nextPageToken": string
}

Response Elements

Response	유형	설명
subscriptions	string Array	토픽에 연결된 서브스크립션 이름 목록
nextPageToken	String	다음 서브스크립션 목록을 가지고 오기 위한 토큰

Subscription

서브스크립션과 관련한 API는 다음과 같습니다.

서브스크립션 목록 조회

프로젝트에 생성된 서브스크립션들의 목록을 조회합니다.

API 호출 방식

메서드	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID

Request Header

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

Query Params

Request	유형	설명
pageSize	Integer	한 번에 조회할 목록 개수
pageToken	String	다음 목록을 불러오기 위한 변수

Response Syntax

서브스크립션 목록 조회 Response Syntax

{
    "subscriptions": [
        {
            Object (Subscription)
        }
    ],
    "nextPageToken": string
}

//Object (Subscription) Example
{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "pushConfig": {
        object (PushConfig)
    },
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명
subscriptions	Object Array (Subscription)	프로젝트에 생성된 서브스크립션의 목록
nextPageToken	String	다음 서브스크립션 목록을 가지고 오기 위한 토큰

Object Array

Response	유형	설명	Output Only
id	String	서브스크립션의 ID	o
name	String	서브스크립션의 이름
domain	String	서브스크립션이 연결된 도메인 이름
project	String	서브스크립션이 연결된 프로젝트 이름
topicId	String	서브스크립션이 연결된 토픽의 ID	o
topic	String	서브스크립션이 연결된 Topic 이름
ackDeadlineSeconds	int	Pub/Sub이 구독자에게 메시지를 재전송하기 전 대기하는 시간
messageRetentionDuration	String	서브스크립션의 메시지 보존기간
maxDeliveryAttempt	int	메시지 재전송 횟수 - -1(default): 무제한 - 1~100 범위에서 횟수 지정 가능
status	String	서브스크립션의 상태	o
pushConfig	Object (PushConfig)	Push 타입 서브스크립션의 엔드포인트 설정
creator	String	서브스크립션을 생성한 생성자	o
createdAt	timestamp	서브스크립션을 생성한 시간	o

PushConfig

{
    "pushEndpoint": string
    "pushBatchSize": int
}

Response	유형	설명
pushEndpoint	String	Endpoint URL (Push Subscription인 경우)
pushBatchSize	int	Push 서브스크립션의 메시지의 배치 사이즈 - Default: 1 - Max: 100

서브스크립션 상세 조회

특정 서브스크립션의 정보를 가져옵니다.

API 호출 방식

메서드	요청 URL
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션 이름

Request Header

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

Response Syntax

서브스크립션 상세 조회 Object (Subscription) Response Syntax

{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "pushConfig": {
        object (PushConfig)
    },
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명	Output Only
id	String	서브스크립션의 Id	o
name	String	서브스크립션의 이름
domain	String	서브스크립션이 연결된 Domain 이름
project	String	서브스크립션이 연결된 Project 이름
topicId	String	서브스크립션이 연결된 토픽의 ID	o
topic	String	서브스크립션이 연결된 토픽의 이름
ackDeadlineSeconds	int	Pub/Sub이 Subscriber에게 메시지를 재전송하기 전 대기하는 시간
messageRetentionDuration	String	서브스크립션의 메시지 보존기간
maxDeliveryAttempt	int	메시지 재전송 횟수 - -1(default): 무제한 - 1~100 범위에서 횟수 지정 가능
status	String	서브스크립션의 상태	o
pushConfig	Object (PushConfig)	Push 타입 서브스크립션의 엔드포인트 설정
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	o
creator	String	서브스크립션을 생성한 생성자	o
createdAt	timestamp	서브스크립션을 생성한 시간	o

pushConfig

PushConfig

{
    "pushEndpoint": string
    "pushBatchSize": int
}

Response	유형	설명
pushEndpoint	String	Endpoint URL (Push Subscription인 경우)
pushBatchSize	int	Push 서브스크립션의 메시지의 배치 사이즈 - Default: 1 - Max: 100

서브스크립션 수정(Patch)

서브스크립션의 설정값을 수정합니다.

API 호출 방식

메서드	URI
PATCH	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션의 이름

Request Header

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

Request Syntax

서브스크립션 수정 Object (Subscription) Request Syntax

{
  "subscription": {
    "pushConfig": {
      "pushEndpoint": "{엔드포인트 URL}"
    },
    "ackDeadlineSeconds": 30,
    "messageRetentionDuration": "604800s",
    "maxDeliveryAttempt": 5
  },
  "updateMask": "ackDeadlineSeconds,messageRetentionDuration,pushConfig.pushEndpoint,maxDeliveryAttempt"
}

Response	유형	필수 여부	설명
subscription.pushConfig	Object (PushConfig)	선택	엔드포인트 URL (Push Subscription인 경우)
subscription.ackDeadlineSeconds	int	선택	Pub/Sub이 Subscriber에게 메시지를 재전송하기 전 대기하는 시간 - Default: 30
subscription.messageRetentionDuration	String	선택	메시지 보존기간 - Default: 7d
subscription.maxDeliveryAttempt	int	선택	메시지 재전송 횟수 - Default: 무제한
updateMask	String	필수	업데이트할 목록 - 쉼표(,)로 구분

Response Syntax

서브스크립션 수정 Object (Subscription) Response Syntax

{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "pushConfig": {
        object (PushConfig)
    },
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명	Output Only
id	String	서브스크립션의 ID	o
name	String	서브스크립션의 이름
domain	String	서브스크립션이 연결된 도메인 이름
project	String	서브스크립션이 연결된 프로젝트 이름
topicId	String	서브스크립션이 연결된 토픽의 ID	o
topic	String	서브스크립션이 연결된 토픽 이름
ackDeadlineSeconds	int	Pub/Sub이 Subscriber에게 메시지를 재전송하기 전 대기하는 시간
messageRetentionDuration	String	서브스크립션의 메시지 보존기간
maxDeliveryAttempt	int	메시지 재전송 횟수 - -1(default): 무제한 - 1~100 범위에서 횟수 지정 가능
status	String	서브스크립션의 상태	o
pushConfig	Object (PushConfig)	Push 타입 서브스크립션의 엔드포인트 설정
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	o
creator	String	서브스크립션을 생성한 생성자	o
createdAt	timestamp	서브스크립션을 생성한 시간	o

PushConfig

{
    "pushEndpoint": string
    "pushBatchSize": int
}

Response	유형	설명
pushEndpoint	String	엔드포인트 URL (Push Subscription인 경우)
pushBatchSize	int	Push 서브스크립션의 메시지 배치 크기 - Default: 1 - Max: 100

메시지 Pull

메시지를 가져옵니다.

API 호출 방식

메서드	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/pull

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션의 이름

Request Header

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

Request Syntax

메시지 Pull Request Syntax

{
  "maxMessages": 1,
  "waitTime": "100ms"
}

Request	유형	필수 여부	설명
maxMessages	int	필수	가져올 메시지 개수 - Max : 100 ⚠️ 메시지 용량이 클 경우 waitTime 에 의해 설정한 메시지 개수보다 적은 양의 메시지를 받을 수 있습니다.
waitTime	string	선택	메시지 fetch wait-time - Default: 100ms - Max : 30s (seconds 단위 입력)

Response Syntax

메시지 Pull Response Syntax

{
    "receivedMessages": [
        {
            object (ReceivedMessage)
        }
    ]
}

//object (ReceivedMessage) Example
{
    "ackId": string,
    "message": {
        object (PubsubMessage)
    },
    "deliveryAttempt": int
}

//// object (PubsubMessage) Example
{
     "data": string,
     "attributes": {
         string: string
         ...
     },
     "messageId": string,
     "publishTime": string
 }

Response Elements

Response	유형
receivedMessages	Object Array (ReceivedMessage)

ReceivedMessage

Fields	유형	설명
ackId	String	메시지에 대한 특정 액션(acknowledge, modifyAckDeadline)을 수행할 수 있는 ID
message	Object (PubsubMessage)
deliveryAttempt	int	해당 메시지가 재전송된 횟수

Pubsub Message

Fields	유형	설명
data	String (required)	메시지의 본문 내용, 최대 1 MiB
attributes	map (key: string, value: string) (optional)	메시지의 속성, 최대 100개
messageId	String	고유 메시지 ID, Publish 요청 응답에 메시지 별로 발급되어 전달된 ID 값과 동일한 값
publishTime	String	메시지가 publish된 시간

메시지 수신 확인

메시지의 ackId를 사용하여 Acknowledgement 처리를 합니다.

API 호출 방식

메서드	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/acknowledge

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션의 이름

Request Header

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

Request Syntax

메시지 수신 확인 Request Syntax

{
  "ackIds": ["ack-id-1"]
}

Request	유형	필수 여부	설명
ackIds	String Array	필수	Acknowledgement 처리를 할 메시지의 ackId 목록

Response Syntax

메시지 수신 확인 Response Syntax

{
    "failure": [
        {
            object (FailedAckID)
        }
    ]
}

//object (FailedAckID) Example
{
     "ackID": string,
     "error": object (Error)
}

Response Elements

Response	유형
failure	object (FailedAckID)

object (FailedAckID)

Fields	유형	설명
ackID	String	기존 ack id
error	String	Object(Error), 에러코드와 설명

메시지 확인 기한 수정

메시지 확인 기한(Ack Deadline)을 연장하거나 단축할 수 있습니다. 성공 시 신규 Ack ID가 발급됩니다.

API 호출 방식

메서드	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/modifyAckDeadline

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션의 이름

Request Header

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

Request Syntax

메시지 수신 확인 수정 Request Syntax

{
  "ackIds": ["ack-id-1"],
  "action": "extend"
}

Request	유형	필수 여부	설명
ackIds	String Array	필수	메시지의 ackId 목록
action	String	필수	extend 또는 skip

Response Syntax

메시지 수신 확인 수정 Response Syntax

{
    "success": [
        {
            object (AckID)
        }
    ],
    "failure": [
        {
            object (FailedAckID)
        }
    ]
}

//object (AckID) Example
{
     "ackID": string,
     "reissuedAckID": string
 }

//object (FailedAckID) Example
{
     "ackID": string,
     "error": object (Error)
}

Response Elements

Response	유형	설명
success	object (AckID)	성공한 Ack ID 목록
failure	object (FailedAckID)	실패한 Ack ID 목록

object (AckID)

Fields	유형	설명
ackID	String	기존 Ack ID
reissuedAckID	String	변경된 Ack ID

object (FailedAckID)

Fields	유형	설명
ackID	String	기존 ack id
error	String	Object(Error), 에러 코드와 설명

메시지 시점 되돌리기(Seek)

서브스크립션을 특정 시간으로 다시 되돌리는 기능으로 되돌린 시점 이후의 모든 메시지를 다시 받아볼 수 있습니다.

API 호출 방식

메서드	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/seek

Path	유형	필수 여부	설명
domain-id	String	필수	프로젝트가 속한 조직 ID
project-id	String	필수	카카오클라우드의 프로젝트 ID
sub-name	String	필수	서브스크립션 이름

Request Header

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

Request Syntax

메시지 Seek Request Syntax

{
    "time": string
}

Request	유형	필수 여부	설명
time	String	필수	되돌릴 시간 - 형식: "2006-01-02T15:04:05+09:00", KST

Response Body

응답값은 없습니다.