ExtensionCallout ポリシー

ExtensionCallout ポリシーを使用して、API プロキシに拡張機能を組み込みます。

拡張機能では、Apigee Edge 外部の特定のリソースへのアクセスが提供されます。このようなリソースには、Cloud Storage や Cloud Speech-to-Text などの Google Cloud Platform サービスを使用できます。また、HTTP や HTTPS 経由でアクセスできる外部リソースも使用できます。

拡張機能の概要については、拡張機能とはをご覧ください。入門チュートリアルについては、チュートリアル: 拡張機能の追加と使用をご覧ください。

ExtensionCallout ポリシーから拡張機能にアクセスする前に、Apigee Edge 組織にすでにインストールされている拡張機能パッケージから拡張機能を追加、構成、デプロイします。

サンプル

次に、Stackdriver Logging 拡張機能で使用できるポリシーの例を示します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>stackdriver-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>stackdriver-extension-example-log</Output>
</ConnectorCallout>

Stackdriver Logging 拡張機能の使用方法についての詳しいチュートリアルは、チュートリアル: 拡張機能の使用をご覧ください。

利用可能なすべての拡張機能の例については、拡張機能リファレンスの概要をご覧ください。

ExtensionCallout ポリシーについて

ExtensionCallout ポリシーは、構成済みの拡張機能を使用して API プロキシ内から外部リソースにアクセスする場合に使用します。

このポリシーを使用するには、まず以下が必要です。

• このポリシーからアクセスする外部リソースに関するいくつかの詳細情報。これらの詳細情報は、リソースに固有のものとなります。たとえば、ポリシーが Cloud Firestore データベースにアクセスする場合は、作成またはアクセスするコレクションやドキュメントの名前を認識しておく必要があります。一般に、リソース固有の情報は、このポリシーのリクエストとレスポンスの処理を構成する際に使用されます。
• API プロキシがデプロイされる環境に追加、構成、デプロイされている拡張機能。言い換えると、このポリシーを使用して特定の Google Cloud サービスにアクセスする場合は、そのサービス用にデプロイされた拡張機能が環境内に存在している必要があります。一般に、構成の詳細には、プロジェクト ID やアカウント名など、リソースへのアクセスを絞り込むのに必要な情報が含まれます。

PostClientFlow での ExtensionCallout ポリシーの使用

ExtensionCallout ポリシーは、API プロキシの PostClientFlow から呼び出すことが可能です。PostClientFlow は、レスポンスがリクエスト元のクライアントに送信された後に実行され、すべてのメトリクスがログに記録されるようにします。PostClientFlow の使用方法について詳しくは、API プロキシ構成リファレンスをご覧ください。

ExtensionCallout ポリシーを使用して PostClientFlow から Google Stackdriver Logging 拡張機能を呼び出す場合は、組織で features.allowExtensionsInPostClientFlow フラグが true に設定されていることを確認します。

• Apigee Edge for Public Cloud をご利用の場合は、Apigee サポートに連絡して、組織で features.allowExtensionsInPostClientFlow フラグが true に設定されていることを確認してください。

• Apigee Edge for Private Cloud をご利用の場合は、Update 組織プロパティ API を使用して features.allowExtensionsInPostClientFlow フラグを true に設定します。

PostClientFlow からの MessageLogging ポリシーの呼び出しに関するすべての制限は、ExtensionCallout ポリシーにも適用されます。詳細については、使用上の注意をご覧ください。

要素リファレンス

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<ConnectorCallout> の属性

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

<Action> 要素

ポリシーで呼び出す、拡張機能で公開されているアクション。

<Action>action-exposed-by-extension</Action>

• デフォルト: なし。
• 要否: 必須。
• 型: 文字列。

拡張機能はそれぞれ、独自のアクション セットを公開し、その拡張機能で示されるリソースの機能へのアクセスを提供します。アクションは、このポリシーで呼び出す関数であると考えることができます。この関数の呼び出しには、<Input> 要素のコンテンツを使用して引数を指定します。アクションのレスポンスは、<Output> 要素で指定した変数に保存されます。

拡張機能の関数の一覧については、このポリシーから呼び出す拡張機能のリファレンスをご覧ください。

