Webhook は、標準 Webhook またはフレキシブル Webhook のいずれかになります。標準 Webhook では、リクエスト フィールドとレスポンス フィールドは Dialogflow によって定義されます。フレキシブル Webhook では、リクエスト フィールドとレスポンス フィールドを自分で定義します。
標準 Webhook
標準 Webhook では、Dialogflow で定義されたリクエスト メッセージとレスポンス メッセージを使用します。リクエスト メッセージには、セッションに関する詳細情報が表示されます。たとえば、現在のアクティブなページ、最近一致したインテント、セッション パラメータ値、エージェント定義のレスポンスがすべて含まれています。
標準 Webhook リクエスト
Webhook でのフルフィルメントが呼び出されると、Dialogflow から Webhook サービスに HTTPS POST Webhook リクエストを送信します。このリクエストの本文は、セッションに関する情報を含む WebhookRequest JSON オブジェクトです。
一部の統合では、WebhookRequest.payload フィールドに追加情報が入力されます。たとえば、Dialogflow CX Phone Gateway の統合では、エンドユーザーの呼び出し元 ID を提供します。
詳しくは、WebhookRequest（V3）または WebhookRequest（V3Beta1）のリファレンス ドキュメントをご覧ください。
標準 Webhook レスポンス
Webhook サービスは Webhook リクエストを受け取ると、Webhook レスポンスを送信する必要があります。回答には次の制限が適用されます。
- レスポンスは、Webhook リソースを作成するときに構成したタイムアウト内で実行する必要があります。この制限時間を超えると、リクエストがタイムアウトになります。
- レスポンスのサイズは 64 KiB 以下でなければなりません。
詳しくは、WebhookResponse（V3）または WebhookResponse（V3Beta1）のリファレンス ドキュメントをご覧ください。
標準 Webhook リソース設定
標準 Webhook の Webhook リソース設定は次のとおりです。
| 用語 | 定義 |
|---|---|
| 表示名 | Webhook のコンソールに表示される名前。 |
| Webhook タイムアウト | Dialogflow が Webhook サービスに Webhook リクエストを送信する際、レスポンスの待機中にタイムアウトが発生することがあります。この設定では、タイムアウトを秒単位で制御します。タイムアウトが発生すると、Dialogflow によって webhook.error.timeout イベントが呼び出されます。 |
| 種類 | プライベート ネットワーク アクセスに Service Directory を使用する場合は「Service Directory」、それ以外の場合は「Generic Web Service」に設定します。 |
| Webhook URL | Webhook サービスの URL アドレスを指定します。 |
| サブタイプ | Standard に設定します。 |
| 環境特有の Webhook | 環境特有の Webhook を指定できます。 |
| 認証 | 認証セクションをご覧ください。 |
| カスタム CA 証明書 | これはカスタム CA 証明書をアップロードするために使用されます。 |
フレキシブル Webhook
フレキシブル Webhook では、リクエスト HTTP メソッド、リクエスト URL パラメータ、リクエスト メッセージとレスポンス メッセージのフィールドを自分で定義します。リクエストは、選択したパラメータ値のみを指定し、レスポンスはパラメータのオーバーライド値のみを指定できます。エージェントと Webhook 間のインターフェースを簡素化するため、この制限は実際に有益です。エージェントと Webhook 間でセッション パラメータ値以外の通信を行う必要はほとんどありません。また、リクエスト メッセージとレスポンス メッセージには必要なものだけが含まれ、さまざまなシナリオに一意の Webhook メッセージを指定できるため、Webhook の実装も簡素化されます。
フレキシブル Webhook リクエスト
エージェントの Webhook リソースを作成する際に、Webhook リクエストに対し、以下を指定できます。
- Webhook サービスに送信される Webhook リクエストに使用される HTTP メソッド。
- URL を使用して Dialogflow が Webhook サービスに送信する必要があるセッション パラメータ値。
- 方式として
POST、PUT、PATCHのいずれかを選択した場合、リクエストの JSON 本文を通じて Dialogflow が Webhook サービスに送信するセッション パラメータ値。
リクエスト URL または JSON 本文を使用してセッション パラメータ値を送信するには、通常どおりにパラメータ参照を使用します。パラメータ参照を URL エスケープする必要はありません。また、参照を引用符で囲む必要はありません。実行時に、Dialogflow は必要に応じてパラメータ値を URL エスケープします。リストまたは複合値は JSON として指定されます。
JSON 本文でパラメータ参照を使用する場合は、パラメータのタイプに関係なく、参照を引用符で囲む必要があります。パラメータが実際に数値スカラー、リスト、複合値である場合、Dialogflow は、実行時にリクエストを送信するときに引用符を削除して、パラメータのデータ型を保持します。文字列スカラー型は、引用符で囲まれたままになります。数値スカラー、数値、または複合値が文字列値内で参照されている場合（例: "This is a number: $session.params.size"）、パラメータは文字列として扱われます（"This is a number: 3"）。
たとえば、次のようにして、fruit と size のセッション パラメータ値をリクエスト URL に指定できます。
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
また、次のようにして、リクエスト JSON 本文に指定できます。
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
フレキシブル Webhook レスポンス
エージェントの Webhook リソースを作成する際に、Dialogflow が実行時に Webhook レスポンスの特定のフィールドに設定する必要があるセッション パラメータを指定できます。
回答には次の制限が適用されます。
- レスポンスは、Webhook リソースを作成するときに構成したタイムアウト内で実行する必要があります。この制限時間を超えると、リクエストがタイムアウトになります。
- レスポンスのサイズは 64 KiB 以下でなければなりません。
スカラー フィールド、リスト フィールド、または複合フィールドを指定するには、次の形式を使用します。
$.fully.qualified.path.to.field
たとえば、次の JSON レスポンスについて考えてみます。
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
「value」フィールドを指定するには、次のようにします。
$.routes[0].legs[0].distance.value
フレキシブル Webhook リソース設定
フレキシブル Webhook の Webhook リソース設定は次のとおりです。
| 用語 | 定義 |
|---|---|
| 表示名 | Webhook のコンソールに表示される名前。 |
| Webhook タイムアウト | Dialogflow が Webhook サービスに Webhook リクエストを送信する際、レスポンスの待機中にタイムアウトが発生することがあります。この設定では、タイムアウトを秒単位で制御します。タイムアウトが発生すると、Dialogflow によって webhook.error.timeout イベントが呼び出されます。 |
| 種類 | プライベート ネットワーク アクセスに Service Directory を使用する場合は「Service Directory」、それ以外の場合は「Generic Web Service」に設定します。 |
| Webhook URL | Webhook サービスの URL アドレスを指定します。これには、セッション パラメータへの参照が含まれる場合があります。 |
| サブタイプ | フレキシブルに設定します。 |
| メソッド | Webhook リクエストの HTTP メソッドを設定します。 |
| リクエストの本文 | 前述のように、リクエストの JSON 本文を指定します。 |
| レスポンス構成 | 前述のように、レスポンス フィールドに設定する必要があるセッション パラメータを指定します。 |
| 環境特有の Webhook | 環境特有の Webhook を指定できます。 |
| 認証 | 認証セクションをご覧ください。 |
| カスタム CA 証明書 | これはカスタム CA 証明書をアップロードするために使用されます。 |
Webhook サービスの要件
webhook サービスは、次の要件を満たす必要があります。
- HTTPS リクエストを処理する必要があります。HTTP はサポートされていません。コンピューティングまたはサーバーレス コンピューティング ソリューションを使用して Google Cloud Platform で Webhook サービスをホストしている場合は、HTTPS によるサービス提供に関するドキュメントをご覧ください。その他のホスティング オプションについては、ドメインの SSL 証明書を取得するをご覧ください。
- リクエストの URL は、Cloud Function としてホストされている場合、または Service Directory Webhook としてアクセスされている場合を除き、公開アクセス可能である必要があります。
- 標準 Webhook またはフレキシブル Webhook セクションで説明されているとおりに、リクエストとレスポンスを処理する必要があります。
- エージェントが Service Directory のプライベート ネットワーク アクセスと統合されていない場合、Webhook 呼び出しはサービス境界外とみなされ、VPC Service Controls を有効にするときにブロックされます。制限付きエンドポイントは Service Directory でサポートされています。詳細については、Service Directory をご覧ください。
認証
Dialogflow エージェントまたはその所有者のみがリクエスト作成認証を持つように、Webhook サービスを保護することが重要です。これは Webhook リソースを作成するときに構成されます。Dialogflow CX は次の認証メカニズムをサポートしています。
| 用語 | 定義 |
|---|---|
| 認証ヘッダー | Webhook 設定では、オプションの HTTP ヘッダーの Key-Value ペアを指定できます。指定した場合、Dialogflow によって Webhook リクエストに HTTP ヘッダーが追加されます。通常は、authorization のキーを持つ単一のペアを指定します。 ヘッダー値は、静的レスポンス メッセージと同様に、セッション パラメータ参照とシステム関数の解析をサポートします。 |
| ユーザー名とパスワードによる基本認証 | Webhook 設定では、オプションのログイン ユーザー名とパスワードの値を指定できます。指定された場合、Dialogflow は webhook リクエストに認証 HTTP ヘッダーを追加します。このヘッダーの形式は "authorization: Basic <base 64 encoding of the string username:password>" です。 |
| サードパーティの OAuth | Dialogflow が OAuth プロバイダからのアクセス トークンを交換して認証 HTTP ヘッダーに追加するように、サードパーティの OAuth 構成を指定できます。クライアント認証情報フローのみがサポートされています。 |
| サービス エージェントのアクセス トークン | サービス エージェント認証でアクセス トークンを選択して、認証にサービス エージェントのアクセス トークンを使用できます。これは他の Google Cloud APIs へのアクセスに使用できます。 |
| サービス エージェントの ID トークン | サービス エージェント認証で ID トークンを選択して、認証にサービス エージェントの ID トークンを使用できます。これは Cloud Functions の関数と Cloud Run サービスへのアクセスに使用できます。他の認証オプションを使用しない場合は、デフォルトで有効になっています。 |
| 相互 TLS 認証 | 相互 TLS 認証のドキュメントをご覧ください。 |
HTTPS 証明書の検証
Dialogflow はデフォルトで Google のデフォルトのトラストストアを使用して HTTPS 証明書を検証します。Google のデフォルトのトラストストアで認識されない証明書（自己署名証明書やカスタムルート証明書など）を HTTPS サーバーに使用する場合は、カスタム CA 証明書をご覧ください。
環境特有の Webhook
環境を使用して本番環境システムを開発環境から分離している場合は（推奨）、Webhook を環境特有に構成できます。定義した Webhook リソースごとに、エージェント用に定義した環境ごとに一意の URL と認証の設定を指定できます。
これによって、Webhook コードの更新を本番環境にデプロイする前に安全に開発してテストできます。
Webhook リソースを作成または編集する
Webhook サービスを実行すると、接続と認証の情報を含むエージェントに Webhook リソースを作成する必要があります。作成後、Webhook リソースの設定を随時編集することもできます。
Webhook リソースを作成または編集するには:
Console
- Dialogflow CX Console を開きます。
- ご自身の Google Cloud プロジェクトを選択します。
- エージェントを選択します。
- [Manage] タブを選択します。
- [Webhooks] をクリックします。
- [作成] をクリックするか、編集するリスト内の Webhook リソースをクリックします。
- 標準の Webhook リソース設定またはフレキシブル Webhook リソース設定を入力します。
- [保存] をクリックします。
API
Webhook リソースを作成するには、Webhook タイプ用の create メソッドをご覧ください。Webhook リソース（環境特有の設定を除く）を編集するには、Webhook タイプ用の patch または update メソッドをご覧ください。
Webhook リファレンスのプロトコルとバージョンを選択:
| プロトコル | V3 | V3beta1 |
|---|---|---|
| REST | Webhook リソース | Webhook リソース |
| RPC | Webhook インターフェース | Webhook インターフェース |
| C++ | WebhooksClient | 利用できません |
| C# | WebhooksClient | 利用できません |
| Go | WebhooksClient | 利用できません |
| Java | WebhooksClient | WebhooksClient |
| Node.js | WebhooksClient | WebhooksClient |
| PHP | 提供なし | 利用できません |
| Python | WebhooksClient | WebhooksClient |
| Ruby | 提供なし | 利用できません |
Webhook 用の環境特有の設定を編集するには、Environment タイプ用の patch または update メソッドをご覧ください。
環境リファレンスのプロトコルとバージョンを選択:
| プロトコル | V3 | V3beta1 |
|---|---|---|
| REST | 環境リソース | 環境リソース |
| RPC | 環境インターフェース | 環境インターフェース |
| C++ | EnvironmentsClient | 利用できません |
| C# | EnvironmentsClient | 利用できません |
| Go | EnvironmentsClient | 利用できません |
| Java | EnvironmentsClient | EnvironmentsClient |
| Node.js | EnvironmentsClient | EnvironmentsClient |
| PHP | 提供なし | 利用できません |
| Python | EnvironmentsClient | EnvironmentsClient |
| Ruby | 提供なし | 利用できません |
Webhook エラー
Webhook サービスで Webhook リクエストの処理中にエラーが発生した場合、Webhook コードは次のいずれかの HTTP ステータス コードを返します。
400Bad Request（不正なリクエスト）401Unauthorized（未承認）403Forbidden（禁止）404Not found（未検出）500Server fault（サーバーエラー）503Service Unavailable（サービス利用不可）
エラー状況が次のいずれかの場合、Dialogflow は Webhook エラーまたはタイムアウトの組み込みイベントを呼び出し、通常どおり処理を続けます。
- レスポンスのタイムアウトを超過しました。
- エラー ステータス コードを受信しました。
- レスポンスが無効です。
- Webhook サービスを利用できません。
また、インテント検出 API 呼び出しによってWebhook サービス呼び出しがトリガーされた場合、インテント検出レスポンスの queryResult.webhookStatuses フィールドには Webhook ステータスの情報が含まれます。
Cloud Functions の使用
Dialogflow は Cloud Functions と統合されているため、セキュアなサーバーレス Webhook を簡単に作成できます。エージェントと同じプロジェクトに存在する関数を作成すると、エージェントは特別な構成を必要とすることなく Webhook を安全に呼び出すことができます。
ただし、次の 2 つの状況では、この統合を手動で設定する必要があります。
- 次のアドレスを含む Dialogflow Service Agent サービス アカウントが、エージェント プロジェクト用に存在している必要があります。
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
この特別なサービス アカウントおよび関連付けられた鍵は通常、プロジェクトの最初のエージェントを作成するときに自動的に作成されます。2020 年 11 月 1 日より前にエージェントを作成した場合は、この特別なサービス アカウントの作成をトリガーできます。- プロジェクトの新しいエージェントを作成します。
- 次のコマンドを実行します。
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Webhook 関数がエージェントとは異なるプロジェクトにある場合は、関数のプロジェクトのDialogflow Service Agent サービス アカウントに Cloud Functions 起動元の IAM のロールを提供する必要があります。
コンテナ化された Webhook と Go ezcx フレームワークの使用
Go を使用してコンテナ化された Webhook を実装する場合は、Go ezcx フレームワークをご覧ください。 このフレームワークを使用すると、Webhook の作成時に必要な多くの手順を簡素化できます。
サービス ディレクトリを使用したプライベート ネットワーク アクセス
Dialogflow は Service Directory プライベート ネットワーク アクセスと統合されたため、VPC ネットワーク内の Webhook ターゲットに接続できます。これにより、トラフィックが Google Cloud ネットワーク内に保持され、IAM と VPC Service Controls が適用されます。
プライベート ネットワークをターゲットとする Webhook を設定するには、次のようにします。
サービス ディレクトリのプライベート ネットワーク構成に従って、VPC ネットワークとサービス ディレクトリ エンドポイントを構成します。
次のアドレスを含む Dialogflow Service Agent サービス アカウントが、エージェント プロジェクト用に存在している必要があります。
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Dialogflow Service Agent サービス アカウントに、次の IAM ロールを付与します。- サービス ディレクトリ プロジェクトの
servicedirectory.viewer - ネットワーク プロジェクトの
servicedirectory.pscAuthorizedService
- サービス ディレクトリ プロジェクトの
Webhook の作成時に、サービス ディレクトリ サービスと URL、オプションの認証情報を指定します。
Console
API
WebhookタイプのserviceDirectoryフィールドをご覧ください。Webhook リファレンスのプロトコルとバージョンを選択:
プロトコル V3 V3beta1 REST Webhook リソース Webhook リソース RPC Webhook インターフェース Webhook インターフェース C++ WebhooksClient 利用できません C# WebhooksClient 利用できません Go WebhooksClient 利用できません Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP 提供なし 利用できません Python WebhooksClient WebhooksClient Ruby 提供なし 利用できません
問題のトラブルシューティングを行う場合、非公開稼働時間チェックを設定することで Service Directory が正しく構成されていることを確認できます。
サービス エージェント認証
Dialogflow では、Dialogflow サービス エージェントを使用して ID トークンまたはアクセス トークンを生成できます。
トークンは、Dialogflow が Webhook を呼び出すときに認証 HTTP ヘッダーに追加されます。
ID トークン
呼び出し元のロールを付与すると、ID トークンを使用して Cloud Functions の関数と Cloud Run サービスにアクセスできます。
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.comCloud Functions の関数と Cloud Run サービスが同じリソース プロジェクトにある場合、サービスを呼び出すために追加の IAM 権限は必要ありません。
Webhook はまた、Google クライアント ライブラリまたは github.com/googleapis/google-auth-library-nodejs などのオープンソース ライブラリを使用して、必要に応じてトークンを検証できます。
アクセス トークン
必要なロールを付与すると、アクセス トークンを使用して他の Google Cloud APIs にアクセスできます。
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
サンプルとトラブルシューティング
Webhook 入門ガイドをご覧ください。