このドキュメントでは、単一メッセージ変換(SMT)を使用して Pub/Sub サブスクリプションを作成する方法について説明します。
サブスクリプション SMT を使用すると、Pub/Sub 内でメッセージ データと属性を軽量に変更できます。この機能を使用すると、メッセージがサブスクライバー クライアントに配信される前に、データのクリーンアップ、フィルタリング、形式変換を行うことができます。
SMT を使用してサブスクリプションを作成するには、 Trusted Cloud コンソール、Google Cloud CLI、クライアント ライブラリ、または Pub/Sub API を使用します。
始める前に
Pub/Sub サービスとその用語について学習する。
SMT について学習する。
必要なロールと権限
SMT を使用してサブスクリプションを作成するために必要な権限を取得するには、プロジェクトに対する Pub/Sub 編集者 (roles/pubsub.editor
)IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
この事前定義ロールには、SMT を使用してサブスクリプションを作成するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
SMT を使用してサブスクリプションを作成するには、次の権限が必要です。
-
プロジェクトに対するサブスクリプションの作成権限を付与します。
pubsub.subscriptions.create
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
定期購入の種類によっては、追加の権限が必要になる場合があります。権限の正確なリストについては、特定のサブスクリプションの作成について説明しているドキュメントをご覧ください。たとえば、SMT を使用して BigQuery サブスクリプションを作成する場合は、BigQuery サブスクリプションを作成するをご覧ください。
トピックとは異なるプロジェクトにサブスクリプションを作成する場合は、トピックを含むプロジェクトで、サブスクリプションを含むプロジェクトのプリンシパルに roles/pubsub.subscriber
ロールを付与する必要があります。
アクセス制御は、プロジェクト レベルと個々のリソースレベルで構成できます。
SMT を使用してサブスクリプションを作成する
SMT を使用してサブスクリプションを作成する前に、サブスクリプションのプロパティのドキュメントを確認してください。
次のサンプルでは、このユーザー定義関数(UDF)SMT を使用してサブスクリプションを作成することを前提としています。UDF の詳細については、UDF の概要をご覧ください。
function redactSSN(message, metadata) {
const data = JSON.parse(message.data);
delete data['ssn'];
message.data = JSON.stringify(data);
return message;
}
コンソール
Trusted Cloud コンソールで、Pub/Sub の [サブスクリプション] ページに移動します。
-
[サブスクリプションを作成] をクリックします。
[サブスクリプションの作成] ページが開きます。
-
[サブスクリプション ID] フィールドに、サブスクリプションの ID を入力します。サブスクリプションの命名の詳細については、命名ガイドラインをご覧ください。
-
[変換] で、[変換を追加] をクリックします。
-
関数名を入力します。例:
redactSSN
。 -
サブスクリプションで SMT をすぐに使用しない場合は、[変換を無効にする] オプションをクリックします。これにより SMT は保存されますが、サブスクリプションを介してメッセージが流れても実行されません。
-
新しい変換を入力します。次に例を示します。
function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; }
-
Pub/Sub には、SMT を検証できる検証関数が用意されています。[検証] をクリックして変換を検証します。
-
別の変換を追加する場合は、[変換を追加] をクリックします。
- すべての SMT を特定の順序で並べるには、上矢印と下矢印を使用します。SMT を削除するには、削除ボタンをクリックします。
-
Pub/Sub には、サンプル メッセージで SMT を実行した結果を確認できるテスト関数が用意されています。SMT をテストするには、[変換をテスト] をクリックします。
-
[テスト変換] ウィンドウで、テストする関数を選択します。
-
[入力メッセージ] ウィンドウにサンプル メッセージを入力します。
-
メッセージ属性を追加する場合は、[属性を追加する] をクリックして、1 つ以上の Key-Value ペアを入力します。
-
[Test] をクリックします。メッセージに SMT を適用した結果が表示されます。
-
ウィンドウを閉じると、サンプル メッセージの SMT のテストが停止します。
-
[作成] をクリックしてサブスクリプションを作成します。
gcloud
-
In the Trusted Cloud console, activate Cloud Shell.
At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Pub/Sub には、SMT を検証できる検証関数が用意されています。
gcloud pubsub message-transforms validate
コマンドを実行します。gcloud pubsub message-transforms validate --message-transform-file=TRANSFORM_FILE
次のように置き換えます。
-
TRANSFORM_FILE: 単一の SMT を含む YAML または JSON ファイルへのパス。
YAML 変換ファイルの例を次に示します。
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
-
Pub/Sub には、サンプル メッセージで 1 つ以上の SMT を実行した結果を確認できるテスト関数が用意されています。
gcloud pubsub message-transforms test
コマンドを実行します。gcloud pubsub message-transforms test --message-transforms-file=TRANSFORMS_FILE --message=MESSAGE --attributes=ATTRIBUTES
次のように置き換えます。
-
TRANSFORMS_FILE: 1 つ以上の SMT を含む YAML または JSON ファイルのパス。
YAML 変換ファイルの例を次に示します。
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
MESSAGE: SMT をテストするメッセージ本文。
-
ATTRIBUTES: SMT をテストするメッセージ属性。
-
-
サブスクリプションを作成するには、
gcloud pubsub subscriptions create
コマンドを実行します。gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_NAME \ --message-transforms-file=TRANSFORMS_FILE
次のように置き換えます。
-
SUBSCRIPTION_ID: 作成するサブスクリプションの ID または名前。サブスクリプションの命名方法のガイドラインについては、リソース名をご覧ください。サブスクリプションの名前は変更できません。
-
TOPIC_NAME: サブスクライブするトピックの名前(
projects/PROJECT_ID/topics/TOPIC_ID
の形式)。 -
TRANSFORMS_FILE: 1 つ以上の SMT を含む YAML または JSON ファイルへのパス。
YAML 変換ファイルの例を次に示します。
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
Java
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Java 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Java API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境変数を s3nsapis.fr
に設定します。
Python
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Python 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Python API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境変数を s3nsapis.fr
に設定します。
Go
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Go 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Go API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN
環境変数を s3nsapis.fr
に設定します。
SMT と他のサブスクリプション機能の連携
サブスクリプションで SMT と Pub/Sub の組み込みフィルタの両方を使用している場合、フィルタは SMT の前に適用されます。このため、次の影響があります。
- SMT がメッセージ属性を変更した場合、Pub/Sub フィルタは新しい属性セットに適用されません。
- SMT は、Pub/Sub フィルタで除外されたメッセージには適用されません。
SMT でメッセージがフィルタリングされる場合は、サブスクリプション バックログのモニタリングへの影響に注意してください。サブスクリプションを Dataflow パイプラインにフィードする場合は、SMT を使用してメッセージをフィルタリングしないでください。Dataflow の自動スケーリングが中断されます。