Pub/Sub API v2

안내

Pub/Sub API v2는 기존 Pub/Sub API v1과 기능적으로 동일하며, API 규격 개선을 위해 신규 출시되었습니다. 신규 연동 시에는 v2 사용을 권장합니다.

공통 에러 코드

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}/v2/topics

Request Header

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

Request Body

토픽 생성 Request Body

{
    "name": "topic-1",
    "description": "topic description",
    "messageRetentionDuration": "604800s"
}

Request Elements

Request	유형	필수 여부	설명
name	string	필수	토픽 이름
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	O
project	string	토픽이 포함된 프로젝트 ID	O
name	string	토픽 이름
messageRetentionDuration	string	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	O
description	string	토픽 설명
creator	string	생성자	O
createdAt	timestamp	생성 시간	O

토픽 목록 조회

프로젝트에 생성된 토픽 목록을 조회합니다.

API 호출 방식

메서드	URI
GET	{endpoint-url}/v2/topics

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	O
project	string	토픽이 포함된 프로젝트 ID	O
name	string	토픽 이름
messageRetentionDuration	string	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	O
description	string	토픽 설명
creator	string	생성자	O
createdAt	timestamp	생성 시간	O

토픽 상세 조회

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

API 호출 방식

메서드	요청 URL
GET	{endpoint-url}/v2/topics/{topic-id}

Path	유형	필수 여부	설명
topic-id	string	필수	토픽 ID

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	O
project	string	토픽이 포함된 프로젝트 ID	O
name	string	토픽 이름
messageRetentionDuration	string	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	O
description	string	토픽 설명
creator	string	생성자	O
createdAt	timestamp	생성 시간	O

메시지 게시하기

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

API 호출 방식

메서드	요청 URL
POST	{endpoint-url}/v2/topics/{topic-id}/publish

Path	유형	필수 여부	설명
topic-id	string	필수	토픽 ID

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 bytes  ㄴ 영문, 숫자, 마침표(.), 언더바(_), 하이픈(-)만 사용 가능 - Value : 1~1024 bytes  ㄴ 문자 종류 제한 없음(단, 앞뒤 공백 및 개행 문자는 입력 불가) - Key,Value의 총 크기는 60KiB를 초과할 수 없습니다. ⚠️ 주의: kakaoc로 시작하는 키는 사용할 수 없습니다.

Response Body

메시지 게시하기 Response Body

{
    "messageIds": [
        string,
        string
    ]
}

Response Elements

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

토픽 수정

토픽의 설명, 메시지 보존 기간 등을 수정할 수 있습니다. 메시지 보존 기간은 기존에 설정한 시간을 기준으로 최대 7일까지 연장만 가능합니다.

API 호출 방식

메서드	요청 URL
PATCH	{endpoint-url}/v2/topics/{topic-id}

Path	유형	필수 여부	설명
topic-id	string	필수	토픽 ID

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	O
project	string	토픽이 포함된 프로젝트 ID	O
name	string	토픽 이름
messageRetentionDuration	string	토픽의 메시지 보존 기간
subscriptionCount	int	토픽에 연결된 서브스크립션의 개수	O
description	string	토픽 설명
creator	string	생성자	O
createdAt	timestamp	생성 시간	O

토픽 삭제

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

주의

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

API 호출 방식

메서드	URI
DELETE	{endpoint-url}/v2/topics/{topic-id}

Path	유형	필수 여부	설명
topic-id	string	필수	토픽 ID

Request Header

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

토픽의 서브스크립션 조회

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

API 호출 방식

메서드	URI
GET	{endpoint-url}/v2/topics/{topic-id}/subscriptions

Path	유형	필수 여부	설명
topic-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
}

Response Elements

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

서브스크립션

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

서브스크립션 생성

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

API 호출 방식

메서드	URI
PUT	{endpoint-url}/v2/subscriptions

Request Body

서브스크립션 생성 Request Body

{
    "name": "subscription-1",
    "topicId": "topic-id-1",
    //Push 유형의 서브스크립션 생성 시
    "pushConfig": {
        object (PushConfig)
    },
    // Object Storage 유형의 서브스크립션 생성 시
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
    "ackDeadlineSeconds": 30,
    "messageRetentionDuration": "604800s",
    "maxDeliveryAttempt": 1,
    "filter": "hasKey(\"region\")"
}

Request Elements

Request	유형	필수 여부	설명
name	string	필수	서브스크립션 이름
topicId	string	필수	연결할 토픽의 ID
pushConfig	Object (PushConfig)	선택	PushSubscription의 정보 - Endpoint Message : Object (PushEndpointMessage) - 만약 endpoint를 설정하지 않는다면 해당 서브스크립션은 Pull 유형의 서브스크립션으로 생성됨
objectStorageConfig	Object (ObjectStorageConfig)	선택	ObjectStorageSubscription의 정보 - pushConfig와 동시에 사용할 수 없음
messageRetentionDuration	int	선택	메시지 보존 기간 - Default: 토픽의 messageRetentionDuration(seconds 단위 입력)
maxDeliveryAttempt	string	선택	메시지 재전송 횟수 - Default: -1 (무제한)
ackDeadlineSeconds	int	선택	Pub/Sub이 Subscriber에게 메시지를 재전송하기 전 대기하는 시간 - Default: 10s(초 단위) - Subscriber가 메시지를 수신한 뒤 ackDeadline 안에 acknowledge를 Pub/Sub에 요청하지 않으면 해당 메시지가 재전송됨
filter	string	선택	수신할 메시지를 속성(attributes) 기준으로 선별하는 필터 구문 - hasKey, hasValue, hasPrefix 함수와 AND, OR, NOT 연산자로 구성 - 최대 길이: 256 bytes ⚠️ 주의: 서브스크립션 생성 시에만 설정 가능하며, 생성 후에는 수정할 수 없습니다.

