ParseDialogflowRequest ポリシー

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

Apigee Edge のドキュメントはこちらをご覧ください。

概要

ParseDialogflowRequest ポリシーを使用すると、Dialogflow と Apigee を簡単に統合できます。詳細については、Apigee と Contact Center AI の統合をご覧ください。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

ParseDialogflowRequest ポリシーは、バックエンドシステムにリクエストデータを送信する前に、Dialogflow エージェントからの WebhookRequest を処理します。このポリシーは WebhookRequest から API 呼び出し全体で使用できるフロー変数にデータを抽出します。この変数は、後続のコールアウト、ルックアップ、またはオーケストレーションされたロジックで使用できます。このポリシーは、Dialogflow エージェントが従来のバックエンドシステムとやり取りする場合に特に便利です。エージェントのデータをバックエンドシステムに送信する前に、データを解析して、バックエンドシステムが使用できるようにそのデータを構造化できます。

バックエンドサービスインテグレータは、Dialogflow WebhookRequest の形式を理解することに時間を費やす必要はありません。すぐに使用できる ParseDialogflowRequest ポリシーで、リクエストデータをシームレスに処理します。

Apigee で Dialogflow エージェントの WebhookRequest にアクセスするには、エージェントの Webhook URL（フルフィルメント）を Apigee で構成した ProxyEndPoint に設定する必要があります。ProxyEndPoint は一般公開されている必要があります。詳しくは、Webhook サービスの要件をご覧ください。

注: ParseDialogflowRequest ポリシーは、Dialogflow リクエスト内の fulfillmentInfo.tag、sentimentAnalysisResult、sessionInfo オブジェクトのみを解析します。

`<ParseDialogflowRequest>`

ParseDialogflowRequest ポリシーを定義します。

デフォルト値	なし
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	`<DialogflowVersion>` `<DisplayName>` `<VariablePrefix>`

次の表に、ParseDialogflowRequest ポリシーに固有の子要素の概要を示します。

子要素	必須かどうか	説明
`<VariablePrefix>`	省略可	フロー変数のカスタム接頭辞を指定します。
`<DialogflowVersion>`	省略可	Dialogflow のバージョンを指定します。

例

次の例は、サンプル Webhook リクエスト、対応する ParseDialogflowRequest ポリシー、ポリシーの適用後に生成されたフロー変数を示しています。

構文

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="POLICY_NAME">
    <!-- The display name for this policy -->
    <DisplayName>DISPLAY_NAME</DisplayName>
    <!-- The optional prefix to be added to all variables created from the
         Dialogflow Webhook request. Note that all variables created from the
         WebhookRequest object will be within a container named
         "google.dialogflow" -->
    <VariablePrefix>CUSTOM_PREFIX</VariablePrefix>
    <!-- The version of Dialogflow for which this request policy is written up.
         This policy supports only the CX version. This element is optional and
         defaults to CX if unspecified -->
    <DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>
</ParseDialogflowRequest>

Webhook リクエスト

次の例は、Dialogflow エージェントからの Webhook リクエスト（JSON 形式）を示しています。

{
    "fulfillmentInfo": {
        "tag": "check-claim-status"
    },
    "sessionInfo": {
        "session": "projects/apigee-test/locations/global/agents/ea45003d-3f5c-46ba-ac6b-f4c6dc8db707/sessions/5ea2e8-7c1-cf4-2cf-8e4d89e72",
        "parameters": {
            "claimId": "1234",
            "policyId": "abcd"
        }
    },
    "sentimentAnalysisResult": {
      "score": -0.7,
      "magnitude": 0.7
  }
}

リクエストで構成できるさまざまなフィールドについては、WebhookRequest をご覧ください。

次のサンプルに移動して、ParseDialogflowRequest ポリシーの構成を確認します。

ParseDialogflowRequest ポリシー

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ParseDialogflowRequest continueOnError="false" enabled="true"
        name="DialogflowRequest-InsuranceAgent">
    <DisplayName>Insurance Agent Webhook Request Policy</DisplayName>
    <VariablePrefix>my-prefix</VariablePrefix>
    <DialogflowVersion>CX</DialogflowVersion>
</ParseDialogflowRequest>

次のサンプルに移動して、ポリシーによって作成されたフロー変数を確認します。

フロー変数

