会話型アクションのサポートは 2023 年 6 月 13 日に終了しました。詳細については、会話型アクションの廃止をご覧ください。

このページは Cloud Translation API によって翻訳されました。

Webhook

より柔軟にアクションを作成できるように、ロジックをデリゲート HTTPS ウェブサービス（フルフィルメント）アクションで Webhook をトリガーし、 HTTPS エンドポイントにリクエストを送信できます。例として、Google Chat でフルフィルメントには以下が含まれます。

ユーザーから提供された情報に基づいて動的プロンプトを生成する。
外部システムに注文を行い、成功を確認する。
バックエンドデータによるスロットの検証。

**図 1.** 呼び出しインテントとシーンでトリガーできる Webhook などです。

Webhook のトリガーとハンドラ

アクションは、呼び出しインテントまたはシーン内で Webhook をトリガーできます。フルフィルメントエンドポイントにリクエストを送信します。フルフィルメントに Webhook が含まれていますハンドラを定義します。Webhook をトリガーして次のような場合です。

呼び出しインテントの一致後
シーンの開始ステージ
シーンの条件ステージで条件が true と評価された後
シーンのスロット充填ステージ
シーンの入力ステージでインテントマッチが発生した後

アクションで Webhook をトリガーすると、Google アシスタントは（JSON ペイロードを含む）をフルフィルメントに送信します。イベントの処理に使用するハンドラの名前。フルフィルメントエンドポイントは適切なハンドラにイベントをルーティングしてロジックを実行し、対応する JSON ペイロードを含むレスポンス。

ペイロード

次のスニペットは、アクションから送信されるリクエストの例を示しています。返すレスポンスが返されます詳しくは、リファレンスドキュメント情報です。

リクエストの例

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

レスポンスの例

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

ランタイムインタラクション

以降のセクションでは、 Webhook ハンドラを指定します。

プロンプトを送信する

シンプルなテキスト、リッチテキスト、カード、さらには本格的なプロンプトも作成できます。 Interactive Canvas を使用するウェブアプリに基づく HTML プロンプト。プロンプトのドキュメントに Webhook イベントの処理時にプロンプトを作成する方法に関する完全な情報をご確認ください。次のスニペットは、カードプロンプトを示しています。

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

レスポンス JSON

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

インテントパラメータの読み取り

アシスタントランタイムは、インテントを一致させると、あります。元のプロパティはユーザーが入力として指定したもので、「Resolved」プロパティは、タイプに基づいて NLU が入力を解決したプロパティです。仕様。

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

リクエスト JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

ユーザーの言語 / 地域を読み取る

この値は、ユーザーの Google アシスタントの言語 / 地域設定に対応しています。

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

読み取りと書き込みのストレージ

リソースの作成方法については、ストレージのドキュメントをご覧ください。さまざまなストレージ機能を使用します。

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

リクエスト JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

レスポンス JSON

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

デバイスの機能を確認する

デバイスの機能を確認して、さまざまな機能を提供したり、やり取りできます。

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

リクエスト JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

サーフェス機能の完全なリストについては、Capability をご覧ください。ご覧ください。

ランタイムタイプのオーバーライド

ランタイムタイプを使用すると、実行時にタイプの仕様を変更できます。こちらの他のソースからデータを読み込んで型の有効な値を入力できます。対象ランタイムタイプのオーバーライドを使用して、アンケートに動的オプションを追加できます。日替わりメニューへの追加も可能です。

ランタイムタイプを使用するには、アクションから使用します。そこから session.typeOverrides パラメータをアクションに対するレスポンスで渡します。使用可能モードには、既存の型エントリを保持する TYPE_MERGE または TYPE_REPLACE が含まれます。既存のエントリをオーバーライドに置き換えます。

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

レスポンス JSON

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

音声バイアスを設定する

音声バイアスを使用すると、NLU にヒントを指定してインテントマッチングを改善できます。マイページ最大 1,000 個のエントリを指定できます。

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

レスポンス JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

遷移シーン

Actions プロジェクトで静的な遷移を定義するだけでなく、実行時にシーンの遷移が発生します。

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

レスポンス JSON

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

シーンスロットの読み取り

スロット充填中に、フルフィルメントを使用してスロットを検証したり、スロット充填のステータス（SlotFillingStatus）。

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

たとえば、レスポンスからタイムゾーンを抽出するとします。インこの例では、スロット名は datetime1 です。タイムゾーンを取得するには、次のようにします。次のコマンドを使用します。

