ExtensionCallout ポリシー

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

拡張機能では、Apigee Edge 外部の特定のリソースへのアクセスが提供されます。このようなリソースには、Cloud StorageCloud 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 やアカウント名など、リソースへのアクセスを絞り込むのに必要な情報が含まれます。

要素リファレンス

<?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">
    

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

属性 説明 デフォルト 要否
name

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

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

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

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

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

たとえば、先行する <Input> ブロックを書き換えて、client.ip フロー変数を使用して 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> 属性

属性 説明 デフォルト 要否
parsed 拡張機能から返された JSON オブジェクトを解析することで、JSON オブジェクト内のデータに他のポリシーから変数としてアクセスできるようにします。 true 省略可

フロー変数

なし。

エラーコード

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

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

ランタイム エラー

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

エラー名 HTTP ステータス 原因
ExecutionFailed 未定 拡張機能がエラー レスポンスを返す。

デプロイエラー

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

エラー名 発生する状況
InvalidConnectorInstance 拡張機能のタグが空のままになっている。
ConnectorInstanceDoesNotExists 拡張機能のタグで指定されている拡張機能名が、API プロキシがデプロイされている環境に存在しない。
InvalidInput 入力タグの値が有効な JSON でない。
InvalidAction アクションタグが空のままになっている。