google.dialogflow.my-prefix.fulfillment.tag = "check-claim-status"
google.dialogflow.my-prefix.session.id = "5ea2e8-7c1-cf4-2cf-8e4d89e72"
google.dialogflow.my-prefix.session.project.id = "apigee-test"
google.dialogflow.my-prefix.session.agent.id = "ea45003d-3f5c-46ba-ac6b-f4c6dc8db707"
google.dialogflow.my-prefix.session.parameters.claimId = "1234"
google.dialogflow.my-prefix.session.parameters.policyId = "abcd"
google.dialogflow.my-prefix.sentimentAnalysisResultScore = -0.7
google.dialogflow.my-prefix.sentimentAnalysisResultMagnitude = 0.7

生成されたフロー変数はすべて、google.dialogflow で始まり、その後に <VariablePrefix> 要素で指定された接頭辞（my-prefix）が続きます。

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

属性	デフォルト	必須かどうか	説明
`name`	なし	必須	ポリシーの内部名。`name` 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
`continueOnError`	false	省略可	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`enabled`	true	省略可	ポリシーを適用するには、`true` に設定します。ポリシーを無効にするには、`false` に設定します。ポリシーがフローに接続されている場合でも適用されません。
`async`	false	非推奨	この属性は非推奨となりました。

子要素のリファレンス

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

`<DisplayName>`

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

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

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

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

構文

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

例

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

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

`<VariablePrefix>`

フロー変数のカスタム接頭辞を指定します。この要素で指定された値は、ParseDialogflowRequest ポリシーによって生成されたすべての変数名の前に付けられます。デフォルトでは、ポリシーによって生成されたすべての変数の先頭に google.dialogflow が付きます。VariablePrefix 要素を指定した場合、google.dialogflow の後にカスタム接頭辞が追加されます。そのため、変数名は google.dialogflow.CUSTOM_PREFIX で始まります。

VariablePrefix 要素を指定しない場合、変数名の先頭には google.dialogflow のみが付きます。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	`<ParseDialogflowRequest>`
子要素	なし

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

構文

<VariablePrefix>VARIABLE_PREFIX</VariablePrefix>

例

次の例では、VariablePrefix を my-prefix に設定しています。

<VariablePrefix>my-custom-prefix</VariablePrefix>

この構成により、すべての変数名は google.dialogflow.my-custom-prefix で始まります。

`<DialogflowVersion>`

Dialogflow のバージョンを指定します。ParseDialogflowRequest ポリシーは CX バージョンのみをサポートしています。ポリシーでこの要素を指定しないと、バージョンはデフォルトで CX になります。

デフォルト値	なし
必須かどうか	省略可
型	文字列
親要素	なし
子要素	なし

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

構文

<DialogflowVersion>DIALOGFLOW_VERSION</DialogflowVersion>

例

次の例では、DialogflowVersion を CX に設定します。

<DialogflowVersion>CX</DialogflowVersion>

エラーコード

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

ランタイムエラー

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

障害コード	HTTP ステータス	原因	修正
`steps.parsedialogflowrequest.InvalidSessionInfo`	`500`	このエラーは、Dialogflow リクエストに無効な sessionInfo.session フィールドがある場合に発生します。Webhook は、このフィールドを使用してセッションを識別します。サポートされているセッション形式については、SessionInfo クラスをご覧ください。
`steps.parsedialogflowrequest.MalformedInput`	`500`	このエラーは、このポリシーに提供された JSON が無効であるか、形式が正しくない場合に発生します。

デプロイエラー

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

エラー名	原因	修正
`UnsupportedOperation`	このエラーは、`DialogflowVersion` 要素でサポートされていない Dialogflow バージョンを指定した場合に発生します。ParseDialogflowRequest ポリシーは `CX` バージョンのみをサポートしています。

障害変数

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

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

次の表に、このポリシーに固有の障害変数を示します。

変数	説明	例
`fault.name="FAULT_NAME"`	`FAULT_NAME` は、ランタイムエラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	`fault.name Matches "UnresolvedVariable"`
`ParseDialogflowRequest.POLICY_NAME.failed`	`POLICY_NAME` は、障害が発生したポリシーのユーザー指定の名前です。	`ParseDialogflowRequest.My-Parse-Dialogflow-Req.failed = true`

ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

ParseDialogflowRequest ポリシー

概要

<ParseDialogflowRequest>

例

構文

Webhook リクエスト

ParseDialogflowRequest ポリシー

フロー変数

子要素のリファレンス

<DisplayName>

構文

例

<VariablePrefix>

構文

例

<DialogflowVersion>

構文

例

エラーコード

ランタイム エラー

デプロイエラー

障害変数

関連トピック

`<ParseDialogflowRequest>`

`<DisplayName>`

`<VariablePrefix>`

`<DialogflowVersion>`

ランタイムエラー