Pub/Sub API

안내

토픽 생성, 토픽 삭제, 서브스크립션 생성, 서브스크립션 삭제 API는 kr-central-2에서만 지원합니다.

공통 에러 코드

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. 해결 방법: 재시도 권장
14 (UNAVAILABLE)	`503`	내부 서버 에러 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. 해결 방법: 재시도 권장

토픽

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

토픽 생성

지정한 이름으로 토픽을 생성합니다.

API 호출 방식

메서드	URI
PUT	`{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 Body

토픽 생성 Request Body
{
    "topic":{
        "description": "topic description",
        "messageRetentionDuration": "604800s"
    }
}

Response Elements

Request	유형	필수 여부	설명
description	string	선택	토픽 설명
messageRetentionDuration	string	선택	메시지 보존 기간 - Default: `604800s`(7d)

Response Body

토픽 생성 Response Body
{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

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

토픽 목록 조회

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

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	int	한 번에 조회할 목록 개수
pageToken	string	다음 목록을 불러오기 위한 변수

Response Body

토픽 목록 조회 Response Body
{
    "topics": [
        {
             object (Topic)
        }
    ],
    "nextPageToken": string
}

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

Response Elements

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

Object Array (Topic)

필드	유형	설명	Output Only
id	string	토픽 ID	O
domain	string	토픽이 포함된 조직 ID
project	string	토픽이 포함된 프로젝트 ID
name	string	토픽 이름
messageRetentionDuration	string	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	O
description	string	토픽 설명
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 Body

토픽 상세 조회 Response Body
{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

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

메시지 게시하기

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

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 Body

메시지 게시하기 Request Body
{
  "messages": [
    {
      "data": "66mU7Iuc7KeAIOqyjOyLnCDthYzsiqTtirjsnoXri4jri6Qu",
      "attributes": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "data": "message-2"
    }
  ]
}

Request Elements

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

Response Body

메시지 게시하기 Response Body
{
    "messageIds": [
        string,
        string
    ]
}

Response Elements

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

토픽 수정

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

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 Body

토픽 수정 Request Body
{
  "topic": {
    "description": "topic description",
    "messageRetentionDuration": "604800s"
  },
  "updateMask": "messageRetentionDuration,description"
}

Request Elements

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

Response Body

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


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

Response Elements

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

토픽 삭제

지정한 이름의 토픽을 삭제합니다.

주의

토픽 삭제 시 하위 서브스크립션이 함께 삭제됩니다.

API 호출 방식

메서드	URI
DELETE	`{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	필수	보안 액세스 키

토픽의 서브스크립션 조회

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

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	int	한 번에 조회할 목록 개수
pageToken	string	다음 목록을 불러오기 위한 변수

Response Body

토픽의 서브스크립션 조회 Response Body
{
    "subscriptions": [
        string
    ],
    "nextPageToken": string
}

Response Elements

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

서브스크립션

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

서브스크립션 생성

지정한 이름으로 서브스크립션을 생성합니다.

API 호출 방식

메서드	URI
PUT	`{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 Body

서브스크립션 생성 Request Body
{
    "subscription":{
        "topic": "topic-1",
        //Push 유형의 서브스크립션 생성 시
        "pushConfig": {
            object (PushConfig)
        },
        // Object storage 유형의 서브스크립션 생성 시
        "objectStorageConfig": {
            object (ObjectStorageConfig)
        },
        "ackDeadlineSeconds": 30,
        "messageRetentionDuration": "604800s",
        "maxDeliveryAttempt": 1
    }
}

Request Elements

Request	유형	필수 여부	설명
subscription.topic	string	필수	연결할 토픽의 이름
subscription.pushConfig	Object (PushConfig)	선택	PushSubscription의 정보 - Endpoint Message : Object (PushEndpointMessage) - 만약 endpoint를 설정하지 않는다면 해당 서브스크립션은 Pull 유형의 서브스크립션으로 생성됨
subscription.objectStorageConfig	Object (ObjectStorageConfig)	선택	ObjectStorageSubscription의 정보 - pushConfig와 동시에 사용할 수 없음
subscription.messageRetentionDuration	int	선택	메시지 보존기간 - Default: 토픽의 messageRetentionDuration(seconds 단위 입력)
subscription.maxDeliveryAttempt	string	선택	메시지 재전송 횟수 - Default: `-1` (무제한)
subscription.ackDeadlineSeconds	int	선택	Pub/Sub이 Subscriber에게 메시지를 재전송 하기 전 대기하는 시간 - Default : `10s` (seconds 기준) - 만약, subscriber가 메시지를 수신한 뒤 ackDeadline 안에 acknowledge를 Pub/Sub에 요청하지 않으면 해당 메시지는 재전송됨

PushConfig

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

필드	유형	설명
pushEndpoint	string	Endpoint URL (*Push Subscription인 경우에만 해당)
pushBatchSize	int	Push 서브스크립션의 메시지 배치 사이즈 - Default: `1` - Max: `100`

ObjectStorageConfig

ObjectStorageConfig
{
    "bucket": string,
    "exportIntervalMinutes": int,
    "filePrefix": string,
    "fileSuffix": string,
    "channelCount": int,
    "maxChannelCount": int,
    "isExportEnabled": bool
}

필드	유형	설명	Output Only
bucket	string	Object Storage 버킷 이름
exportIntervalMinutes	int	Object Storage에 파일을 저장하는 주기
filePrefix	string	Object Storage에 저장되는 파일의 Prefix - 일부 특수문자(\ : * ? ” < > \|) 및 Prefix 맨 앞에 슬래시('/') 입력 불가 - 연속된 슬래시('//') 입력 불가 - Prefix 와 Suffix 합이 200bytes를 넘을 수 없음
fileSuffix	string	Object Storage에 저장되는 파일의 Suffix - 일부 특수문자(\ : * ? ” < > \|) 입력 불가 - 연속된 슬래시('//') 입력 불가
channelCount	int	설정된 내보내기 채널 개수
maxChannelCount	int	최대 생성 가능한 채널 개수 * Subscription Get 요청 시에만 출력됨 (List 조회 시 출력 안됨)	O
isExportEnabled	bool	내보내기 활성화 여부	O

Response Body

서브스크립션 생성 Response Body
{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

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

서브스크립션 목록 조회

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

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	int	한 번에 조회할 목록 개수
pageToken	string	다음 목록을 불러오기 위한 변수

Response Body

서브스크립션 목록 조회 Response Body
{
    "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,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

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

Object Array (Subscription)

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

서브스크립션 상세 조회

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

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 Body

서브스크립션 상세 조회 Object (Subscription) Response Body
{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

필드	유형	설명	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
subscriptionType	string	서브스크립션의 유형 - PULL, PUSH, OBJECT_STORAGE	O
pushConfig	Object (PushConfig)	Push 타입 서브스크립션의 엔드포인트 설정
objectStorageConfig	Object (ObjectStorageConfig)	Object Storage 서브스크립션 유형의 속성 설정
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	O
creator	string	서브스크립션을 생성한 생성자	O
createdAt	timestamp	서브스크립션을 생성한 시간	O

서브스크립션 수정(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 Body

서브스크립션 수정 Object (Subscription) Request Body
{
    "subscription":{
        "pushConfig": {
            Object (PushConfig)
        },
         "objectStorageConfig": {
            Object (ObjectStorageConfig)
        },
        "ackDeadlineSeconds": 30,
        "messageRetentionDuration": "604800s",
        "maxDeliveryAttempt": 5
    },
    "updateMask": "ackDeadlineSeconds,messageRetentionDuration,pushConfig.pushEndpoint,maxDeliveryAttempt"
}

필드	유형	필수 여부	설명
subscription.pushConfig	Object (PushConfig)	선택	엔드포인트 URL (Push Subscription인 경우)
subscription.objectStorageConfig	Object (ObjectStorageConfig)	선택	버킷 정보 등 (Object Storage 서브스크립션 유형인 경우)
subscription.ackDeadlineSeconds	int	선택	Pub/Sub이 Subscriber에게 메시지를 재전송하기 전 대기하는 시간
subscription.messageRetentionDuration	string	선택	메시지 보존기간
subscription.maxDeliveryAttempt	int	선택	메시지 재전송 횟수
updateMask	string	필수	업데이트할 목록 - 쉼표(`,`)로 구분

Response Body

서브스크립션 수정 Object (Subscription) Response Body
{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

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

서브스크립션 삭제

지정한 이름의 서브스크립션을 삭제합니다.

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

메시지 수신 Pull

메시지를 가져옵니다.(*서브스크립션이 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 Body

메시지 Pull Request Body
{
  "maxMessages": 1,
  "waitTime": "100ms"
}

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

Response Body

메시지 Pull Response Body
{
    "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

필드	유형
receivedMessages	Object Array (ReceivedMessage)

ReceivedMessage

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

PubsubMessage

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

메시지 수신 확인

메시지의 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 Body

 메시지 수신 확인 Request Body
{
  "ackIds": ["ack-id-1"]
}

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

Response Body

 메시지 수신 확인 Response Body
{
    "failure": [
        {
            object (FailedAckID)
        }
    ]
}

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

Response Elements

Response	유형
failure	Object (FailedAckID)

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 Body

 메시지 수신 확인 수정 Request Body
{
  "ackIds": ["ack-id-1"],
  "action": "extend"
}

Request	유형	필수 여부	설명
ackIds	string Array	필수	메시지의 ackId 목록
action	string	필수	extend 또는 skip - `Extend`: 메시지의 사용 시간을 현시점부터 서브스크립션의 AckDeadline 시간만큼 연장 - `Skip`: 메시지의 사용 시간을 0으로 설정하여 다른 클라이언트에서 메시지를 수신할 수 있도록 함

Response Body

 메시지 수신 확인 수정 Response Body
{
    "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 목록

AckID

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

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 Body

메시지 Seek Request Body
{
    "time": string
}

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

Response Body

응답값은 없습니다.

공통 에러 코드​

에러 메시지 및 문제 해결​

토픽​

토픽 생성​

API 호출 방식​

Request Header​

Request Body​

Response Elements​

Response Body​

Response Elements​

토픽 목록 조회​

API 호출 방식​

Request Header​

Query Params​

Response Body​

Response Elements​

Object Array (Topic)​

토픽 상세 조회​

API 호출 방식​

Request Header​

Response Body​

Response Elements​

메시지 게시하기​

API 호출 방식​

Request Header​

Request Body​

Request Elements​

Response Body​

Response Elements​

토픽 수정​

API 호출 방식​

Request Header​

Request Body​

Request Elements​

Response Body​

Response Elements​

토픽 삭제​

API 호출 방식​

Request Header​

토픽의 서브스크립션 조회​

API 호출 방식​

Request Header​

Query Params​

Response Body​

Response Elements​

서브스크립션​

서브스크립션 생성​

API 호출 방식​

Request Body​

Request Elements​

PushConfig​

ObjectStorageConfig​

Response Body​

Response Elements​

서브스크립션 목록 조회​

API 호출 방식​

Request Header​

Query Params​

Response Body​

Response Elements​

Object Array (Subscription)​

서브스크립션 상세 조회​

API 호출 방식​

Request Header​

Response Body​

Response Elements​

서브스크립션 수정(Patch)​

API 호출 방식​

Request Header​

Request Body​

Response Body​

Response Elements​

서브스크립션 삭제​

메시지 수신 Pull​

API 호출 방식​

Request Header​

Request Body​

Response Body​

Response Elements​

ReceivedMessage​

공통 에러 코드

에러 메시지 및 문제 해결

토픽

토픽 생성

API 호출 방식

Request Header

Request Body

Response Elements

Response Body

Response Elements

토픽 목록 조회

API 호출 방식

Request Header

Query Params

Response Body

Response Elements

Object Array (Topic)

토픽 상세 조회

API 호출 방식

Request Header

Response Body

Response Elements

메시지 게시하기

API 호출 방식

Request Header

Request Body

Request Elements

Response Body

Response Elements

토픽 수정

API 호출 방식

Request Header

Request Body

Request Elements

Response Body

Response Elements

토픽 삭제

API 호출 방식

Request Header

토픽의 서브스크립션 조회

API 호출 방식

Request Header

Query Params

Response Body

Response Elements

서브스크립션

서브스크립션 생성

API 호출 방식

Request Body

Request Elements

PushConfig

ObjectStorageConfig

Response Body

Response Elements

서브스크립션 목록 조회

API 호출 방식

Request Header

Query Params

Response Body

Response Elements

Object Array (Subscription)

서브스크립션 상세 조회

API 호출 방식

Request Header

Response Body

Response Elements

서브스크립션 수정(Patch)

API 호출 방식

Request Header

Request Body

Response Body

Response Elements

서브스크립션 삭제

메시지 수신 Pull

API 호출 방식

Request Header

Request Body

Response Body

Response Elements

ReceivedMessage