このページでは、フィルタを含む Pub/Sub サブスクリプションを作成する方法について説明します。
フィルタを含むサブスクリプションからメッセージを受信すると、フィルタに一致するメッセージのみを受信します。Pub/Sub サービスは、フィルタと一致しないメッセージに、自動的に確認応答します。メッセージは属性でフィルタできますが、メッセージ内のデータでフィルタすることはできません。
1 つのトピックに複数のサブスクリプションをアタッチできます。また、各サブスクリプションには異なるフィルタを設定できます。
たとえば、トピックが世界の異なるリージョンのニュースを受け取る場合は、特定のリージョンからのみ公開されるニュースでフィルタリングするようにサブスクリプションを構成できます。この構成では、トピックのメッセージ属性の一つがニュースをパブリッシュするリージョンに対応している状態にする必要があります。
フィルタを含むサブスクリプションからメッセージを受信した場合、Pub/Sub が自動的に確認応答するメッセージに対して送信メッセージ料金は発生しません。これらのメッセージに対しては、メッセージ配信料金とシーク関連のストレージ料金が発生します。
フィルタを含むサブスクリプションを作成する
pull サブスクリプションと push サブスクリプションにはフィルタを含めることができます。すべてのサブスクライバーは、StreamingPull API を使用するサブスクライバーを含む、フィルタを含むサブスクリプションからメッセージを受信できます。
Google Cloud コンソール、Google Cloud CLI、クライアント ライブラリ、または Pub/Sub API を使用して、フィルタを含むサブスクリプションを作成できます。
Console
フィルタを含む pull サブスクリプションを作成するには、次の手順に従います。
Google Cloud コンソールで、[サブスクリプション] ページに移動します。
[サブスクリプションを作成] をクリックします。
[サブスクリプション ID] を入力します。
プルダウン メニューからトピックを選択するか、作成します。サブスクリプションがトピックからメッセージを受信します。
[サブスクリプション フィルタ] セクションで、フィルタ式を入力します。
[作成] をクリックします。
フィルタを含む push サブスクリプションを作成するには、次の手順に従います。
Google Cloud コンソールで、[サブスクリプション] ページに移動します。
[サブスクリプションを作成] をクリックします。
[サブスクリプション ID] を入力します。
プルダウン メニューからトピックを選択するか、作成します。サブスクリプションがトピックからメッセージを受信します。
[配信タイプ] で [Push] をクリックします。
[エンドポイント URL] 欄に、push エンドポイントの URL を入力します。
[サブスクリプション フィルタ] セクションで、フィルタ式を入力します。
[作成] をクリックします。
gcloud
フィルタを含む pull サブスクリプションを作成するには、--message-filter
フラグを指定して gcloud pubsub subscriptions create
コマンドを使用します。
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
以下を置き換えます。
- SUBSCRIPTION_ID: 作成するサブスクリプションの ID
- TOPIC_ID: サブスクリプションに関連付けるトピックの ID
- FILTER: フィルタリング構文の式
フィルタを含む push サブスクリプションを作成するには、--push-endpoint
フラグと --message-filter
フラグを指定して、gcloud pubsub subscriptions create
コマンドを使用します。
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
以下を置き換えます。
- SUBSCRIPTION_ID: 作成するサブスクリプションの ID
- TOPIC_ID: サブスクリプションに関連付けるトピックの ID
- PUSH_ENDPOINT: push サブスクライバーが実行されるサーバーの URL
- FILTER: フィルタリング構文の式
REST
フィルタを含むサブスクリプションを作成するには、projects.subscriptions.create
メソッドを使用します。
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
以下を置き換えます。
- PROJECT_ID: サブスクリプションを作成するプロジェクトのプロジェクト ID
- SUBSCRIPTION_ID: 作成するサブスクリプションの ID
フィルタを含む pull サブスクリプションを作成するには、リクエスト本文にフィルタを指定します。
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
以下を置き換えます。
- PROJECT_ID: トピックが含まれるプロジェクトのプロジェクト ID
- TOPIC_ID: サブスクリプションに関連付けるトピックの ID
- FILTER: フィルタリング構文の式
フィルタを含む push サブスクリプションを作成するには、リクエスト本文に push エンドポイントとフィルタを指定します。
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
以下を置き換えます。
- PROJECT_ID: トピックが含まれるプロジェクトのプロジェクト ID
- TOPIC_ID: サブスクリプションに関連付けるトピックの ID
- PUSH_ENDPOINT: push サブスクライバーが実行されるサーバーの URL
- FILTER: フィルタリング構文の式
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 のリファレンス ドキュメントをご覧ください。
フィルタの最大長は 256 バイトです。フィルタは、サブスクリプションの不変のプロパティです。サブスクリプションを作成した後に、サブスクリプションを更新してフィルタを変更することはできません。
フィルタがバックログ指標に与える影響
作成したサブスクリプションをモニタリングするには、フィルタを使用してサブスクリプションをモニタリングするをご覧ください。
フィルタが有効になっている場合、バックログ指標にはフィルタに一致するメッセージのデータのみが含まれます。バックログ指標のリストを次に示します。
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
これらの指標の詳細については、Pub/Sub 指標のリストをご覧ください。
サブスクリプションのフィルタを更新する
既存のサブスクリプションのフィルタを更新することはできません。代わりに、この回避策に沿ってご対応ください。
フィルタを変更するサブスクリプションのスナップショットを作成します。
コンソールを使用してスナップショットを取得する方法の詳細については、スナップショットの作成を作成するをご覧ください。
新しいフィルタを使用して新しいサブスクリプションを作成します。
フィルタを含むサブスクリプションの作成の詳細については、フィルタを含むサブスクリプションを作成するをご覧ください。
Google Cloud コンソールで、[Pub/Sub サブスクリプション] ページに移動します。
作成したサブスクリプションをクリックします。
[サブスクリプションの詳細] ページで、[メッセージの再生] をクリックします。
シークするには、[スナップショットまで] をクリックします。
手順 1 で元のサブスクリプション用に作成したスナップショットを選択し、[シーク] をクリックします。
移行中にメッセージが失われることはありません。
新しいサブスクリプションを使用するよう、サブスクライバーを変更します。
この手順を完了したら、元のサブスクリプションを削除できます。
フィルタを作成する構文
メッセージをフィルタするには、属性を操作する式を記述します。属性のキーまたは値に一致する式を記述できます。attributes
の ID により、メッセージ内の属性が選択されます。
たとえば、次の表のフィルタは name
属性を選択します。
フィルタ | 説明 |
---|---|
attributes:name |
name 属性を含むメッセージ |
NOT attributes:name |
name 属性を含まないメッセージ |
attributes.name = "com" |
name 属性と com の値を含むメッセージ |
attributes.name != "com" |
name 属性と com の値を含まないメッセージ |
hasPrefix(attributes.name, "co") |
name 属性と co で始まる値を含むメッセージ |
NOT hasPrefix(attributes.name, "co") |
name 属性と、co で始まる値を含まないメッセージ |
フィルタ式の比較演算子
次の比較演算子を使用して属性をフィルタできます。
:
=
!=
:
演算子は、属性のリスト内のキーを一致させます。
attributes:KEY
等価演算子はキーと値に一致させます。値は文字列リテラルにする必要があります。
attributes.KEY = "VALUE"
等価演算子を含む式はキーで始まり、等価演算子はキーと値を比較する必要があります。
有効: フィルタでキーと値を比較している
attributes.name = "com"
無効: フィルタの左側が値である
"com" = attributes.name
無効: フィルタで 2 つのキーを比較している
attributes.name = attributes.website
キーと値は大文字と小文字が区別され、属性と正確に一致している必要があります。キーにハイフン、アンダースコア、英数字以外の文字が含まれている場合は、文字列リテラルを使用します。
attributes."iana.org/language_tag" = "en"
フィルタでバックスラッシュ、引用符、非出力文字を使用するには、文字列リテラル内の文字をエスケープします。文字列リテラル内で Unicode、16 進数、8 進数のエスケープ シーケンスを使用することもできます。
有効: フィルタで文字列リテラル内の文字をエスケープする
attributes:"\u307F\u3093\u306A"
無効: フィルタで文字列リテラルを使用せず文字をエスケープする
attributes:\u307F\u3093\u306A
フィルタ式のブール演算子
フィルタでブール演算子 AND
、NOT
、OR
を使用できます。演算子は大文字にする必要があります。たとえば、次のフィルタは iana.org/language_tag
属性を含むが、name
属性と com
値を含まないメッセージ用のものです。
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
NOT
演算子が最も優先されます。AND
演算子と OR
演算子を組み合わせるには、かっこを使用して式を完成させます。
有効: かっこを使用した
AND
演算子とOR
演算子attributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
無効: かっこを使用しない
AND
演算子とOR
演算子attributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
無効:
AND
演算子とOR
演算子による不完全な式の組み合わせattributes.name = "com" AND ("net" OR "org")
NOT
演算子の代わりに単項マイナス演算子を使用できます。
attributes.name = "com" AND -attributes:"iana.org/language_tag"
フィルタ式の関数
hasPrefix
関数を使用すると、部分文字列で始まる値を持つ属性をフィルタできます。フィルタでサポートされている関数は hasPrefix
のみです。
接頭辞の一致は hasPrefix
関数でサポートされていますが、一般的な正規表現はサポートされていません。
hasPrefix(attributes.KEY, "SUBSTRING")
次のように置き換えます。
- KEY: 属性名
- SUBSTRING: 値の部分文字列