このドキュメントでは、メッセージのパブリッシュについて説明します。
パブリッシャー アプリケーションによって、メッセージが作成され、トピックに送信されます。Pub/Sub では、既存のサブスクライバーに対して、メッセージの at-least-once 配信とベストエフォートの順序指定を実施しています。
パブリッシャー アプリケーションの一般的なフローは次のとおりです。
- データを含むメッセージを作成します。
- リクエストを 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 でエンコードされたメッセージ データの文字列
メッセージには、空でないデータ フィールドか、少なくとも 1 つの属性が含まれている必要があります。
リクエストが成功した場合のレスポンスは、メッセージ ID が含まれる JSON オブジェクトです。次の例は、メッセージ ID が含まれるレスポンスを示しています。
{ "messageIds": [ "19916711285", ] }
C++
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C++ の設定手順を実施してください。詳細については、Pub/Sub C++ API のリファレンス ドキュメントをご覧ください。
C#
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、Pub/Sub C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Go の設定手順を実施してください。詳細については、Pub/Sub Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、Pub/Sub Java 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 コンソールの トピック ページに移動します。
メッセージをパブリッシュするトピックをクリックします。
[トピックの詳細] ページで、[メッセージ] をクリックします。
[メッセージをパブリッシュ] をクリックします。
[メッセージ本文] フィールドにメッセージのデータを入力します。
[メッセージ属性] で [属性を追加する] をクリックします。
Key-Value ペアを入力します。
必要に応じて属性を追加します。
[公開] をクリックします。
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
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、Pub/Sub Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、Pub/Sub Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Python の設定手順を実施してください。詳細については、Pub/Sub Python API のリファレンス ドキュメントをご覧ください。
Ruby
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Ruby の設定手順を実施してください。詳細については、Pub/Sub Ruby API のリファレンス ドキュメントをご覧ください。
順序指定キーを使用してメッセージをパブリッシュする
サブスクライバー クライアント���メッセージを順に受信するには、順序指定キーを使用してメッセージをパブリッシュするようにパブリッシャー クライアントを構成する必要があります。
順序指定キーのコンセプトについては、順序指定メッセージをご覧ください。
パブリッシャー クライアントの順序付きメッセージに関する重要な考慮事項の一覧を以下に示します。
単一のパブリッシャー クライアントでの順序指定: 1 つのパブリッシャー クライアントが同じリージョンで同じ順序指定キーを使用してメッセージをパブリッシュすると、サブスクライバー クライアントはそれらのメッセージをパブリッシュされた順序で受信します。たとえば、パブリッシャー クライアントが順序指定キー A を使用してメッセージ 1、2、3 をパブリッシュする場合、サブスクライバー クライアントはこれらのメッセージを 1、2、3 の順序で受信します。
複数のパブリッシャー クライアントにわたる順序付け: サブスクライバー クライアントが受信するメッセージの順序は、複数のパブリッシャー クライアントが同じ順序指定キーを使用する場合でも、同じリージョンでパブリッシュされた順序と一致します。しかし、パブリッシャーのクライアント自体はこの順序を把握していません。
たとえば、パブリッシャー クライアント X と Y がそれぞれ順序指定キー A を使用してメッセージをパブリッシュし、X のメッセージが Y より前に Pub/Sub によって受信された場合、すべてのサブスクライバー クライアントは Y より前に X のメッセージを受信します。���なるパブリッシャー クライアント間での厳格なメッセージ順序が必要な場合、クライアントは同じ順序指定キーを持つメッセージを同時にパブリッシュしないように追加の調整メカニズムを実装する必要があります。たとえば、ロック サービスを使用すると、パブリッシュ中に順序指定キーの所有権を維持できます。
リージョン間での並べ替え: メッセージの順序指定は、同じリージョンにパブリッシュされたメッセージに対してのみ想定されます。そのため、パブリッシャー クライアントがロケーション サービス エンドポイントを使用して、同じ順序指定キーの同じリージョンにメッセージをパブリッシュするようにします。サブスクライバー クライアントは、これらのメッセージを順番に受信できます。
公開エラー:順序指定キーを使用したパブリッシュが失敗すると、パブリッシャー内の同じ順序指定キーのキューに入れられたメッセージが失敗し、この順序指定キーの今後のパブリッシュ リクエストも失敗します。このようなエラーが発生した場合は、順序指定キーを使用してパブリッシュを再開する必要があります。パブリッシュ オペレーションを再開する例については、順序指定キーを使用してリクエストを再試行するをご覧ください。
Google Cloud コンソール、Google Cloud CLI、Pub/Sub API、またはクライアント ライブラリを使用して、順序指定キーでメッセージをパブリッシュできます。
コンソール
属性付きのメッセージを公開するには、次の手順を行います。
Google Cloud コンソールの トピック ページに移動します。
メッセージをパブリッシュするトピックをクリックします。
[トピックの詳細] ページで、[メッセージ] をクリックします。
[メッセージをパブリッシュ] をクリックします。
[メッセージ本文] フィールドにメッセージのデータを入力します。
[メッセージの順序指定] フィールドに順序指定キーを入力します。
[発行] をクリックします。
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: 順序指定キーが含まれる文字列
メッセージには、空でないデータ フィールドか、少なくとも 1 つの属性が含まれている必要があります。
リクエストが成功した場合のレスポンスは、メッセージ ID が含まれる JSON オブジェクトです。次の例は、メッセージ ID が含まれるレスポンスを示しています。
{ "messageIds": [ "19916711285", ] }
C++
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C++ の設定手順を実施してください。詳細については、Pub/Sub C++ API のリファレンス ドキュメントをご覧ください。
C#
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、Pub/Sub C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Go の設定手順を実施してください。詳細については、Pub/Sub Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、Pub/Sub Java 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 リソースのロケーションの制限をご覧ください。
スキーマを使用してメッセージをパブリッシュするには、スキーマの概要をご覧ください。
高度な配信オプションを構成する方法については、以下をご覧ください。