PushConfig

PushConfig

{
    "pushEndpoint": string
    "pushBatchSize": int,
    "unwrapPayload": bool,
    "writeMetadata": bool
}

필드	유형	설명
pushEndpoint	string	Endpoint URL (*Push Subscription인 경우에만 해당)
pushBatchSize	int	Push 서브스크립션의 메시지 배치 사이즈 - Default: 1 - Max: 100
unwrapPayload	bool	메시지 래핑 해제 설정 여부 - Default: false
writeMetadata	bool	메타데이터 포함 여부 (*unwrapPayload가 true로 설정된 경우에만 true로 설정 가능) - Default: false

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)
    },
    "filter": string,
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	유형	설명	Output Only
id	string	서브스크립션 ID	O
name	string	서브스크립션의 이름
domain	string	서브스크립션이 연결된 Domain ID	O
project	string	서브스크립션이 연결된 Project ID	O
topicId	string	서브스크립션이 연결된 토픽의 ID
topic	string	서브스크립션이 연결된 토픽의 이름	O
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 서브스크립션 유형의 속성 설정
filter	string	수신할 메시지를 속성(attributes) 기준으로 선별하는 필터 구문 - 생성 시에만 설정 가능하며 이후 수정 불가
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	O
creator	string	서브스크립션을 생성한 생성자	O
createdAt	timestamp	서브스크립션을 생성한 시간	O

서브스크립션 목록 조회

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

API 호출 방식

메서드	URI
GET	{endpoint-url}/v2/subscriptions

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)
    },
    "filter": string,
    "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	O
project	string	서브스크립션이 연결된 프로젝트 ID	O
topicId	string	서브스크립션이 연결된 토픽의 ID
topic	string	서브스크립션이 연결된 Topic 이름	O
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 서브스크립션 유형의 속성 설정
filter	string	수신할 메시지를 속성(attributes) 기준으로 선별하는 필터 구문 - 생성 시에만 설정 가능하며 이후 수정 불가
creator	string	서브스크립션을 생성한 생성자	O
createdAt	timestamp	서브스크립션을 생성한 시간	O

서브스크립션 상세 조회

특정 서브스크립션의 정보를 조회합니다.

API 호출 방식

메서드	요청 URL
GET	{endpoint-url}/v2/subscriptions/{subscription-id}

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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)
    },
    "filter": string,
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

필드	유형	설명	Output Only
id	string	서브스크립션의 ID	o
name	string	서브스크립션의 이름
domain	string	서브스크립션이 연결된 Domain 이름	O
project	string	서브스크립션이 연결된 Project 이름	O
topicId	string	서브스크립션이 연결된 토픽의 ID
topic	string	서브스크립션이 연결된 토픽의 이름	O
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 서브스크립션 유형의 속성 설정
filter	string	수신할 메시지를 속성(attributes) 기준으로 선별하는 필터 구문 - 생성 시에만 설정 가능하며 이후 수정 불가
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	O
creator	string	서브스크립션을 생성한 생성자	O
createdAt	timestamp	서브스크립션을 생성한 시간	O

서브스크립션 수정(Patch)

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

API 호출 방식

메서드	URI
PATCH	{endpoint-url}/v2/subscriptions/{subscription-id}

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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)
    },
    "filter": string,
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

필드	유형	설명	Output Only
id	string	서브스크립션의 ID	O
name	string	서브스크립션의 이름
domain	string	서브스크립션이 연결된 도메인 ID	O
project	string	서브스크립션이 연결된 프로젝트 ID	O
topicId	string	서브스크립션이 연결된 토픽의 ID
topic	string	서브스크립션이 연결된 토픽 이름	O
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 서브스크립션 유형의 속성 설정
filter	string	수신할 메시지를 속성(attributes) 기준으로 선별하는 필터 구문 - 생성 시에만 설정 가능하며 이후 수정 불가
unprocessedMessageCount	int	서브스크립션의 현재 처리되지 않은 메시지 개수	O
creator	string	서브스크립션을 생성한 생성자	O
createdAt	timestamp	서브스크립션을 생성한 시간	O

서브스크립션 삭제

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

메서드	URI
DELETE	{endpoint-url}/v2/subscriptions/{subscription-id}

메시지 수신 Pull

메시지를 가져옵니다. 서브스크립션이 Pull 유형인 경우에만 지원합니다.

API 호출 방식

메서드	URI
POST	{endpoint-url}/v2/subscriptions/{subscription-id}/pull

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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}/v2/subscriptions/{subscription-id}/acknowledge

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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}/v2/subscriptions/{subscription-id}/modifyAckDeadline

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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}/v2/subscriptions/{subscription-id}/seek

Path	유형	필수 여부	설명
subscription-id	string	필수	서브스크립션 ID

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

응답 값은 없습니다.