<Connector> 要素

使用する構成済みの拡張機能名。これは、拡張機能の環境へのデプロイを構成したときに、拡張機能に命名された環境をスコープとする名前です。

<Connector>name-of-configured-extension</Connector>

• デフォルト: なし。
• 要否: 必須。
• 型: 文字列。

拡張機能は、同じ拡張機能パッケージに基づいてデプロイされていても、他の拡張機能とは構成値が異なる場合があります。このような構成値は、同じパッケージから構成された拡張機能であってもランタイムの機能が大きく異なる可能性があるため、呼び出す拡張機能は必ず正しく指定してください。

<Input> 要素

拡張機能に送信されるリクエスト本文を含む JSON。

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

• デフォルト: なし。
• 要否: 拡張機能に応じて、オプションまたは必須です。
• 型: 文字列。

これは基本的には <Action> 要素で指定したアクションに対する引数です。<Input> 要素の値は、呼び出す拡張機能とアクションによって異なります。各アクションのプロパティの詳細については、拡張機能パッケージのドキュメントをご覧ください。

<Input> 要素の値の多くは、<![CDATA[]]> セクションで囲まなくても正しく機能しますが、JSON のルールにより XML として値が解析されない場合もあります。ベスト プラクティスとして、JSON を CDATA セクションとして囲むと、ランタイムの解析エラーを回避できます。

<Input> 要素の値は、プロパティが拡張機能アクションに送信する値を指定する、適切な形式の JSON です。たとえば、Google Stackdriver Logging 拡張機能の log アクションは、書き込み先のログ（logName）、エントリに含めるメタデータ（metadata）、ログメッセージ（data）を指定する値を取得します。

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

<Input> JSON でのフロー変数の使用

<Input> のコンテンツがメッセージ テンプレートとして扱われます。このため、中かっこで囲まれた変数名がランタイム時に参照先変数の値に置き換えられます。

たとえば、client.ip フロー変数を使用するように上記の <Input> ブロックを書き換えて、API プロキシを呼び出すクライアントの IP アドレスを取得できます。

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

ランタイム時に JSON 内のプロパティ値を引用符で囲む場合は、必ず JSON コード内で引用符を使用してください。これは、ランタイム時に解決する JSON プロパティ値としてフロー変数を指定する場合も同様です。

次の <Input> の例には、2 つのフロー変数参照が含まれています。

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

ランタイム時に JSON プロパティ値は次のように解決されます。

• logName プロパティ値 - 文字列リテラル example-log。
• metadata プロパティ値 - 引用符の囲みなしの my.log.entry.metadata フロー変数値。これは、変数の値自体がオブジェクトを表す JSON である場合に役立つことがあります。
• message プロパティ値 - 引用符の囲みありの client.ip フロー変数値。

<Output> 要素

拡張機能のアクションのレスポンスを格納する変数名。

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

または

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

• デフォルト: なし。
• 要否: 拡張機能に応じて、オプションまたは必須です。
• 型: parsed 属性設定に応じて、解析されたオブジェクトまたは文字列。

レスポンスの受信時に、レスポンス値がここで指定する変数に格納され、他の API プロキシコードからアクセスできます。

拡張機能のレスポンス オブジェクトは JSON 形式です。ポリシーが JSON を処理する方法には次の 2 つのオプションがあります。

• 解析（デフォルト）: ポリシーによって JSON オブジェクトが解析され、JSON データで自動的に変数が生成されます。たとえば、JSON に "messageId" : 12345; を含めて、出力変数に extensionOutput という名前を付けると、変数 {extensionOutput.messageId} を使用して他のポリシーでそのメッセージ ID にアクセスできます。
• 未解析: 出力変数に、拡張機能からの未加工で未解析の JSON レスポンスが格納されます（必要に応じて、JavaScript ポリシーを使用して別の手順でレスポンス値を解析することもできます）。

<Output> 属性

フロー変数

なし。

エラーコード

Apigee Edge ポリシーから返されるエラーは、ポリシーエラー リファレンスに記載された一貫した形式に従います。

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

ランタイム エラー

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

デプロイエラー

このポリシーを含むプロキシのデプロイで、次のエラーが発生することがあります。