이 문서에서는 메시지 게시에 관한 정보를 제공합니다.
게시자 애플리케이션이 메시지를 만들어 주제로 전송합니다. Pub/Sub에서는 기존 구독자에 최소 1회 메시지 전송 및 최선의 순서 지정을 제공합니다.
게시자 애플리케이션의 일반적인 흐름은 다음과 같습니다.
- 사용자 데이터를 포함하는 메시지를 생성합니다.
- 지정된 주제에 메시지를 게시하려면 Pub/Sub 서버에 요청을 보냅니다.
시작하기 전에
게시 워크플로를 구성하기 전에 다음 작업이 완료되어야 합니다.
- 게시 워크플로에 대해 알아보세요.
- 주제 만들기
- 구독 선택 및 만들기
필요한 역할
주제에 메시지를 게시하는 데 필요한 권한을 얻으려면 관리자에게 주제에 대한 Pub/Sub 게시자(roles/pubsub.publisher
) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
주제 및 구독을 만들거나 업데이트하려면 추가 권한이 필요합니다.
메시지 형식
메시지는 메시지 데이터 및 메타데이터가 있는 필드로 구성됩니다. 메시지에서 다음 중 하나 이상을 지정합니다.
Pub/Sub 서비스는 메시지에 다음 필드를 추가합니다.
- 주제에 고유한 메시지 ID
- Pub/Sub 서비스가 메시지를 수신하는 시점의 타임스탬프
메시지에 관한 자세한 내용은 메시지 형식을 참고하세요.
메시지 게시
Google Cloud 콘솔, Google Cloud CLI, Pub/Sub API, 클라이언트 라이브러리를 사용하여 메시지를 게시할 수 있습니다. 클라이언트 라이브러리는 메시지를 비동기식으로 게시할 수 있습니다.
다음 샘플은 주제에 메시지를 게시하는 방법을 보여줍니다.
콘솔
메시지를 게시하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 Pub/Sub 주제 페이지로 이동합니다.
주제 ID를 클릭합니다.
메시지 아래의 주제 세부정보 페이지에서 메시지 게시를 클릭합니다.
메시지 본문 필드에 메시지 데이터를 입력합니다.
게시를 클릭합니다.
gcloud
메시지를 게시하려면 gcloud pubsub topics publish 명령어를 사용합니다.
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
다음을 바꿉니다.
- TOPIC_ID: 주제의 ID
- MESSAGE_DATA: 메시지 데이터가 있는 문자열
- KEY: 메시지 속성의 키
- VALUE: 메시지 속성의 키 값
REST
메시지를 게시하려면 다음과 같이 POST 요청을 보내세요.
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
다음을 바꿉니다.
- PROJECT_ID: 주제가 있는 프로젝트의 프로젝트 ID
- TOPIC_ID: 주제의 ID
요청 본문에 다음 필드를 지정합니다.
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
다음을 바꿉니다.
- KEY: 메시지 속성의 키
- VALUE: 메시지 속성의 키 값
- MESSAGE_DATA: 메시지 데이터가 있는 base64로 인코딩된 문자열
메시지는 비어 있지 않은 데이터 필드 또는 하나 이상의 속성을 포함해야 합니다.
요청이 성공하면 응답은 메시지 ID가 있는 JSON 객체로 받습니다. 다음은 메시지 ID가 포함된 응답의 예시입니다.
{ "messageIds": [ "19916711285", ] }
C++
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요.
C#
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참조 문서를 확인하세요.
Go
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 참조하세요.
자바
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub 자바 API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
PHP
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 PHP 설정 안내를 따르세요. 자세한 내용은 Pub/Sub PHP API 참조 문서를 참조하세요.
Python
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참조 문서를 참조하세요.
Ruby
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Ruby API 참고 문서를 참조하세요.
메시지를 게시하면 Pub/Sub 서비스가 메시지 ID를 게시자에게 반환합니다.
속성을 사용하여 메시지 게시
Pub/Sub 메시지에 커스텀 속성을 메타데이터로 삽입할 수 있습니다. 속성은 우선순위, 원본, 대상과 같은 메시지에 대한 추가 정보를 제공하기 위해 사용됩니다. 속성은 또한 구독에서 메시지를 필터링하는 데 사용할 수 있습니다.
메시지에서 속성을 사용하려면 다음 가이드라인을 따르세요.
속성은 텍스트 문자열이나 바이트 문자열이 지원됩니다.
메시지당 최대 100개의 속성을 사용할 수 있습니다.
속성 키는
goog
로 시작하지 않아야 하고 256바이트를 초과하지 않아야 합니다.속성 값은 1,024바이트를 초과하지 않아야 합니다.
메시지 스키마는 다음과 같이 나타낼 수 있습니다.
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
게시 측 중복의 경우, 동일한 messageId
라도 동일한 클라이언트 측 원본 메시지에 대해 다른 publishTime
값을 보게 될 수 있습니다.
PubsubMessage
JSON 스키마는 REST 및 RPC 문서의 일부로 게시됩니다. 이벤트 타임스탬프에 커스텀 속성을 사용할 수 있습니다.
다음 샘플은 속성이 포함된 메시지를 주제에 게시하는 방법을 보여줍니다.
콘솔
속성이 포함된 메시지를 게시하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
메시지를 게시할 주제를 클릭합니다.
주제 세부정보 페이지에서 메시지를 클릭합니다.
메시지 게시를 클릭합니다.
메시지 본문 필드에 메시지 데이터를 입력합니다.
메시지 속성에서 속성 추가를 클릭합니다.
키-값 쌍을 입력합니다.
필요한 경우 속성을 더 추가합니다.
게시를 클릭합니다.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
C++
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요.
C#
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참조 문서를 확인하세요.
Go
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 참조하세요.
자바
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub 자바 API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
Python
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참조 문서를 참조하세요.
Ruby
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Ruby API 참고 문서를 참조하세요.
순서 키를 사용하여 메시지 게시
구독자 클라이언트에서 메시지를 순서대로 수신하려면 게시자 클라이언트가 순서 키로 메시지를 게시하도록 구성해야 합니다.
순서 키의 개념을 이해하려면 메시지 순서 지정을 참조하세요.
다음은 게시자 클라이언트의 순서가 지정된 메시징에 대한 주요 고려사항 목록입니다.
단일 게시자 클라이언트에서 순서 지정: 단일 게시자 클라이언트가 동일한 리전에서 동일한 순서 키로 메시지를 게시하면 구독자 클라이언트는 게시된 정확한 순서대로 메시지를 수신합니다. 예를 들어 게시자 클라이언트가 순서 키 A로 메시지 1, 2, 3을 게시하면 구독자 클라이언트는 1, 2, 3 순으로 메시지를 수신합니다.
여러 게시자 클라이언트 간 순서 지정: 여러 게시자 클라이언트가 동일한 순서 키를 사용하는 경우에도 구독자 클라이언트가 수신한 메시지의 순서는 동일한 리전에 게시된 순서와 일치합니다. 그러나 게시자 클라이언트 자체는 이 순서를 알지 못합니다.
예를 들어 게시자 클라이언트 X와 Y가 각각 순서 키 A로 메시지를 게시하고 Pub/Sub에서 X의 메시지를 Y보다 먼저 수신하면 모든 구독자 클라이언트는 X의 메시지를 Y보다 먼저 수신합니다. 여러 게시자 클라이언트에 엄격한 메시지 순서가 필요한 경우 해당 클라이언트는 동일한 순서 키로 메시지를 동시에 게시하지 않도록 추가 조정 메커니즘을 구현해야 합니다. 예를 들어 잠금 서비스는 게시 중 순서 키의 소유권을 유지하는 데 사용될 수 있습니다.
리전 간 순서 지정: 제공 순서 보장은 순서 키에 대한 게시가 동일한 리전에서 수행될 때만 적용됩니다. 게시자 애플리케이션이 동일한 순서 키를 사용해서 서로 다른 리전에 메시지를 게시하는 경우 이러한 게시 간에 순서를 적용할 수 없습니다. 구독자는 임의 리전에 연결할 수 있고 순서 보장이 계속 보존됩니다.
Google Cloud 내에서 애플리케이션을 실행할 때는 기본적으로 동일 리전의 Pub/Sub 엔드포인트에 연결됩니다. 따라서 Google Cloud 내의 단일 리전에서 애플리케이션을 실행하면 일반적으로 단일 리전과 상호작용하도록 보장됩니다.
Google Cloud 외부 또는 여러 리전에서 게시자 애플리케이션을 실행하는 경우 Pub/Sub 클라이언트를 구성할 때 위치별 엔드포인트를 사용하여 단일 리전에 연결하도록 보장할 수 있습니다. Pub/Sub의 모든 위치 엔드포인트는 단일 리전에 연결됩니다. 위치별 엔드포인트에 대한 자세한 내용은 Pub/Sub 엔드포인트를 참조하세요. Pub/Sub의 모든 위치별 엔드포인트 목록은 위치별 엔드포인트 목록을 참조하세요.
게시 실패: 순서 키로 게시가 실패하면 이 순서 키의 이후 게시 요청을 포함하여 물론 게시자의 동일 순서 키에 대해 큐에 추가된 메시지가 실패합니다. 이러한 오류가 발생하면 순서 키로 게시를 재개해야 합니다. 게시 작업을 재개하는 예시는 순서 키를 사용하여 요청 재시도를 참조하세요.
Google Cloud 콘솔, Google Cloud CLI, Pub/Sub API, 클라이언트 라이브러리를 사용하여 순서 키가 포함된 메시지를 게시할 수 있습니다.
콘솔
속성이 포함된 메시지를 게시하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
메시지를 게시할 주제를 클릭합니다.
주제 세부정보 페이지에서 메시지를 클릭합니다.
메시지 게시를 클릭합니다.
메시지 본문 필드에 메시지 데이터를 입력합니다.
메시지 순서 필드에서 순서 키를 입력합니다.
게시를 클릭합니다.
gcloud
순서 키가 포함된 메시지를 게시하려면 gcloud pubsub topics publish
명령어와 --ordering-key
플래그를 사용합니다.
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
다음을 바꿉니다.
- TOPIC_ID: 주제의 ID
- MESSAGE_DATA: 메시지 데이터가 있는 문자열
- ORDERING_KEY: 순서 키가 포함된 문자열
REST
순서 키가 있는 메시지를 게시하려면 다음과 같이 POST 요청을 보냅니다.
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
다음을 바꿉니다.
- PROJECT_ID: 주제가 있는 프로젝트의 프로젝트 ID
- TOPIC_ID: 주제의 ID
요청 본문에 다음 필드를 지정합니다.
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
다음을 바꿉니다.
- KEY: 메시지 속성의 키
- VALUE: 메시지 속성의 키 값
- MESSAGE_DATA: 메시지 데이터가 있는 base64로 인코딩된 문자열
- ORDERING_KEY: 순서 키가 포함된 문자열
메시지는 비어 있지 않은 데이터 필드 또는 하나 이상의 속성을 포함해야 합니다.
요청이 성공하면 응답은 메시지 ID가 있는 JSON 객체로 받습니다. 다음은 메시지 ID가 포함된 응답의 예시입니다.
{ "messageIds": [ "19916711285", ] }
C++
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요.
C#
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C# API 참조 문서를 확인하세요.
Go
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 참조하세요.
자바
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub 자바 API 참조 문서를 참조하세요.
Node.js
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Node.js API 참조 문서를 참조하세요.
Python
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참조 문서를 참조하세요.
Ruby
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Ruby API 참고 문서를 참조하세요.
게시자 모니터링
Cloud Monitoring은 주제를 모니터링하기 위한 여러 측정항목을 제공합니다.
주제를 모니터링하고 정상 게시자를 유지하려면 정상 게시자 유지를 참조하세요.
다음 단계
Pub/Sub에서 메시지 데이터를 저장하는 위치를 제한하려면 Pub/Sub 리소스 위치 제한을 참조하세요.
스키마를 사용하여 메시지를 게시하려면 스키마 개요를 참조하세요.
고급 전송 옵션을 구성하는 방법은 다음을 참조하세요.