このドキュメントでは、メッセージのパブリッシュについて説明します。
パブリッシャー アプリケーションによって、メッセージが作成され、トピックに送信されます。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、クライアント ライブラリを使用してパブリッシュできます。クライアント ライブラリは、メッセージを非同期的にパブリッシュできます。
次のサンプルは、メッセージをトピックにパブリッシュする方法を示しています。
Console
メッセージをパブリッシュする手順は次のとおりです。
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 ドキュメントの一部としてパブリッシュされます。イベントのタイムスタンプにはカスタム属性を使用できます。
次のサンプルは、属性付きのメッセージをトピックにパブリッシュする方法を示しています。
Console
属性付きのメッセージをパブリッシュするには、次の手順を行います。
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 リファレンス ドキュメントをご覧ください。
順序指定キーを使用してメッセージをパブリッシュする
サブスクライバー クライアントでメッセージを順序どおりに受信するには、順序指定キーを使用してメッセージをパブリッシュするようにパブリッシャー クライアントを構成する必要があります。
順序指定キーのコンセプトについては、順序メッセージをご覧ください。
パブリッシャー クライアント向けの順序指定メッセージに関する主な考慮事項は次のとおりです。
単一のパブリッシャー クライアントでの順序指定: 単一のパブリッシャー クライアントが同じリージョンで同じ順序指定キーを使用してメッセージをパブリッシュすると、サブスクライバー クライアントはそれらのメッセージをパブリッシュされた順序どおりに受信します。たとえば、パブリッシャー クライアントが順序指定キー A を使用してメッセージ 1、2、3 をパブリッシュすると、サブスクライバー クライアントは 1、2、3 の順序で受信します。
複数のパブリッシャー クライアント間の順序指定: サブスクライバー クライアントが受信するメッセージの順序は、複数のパブリッシャー クライアントが同じ順序指定キーを使用している場合でも、同じリージョンでパブリッシュされた順序と一致します。ただし、パブリッシャー クライアント自身はこの順序を認識していません。
たとえば、パブリッシャー クライアント X と Y がそれぞれ順序指定キー A を使用してメッセージをパブリッシュし、X のメッセージが Y のメッセージより先に Pub/Sub によって受信された場合、すべてのサブスクライバー クライアントは 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、またはクライアント ライブラリを使用して、順序指定キーでパブリッシュできます。
Console
属性付きのメッセージをパブリッシュするには、次の手順を行います。
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 リソースのロケーションの制限をご覧ください。
スキーマを使用してメッセージをパブリッシュするには、スキーマの概要をご覧ください。
高度な配信オプションを構成する方法については、以下をご覧ください。