PublishMessage ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

ポリシー アイコン

概要

PublishMessage ポリシーを使用すると、API プロキシフロー情報を Google Cloud Pub/Sub トピックにパブリッシュできます。Google の Pub/Sub により、サービスが非同期に通信でき、レイテンシが大幅に短縮されます。Pub/Sub の詳細については、Pub/Sub とはをご覧ください。Pub/Sub トピックにパブリッシュする情報には、リテラル テキストまたはフロー変数を使用できます。メッセージ テンプレートを使用して、リテラル テキストとフロー変数の組み合わせを指定することもできます。

パブリッシュ リクエストが成功すると、Apigee は publishmessage.message.id フロー変数を Pub/Sub サーバーによって返された値に設定します。詳細については、フロー変数をご覧ください。

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

認証とプロキシのデプロイ

PublishMessage ポリシーを実行するには、認証トークンが必要です。ただし、ポリシー定義に明示的な <Authentication> 要素はありません。Google 認証を使用するには API プロキシをデプロイする必要があります。これにより、リクエストに内部的に認証トークンが追加されます。Google 認証を使用する API プロキシをデプロイする方法については、デプロイ手順をご覧ください。API プロキシで Google 認証を使用する以外に、pubsub.topics.publish 権限を持つロールを持つサービス アカウントを使用して API プロキシをデプロイする必要があります。Pub/Sub の Identity and Access Management（IAM）のロールの詳細については、権限とロールをご覧ください。

<PublishMessage>

PublishMessage ポリシーを指定します。

デフォルト値 なし
必須かどうか 必須
型 複合型
親要素 なし
子要素 <CloudPubSub>
<DisplayName>
<Source>

次の表は、<PublishMessage> の子要素の概要をまとめたものです。

子要素 必須かどうか 説明
<CloudPubSub> 必須 <Topic> の親要素。<Topic> 要素は、メッセージをパブリッシュする Pub/Sub トピックを指定します。
<DisplayName> 省略可 ポリシーのカスタム名。
<IgnoreUnresolvedVariables> 省略可 Apigee が未解決の変数を検出した場合に、処理を停止するかどうかを指定します。
<Source> 必須 パブリッシュするメッセージを指定します。
その他の子要素
<Topic> 必須 メッセージのパブリッシュ先の Pub/Sub トピックを指定します。

<PublishMessage> 要素の構文は次のとおりです。

構文

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1">
    <DisplayName>DISPLAY_NAME</DisplayName>
    <Source>SOURCE_VALUE</Source>
    <CloudPubSub>
        <Topic>TOPIC_NAME</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PublishMessage>

例

次の例は、<PublishMessage> ポリシーの定義を示しています。

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>{flow-variable-1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

この要素には、すべてのポリシーに共通する次の属性があります。

属性 デフォルト 必須かどうか 説明
name なし 必須

ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。

管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError false 省略可 ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<PublishMessage> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値 なし
必須かどうか 省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
型 文字列
親要素 <PolicyElement>
子要素 なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<Source>

パブリッシュするメッセージを指定します。

メッセージには、リテラル テキストやフロー変数を使用することも、メッセージ テンプレートで両方の組み合わせを使用することもできます。

デフォルト値 なし
必須かどうか 必須
型 文字列
親要素 <PublishMessage>
子要素 なし

<Source> 要素の構文は次のとおりです。

構文

 <Source>SOURCE</Source>

例 1

次の例では、ソース メッセージを flow-var-1 フロー変数の値に設定しています。

<Source>{flow-var-1}</Source>

例 2

次の例では、ソース メッセージを source-message-text-01 に設定しています。

<Source>source-message-text-01</Source>

<CloudPubSub>

<Topic> の親要素。

1 つの Pub/Sub トピックにのみパブリッシュできます。そのため、<CloudPubSub> 要素に含めることができる <Topic> 要素は 1 つだけです。

デフォルト値 なし
必須かどうか 必須
型 複合型
親要素 <PublishMessage>
子要素 <Topic>

<CloudPubSub> 要素の構文は次のとおりです。

構文

<CloudPubSub>
  <Topic>TOPIC_NAME</Topic>
</CloudPubSub>

例

次の例は、<CloudPubSub> 要素の宣言を示しています。

<CloudPubSub>
  <Topic>projects/{request.header.project}/topics/{request.header.topic}</Topic>
</CloudPubSub>

<Topic>

<Source> メッセージをパブリッシュする Pub/Sub トピックを指定します。

トピック名は projects/project-id/topics/topic-name 形式で指定する必要があります。

デフォルト値 なし
必須かどうか 必須
型 複合型
親要素 <CloudPubSub>
子要素 なし

<Topic> 要素の構文は次のとおりです。

構文
<Topic>TOPIC_NAME</Topic>
例

次の例では、パブリッシュ先の Pub/Sub トピックを指定しています。

<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>

この例では、project-id-marketing は Google Cloud プロジェクト ID で、topic-name-test1 は <Source> メッセージがパブリッシュされるトピックです。

<IgnoreUnresolvedVariables>

Apigee が未解決の変数を検出した場合に、処理を停止するかどうかを指定します。

デフォルト値 いいえ
必須かどうか 省略可
型 ブール値
親要素 <PublishMessage>
子要素 なし

未解決の変数を無視して処理を続行するには、値を true に設定します。それ以外の場合は false に設定します。デフォルト値は false です。

<IgnoreUnresolvedVariables> を true に設定することは、<PublishMessage> の continueOnError を true に設定することとは異なります。continueOnError を true に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

構文

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

例

次の例では、<IgnoreUnresolvedVariables> を true に設定します。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

フロー変数

フロー変数は、特定のデータを保持するオブジェクトで、API プロキシフローのコンテキストで使用できます。これらの変数には、ペイロード情報、URL パス、IP アドレス、ポリシー実行のデータなどの情報が保持されます。フロー変数の詳細については、フロー変数の使用をご覧ください。

PublishMessage ポリシーが正常に Pub/Sub トピックにパブリッシュされると、Apigee は publishmessage.message.id フロー変数を Pub/Sub サーバーによって返された messageId に設定します。フロー変数は string 型で、プロキシ リクエスト フロー以降で使用できます。必要に応じて、他のダウンストリーム ポリシーでフロー変数を使用できます。ただし、パブリッシュが失敗した場合、Apigee は publishmessage.message.id 変数を設定しません。この変数にアクセスすると、エラーが発生します。

さまざまなタイプのフロー変数の詳細については、フロー変数のリファレンスをご覧ください。

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因
steps.publishmessage.PermissionDeniedError 500 このエラーは、ランタイム サービス アカウントがプロキシ サービス アカウントの権限を借用できないか、プロキシ サービス アカウントにトピックへのパブリッシュ権限がない場合に発生します。
steps.publishmessage.ExecutionError 500 このエラーは、Pub/Sub へのメッセージのパブリッシュ中に予期しないエラーが発生した場合に発生します。エラーの詳細はエラー メッセージで確認できます。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラー メッセージが生成されます。これらのエラー メッセージはエラー レスポンスで確認できます。多くの場合、システムによって生成されたエラー メッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラー メッセージをカスタマイズして、より有用なメッセージにすることができます。

エラー メッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイム エラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

変数 説明 例
fault.name fault.name は、ランタイム エラーの表にある障害のいずれかに一致します。障害名は、障害コードの最後の部分です。 fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed POLICY_NAME は、障害が発生したポリシーのユーザー指定の名前です。 publishmessage.publish-message-1.failed = true
ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。