conv.scene.slots['datetime1'].value.time_zone.id

リクエスト JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

シーンスロットを無効にする

スロットを無効にして、ユーザーに新しい値を指定させることができます。

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

レスポンス JSON

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

開発オプション

</ph> <ph type="x-smartling-placeholder"></ph>

Actions Builder には、Cloud Functions エディタと呼ばれるインラインエディタが備わっています。これにより、Cloud Functions for Firebase をできます。フルフィルメントを構築して任意のホスティングにデプロイすることもできる HTTPS フルフィルメントエンドポイントを Webhook ハンドラとして登録します。

インラインエディタ

Cloud Functions エディタで開発するには:

Actions プロジェクトを開き、[Develop] タブ >Webhook >乗り換えフルフィルメント方法。[Fulfillment Method] ウィンドウが表示されます。
[インライン Cloud Functions] を選択し、[確認] をクリックします。

で確認できます。

外部 HTTPS エンドポイント

このセクションでは、Cloud Functions for Firebase をフルフィルメントサービスが提供されます。ただし、Google Cloud の任意のホスティングサービスに納品できます。

環境を設定する

環境の設定手順は次のとおりです。

Node.js をダウンロードしてインストールします。
Firebase CLI を設定して初期化します。次のコマンドを実行すると、 EACCES エラーが発生した場合は、npm の権限の変更が必要になる場合があります。
```
npm install -g firebase-tools
```
Google アカウントを使用して Firebase ツールを認証します。
```
firebase login
```
Actions プロジェクトを保存したプロジェクトディレクトリを開始します。設定する Firebase CLI 機能を選択するよう求められます。追加することもできます。Functions と、利用したいその他の機能を選択します Enter キーを押して確定し、続行します。
```
$ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init
```
Firebase ツールを Actions プロジェクトに関連付けるため、矢印キーを使ってプロジェクトリスト内を移動します。

注: [ [デフォルトのプロジェクトを設定しない]が、これを行う必要があります。後でコマンド firebase use PROJECT_ID を使用して関連付けます。

プロジェクトを選択すると、Firebase ツールが Functions の関数を使用する言語を尋ねられます矢印キーで選択します Enter キーを押して続行します。

=== Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

ESLint を使用して潜在的なバグを検出し、スタイルを適用するかどうかを選択します（Y または N を入力します）。
```
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
```
プロンプトに「Y」と入力して、プロジェクトの依存関係を取得します。
```
? Do you want to install dependencies with npm now? (Y/n)
```
設定が完了すると、次のような出力が表示されます。
```
✔  Firebase initialization complete!
```

@assistant/conversation の依存関係をインストールします。

$ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

フルフィルメント依存関係を取得し、フルフィルメント関数をデプロイします。
```
$ npm install
$ firebase deploy --only functions
```
デプロイには数分かかります。完了すると、以下のような出力が表示されます。追加します。Dialogflow を入力するには、Function URL が必要です。
```
✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>
```
フルフィルメント URL をコピーして、次のセクションで使用します。

Webhook ハンドラを登録

Cloud Functions の関数のエンドポイントを Webhook ハンドラとして登録するには:

Actions Console で、[Develop] >Webhook。
[Change fulfillment method]（フルフィルメント方法を変更）をクリックします。[Fulfillment Method] ウィンドウ表示されます。
[Webhook] を選択し、[Confirm] をクリックします。
ウェブサービスの URL を [Webhook] フィールドに貼り付けます。
[保存] をクリックします。

Webhook

Webhook のトリガーとハンドラ

ペイロード

リクエストの例

レスポンスの例

ランタイム インタラクション

プロンプトを送信する

Node.js

レスポンス JSON

インテント パラメータの読み取り

Node.js

リクエスト JSON

ユーザーの言語 / 地域を読み取る

Node.js

JSON

読み取りと書き込みのストレージ

Node.js

リクエスト JSON

レスポンス JSON

デバイスの機能を確認する

Node.js

リクエスト JSON

ランタイム タイプのオーバーライド

Node.js

レスポンス JSON

音声バイアスを設定する

Node.js

レスポンス JSON

遷移シーン

Node.js

レスポンス JSON

シーンスロットの読み取り

Node.js

リクエスト JSON

シーンスロットを無効にする

Node.js

レスポンス JSON

開発オプション

インライン エディタ

外部 HTTPS エンドポイント

環境を設定する

Webhook ハンドラを登録

ランタイムインタラクション

インテントパラメータの読み取り

ランタイムタイプのオーバーライド

インラインエディタ