Alexa ConversationsのAPI呼び出しの処理

Alexa ConversationsのAPI呼び出しの処理

スキルでAPIを呼び出すために、AlexaはDialog.API.Invokedタイプのリクエストをスキルに送信します。リクエストのフィールドには、APIの名前、引数の値、スロットの値が含まれます。スキルはAlexa Conversations用のAPIの定義で定義したすべてのAPIを処理できる必要があります。

Alexaがスキルとやり取りするために使用するリクエストと応答は、カスタムスキルのJSONインターフェースのリファレンスに記載されている形式とほぼ同じですが、若干の違いがあります。この違いの概要については、Alexa Conversationsのリクエストと応答のリファレンスを参照してください。

ヒント

Alexa Conversationsスキルでのリクエスト処理と応答送信の方法の例を確認するには、Alexa-hostedサンプルスキルテンプレートを使用することをお勧めします。開発者コンソールのオンラインコードエディターを使用して、スキルコードを検証できます。テンプレートからスキルを作成する方法については、Alexa Conversationsを使用した開発の概要を参照してください。

リクエストを受け取る

Alexa Conversationsスキルで、dateとcityNameの2つの入力引数を持つGetWeather APIを定義しているとします。Alexaは、ユーザーとの対話からdateとcityNameの値を取得した後、次のようなDialog.API.Invokedタイプのリクエストをスキルに送信します。

{
  "type": "Dialog.API.Invoked",
  "requestId": "amzn1.echo-api.request.edbb146d-a38a-4e31-9010-eab4403981b7",
  "timestamp": "2020-01-02T02:35:15Z",
  "locale": "ja-JP",
  "apiRequest": {
    "name": "GetWeather",
    "arguments": {
      "date": "2020-01-01",
      "cityName": "神戸"
    },
    "slots": {
      "date": {
        "type": "Simple",
        "value": "2020-01-01"
      },
      "cityName": {
        "type": "Simple",
        "value": "神戸",
        "resolutions": {..} // オプション、 エンティティ解決用
      }
    }
  }
}

応答を返す

Dialog.API.Invokedリクエストに応答を送信するときは、次のどちらか1つだけをresponseオブジェクトで返す必要があります。

  • apiResponseオブジェクト。Alexa Conversationsモデルがダイアログでアクションの予測を継続する必要があることを示します。
  • Dialog.DelegateRequestディレクティブ。ダイアログ管理のコントロールをスキルに転送します。Dialog.DelegateRequestディレクティブの例については、Alexa Conversationsとの間でのダイアログ管理の引き渡しを参照してください。

apiResponseオブジェクトとDialog.DelegateRequestディレクティブの両方を返すことはできません。詳しいルールについては、応答の処理を参照してください。

apiResponseオブジェクトを使用した応答のスキーマは次のとおりです。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {
      "cityName": "神戸",
      "lowTemperature": 10,
      "highTemperature": 18
    }
  }
}

apiResponseの内容は、Alexa Conversations用のAPIの定義で設定したAPI定義の戻り値の型と一致している必要があります。これらのオブジェクトには、マルチレベルのJSONオブジェクトを使用できます。

Node.JS SDKを使用してGetWeather APIを処理するスキルコードは、次のようになります。

クリップボードにコピーされました。

const GetWeatherApiHandler = {
    canHandle(handlerInput) {
        return util.isApiRequest(handlerInput, 'GetWeatherApi');
    },
    handle(handlerInput) {
        const cityNameWithId = util.getCityNameWithIdFromApiRequestSlots(handlerInput);

        if (!cityNameWithId) {
            //この都市の値がスロットに一致しなかったので、
            //空の値を返し、応答テンプレートに処理させます。
            return {apiResponse:{}};
        }

        //この場所と日付の天気を取得するサービスを呼び出します。
        const weather = weatherClient.getWeather(cityNameWithId.id);

        const response = {
            apiResponse: {
                cityName: cityNameWithId.name,
                lowTemperature: weather.lowTemperature,
                highTemperature: weather.highTemperature
            }
        }

        return response;
    }
}

スキルセッションを終了する

スキルセッションが終了することを示すには、shouldEndSessionをtrueに設定した応答をDialog.API.Invokedリクエストに返します。これでAPI Success（またはAPI Failure）の応答がレンダリング可能になり、セッションが終了してマイクがオフになります。

このページは役に立ちましたか？

最終更新日: 2022 年 01 月 14 日