Alexa Conversationsのリクエストと応答のリファレンス

Alexa Conversationsのリクエストと応答のリファレンス

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

リクエストの形式

Alexa Conversationsのリクエストとカスタムスキルのリクエストの唯一の違いは、Alexa Conversationsの場合、リクエストオブジェクトはDialog.API.Invokedタイプで、apiRequestオブジェクトが含まれていることです。

リクエスト本文の構文

{
   "version": "1.0",
   "session": {},
   "context": {},
   "request": {
      "type": "Dialog.API.Invoked",
      "requestId": "...",
      "timestamp": "...",
      "locale": "...",
      "apiRequest" : {
         "name" : "サンプルAPI名",   
         "arguments" : {
            ...
         },
         "slots": {
            ...
         }  
      }     
   }
}
フィールド 説明 型

type

リクエストのタイプです。Alexa Conversationsの場合、値はDialog.API.Invokedです。

文字列

requestId

特定のリクエストの一意のIDです。

文字列

timestamp

Alexaがリクエストを送信した日時を表す文字列（ISO 8601形式）です。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます（リプレイ攻撃を防ぐため）。詳細については、タイムスタンプを参照してください。

文字列

locale

ユーザーのロケールを示す文字列です。例：ja-JPロケールコードの詳細については、サポートされているロケールコードを参照してください。

文字列

apiRequest.name

呼び出されたAPIの名前です。

文字列

apiRequest.arguments

プレーンなデータオブジェクトとしてAPIリクエストのペイロードを含むオブジェクトです。詳細については、argumentsオブジェクトを参照してください。

オブジェクト

apiRequest.slots

指定されたAPIリクエスト引数の解決とその値を含むオブジェクトです。詳細については、slotsオブジェクトを参照してください。

オブジェクト

argumentsオブジェクト

argumentsオブジェクトは、プレーンなリクエストデータオブジェクトです。これには次のルールがあります。

  • argumentsオブジェクトには、APIが使用する各スロットタイプのプリミティブ値が含まれます。
  • argumentsオブジェクトは、API定義で定義されているのと同じ構造に従います。
  • 値のデータ型は、使用するスロットタイプによって異なります。
  • Alexa Conversationsが発話値を関連するスロットタイプ形式に解決できない場合、そのスロットの引数値は設定されません。たとえば、スロットタイプAMAZON.NUMBERのスロットSlotAに対してユーザーが「神戸」と言った場合、「神戸」は数値に解決できないため、argumentsオブジェクトにはSlotAの値は含まれません。slotsオブジェクトのSlotAの値は、未解決の文字列値「神戸」になります。

slotsオブジェクト

apiRequest.slotsオブジェクト内の値を送信する場合、発話値の既存のスロットおよびエンティティ解決のルールがあれば、Alexa Conversationsはそれに従います。slotsオブジェクトには、スロット値とそれに対応する解決が含まれます。

slotsオブジェクトの値は、次のルールに基づいています。

  • すべての単純なスロットにスロット値があります。

slotsオブジェクトの解決は、次のルールに基づいています。

  • 現在、Alexa Conversationsは複雑なスロットやリストスロットの解決をサポートしていないため、これらのタイプのスロットにはエンティティ解決は存在しません。
  • AMAZON.DATEやAMAZON.TIMEなど、数値や日付などのデータタイプに変換するスロットタイプには、エンティティ解決は存在しません。
  • Alexa Conversationsは、他のカスタムスキルと同じスロットタイプの拡張ルールに従います。詳細については、スロットタイプを拡張するを参照してください。
  • エンティティ解決は、スロットタイプが単純で、かつ発話の場合にのみslotsオブジェクトに存在します。

例1

次の例は、テストに使用できる完全なDialog.API.Invokeリクエストです。

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.12345678",
    "application": {
      "applicationId": "amzn1.ask.skill.12345678"
    },
    "attributes": {},
    "user": {
      "userId": "amzn1.ask.account.testUser"
    }
  },
  "context": {},
  "request": {
    "type": "Dialog.API.Invoked",
    "requestId": "amzn1.echo-api.request.1234",
    "timestamp": "2021-05-25T21:06:28Z",
    "locale": "ja-JP",
    "apiRequest": {
      "name": “PlaceholderAPI”,
      "arguments": {
        "argument1": "テスト"
      }
    }
  }    
}

例2

この例では、スキルAPIには次のスキーマがあります。

// API schema 
{
    "apiName": "BookMovieTicket",
    "arguments": {
        "movie" : {
            "type" : "Movie"
        },
        "partySize" : {
            "type" : "AMAZON.NUMBER"
        },
        "preferredShowTimes" : {
            "type" : "List<AMAZON.TIME>"
        },
        "preferredTheaters": {
            "type": "List<Theater>"
        }
    },
    "returns": {
        "type" : "BookingResult"
    }
}

この場合、スキルに対するDialog.API.Invokedリクエストは次のようになります。

{
    "version" : "1.0",          
    "session" : {
        "attributes" : {},
        ..
    },             
    "context" : {},             
    "request" : {               
        // 標準 フィールド        
        "type" : "Dialog.API.Invoked",
        "requestId" : "...",
        "timestamp" : "..",
        "locale" : "..",
        // Alexa Conversations固有
        "apiRequest" : {
            "name" : "BookMovieTicket",         // API 名
            "arguments" : {
              "movie" : "サンプル映画名",   // カスタムスロットタイプ（映画）
              "partySize" : 4,                  // AMAZON.NUMBER 
              "preferredShowTimes": [           // List<AMAZON.TIME>
                "12:00",
                "16:00",
                "21:00"
              ],
              "preferredTheaters": [            // カスタムスロットタイプのリスト（映画館）
               {
                 "name": "myValue",
                 "address": "myValue"
               }
             ]
           },
           // スロットは単純な場合に値を持ちます 
           // スロットタイプと値は発話されます 
           "slots": {
             "movie": {
               "type": "Simple",
               "value": “サンプル映画名”,
               "resolutions": { .. }
             },
             "partySize": {
               "type": "Simple",
               "value": "4"
             }
          }  
       }  
    }
}

応答の形式

Alexa Conversationsの場合、responseオブジェクトにはapiResponseオブジェクトまたはDialog.DelegateRequestディレクティブのどちらか一方を含めることができます。apiResponseオブジェクトを使用した応答のスキーマは次のとおりです。

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        "key1": "value1",
        "key2": {},
        "key3": []
       },
       "shouldEndSession": true|false|null       
   } 
}

応答本文の構文

フィールド 説明 型 必須

version

応答のバージョン指定子です。値は "1.0"です。

文字列

◯

response

ユーザーに対して何を出力するかと現在のセッションを終了するかどうかを定義する応答オブジェクトです。

オブジェクト

◯

response.apiResponse

API応答エンティティオブジェクトと、ビルド時にスキルによって定義された値です。

オブジェクト、リスト、文字列、または数値

◯

response.shouldEndSession

Alexaが応答を発話した後に何が起こるかを表すブール値です。

  • true： セッションが終了します。
  • false： Alexaは、ユーザーの応答を聴き取るために数秒間マイクを有効にします。
  • null / undefined： セッションの動作は、Echoデバイスの種類によって異なります。デバイスに画面があり、スキルに画面コンテンツが表示されている場合、セッションは最大30秒間開いたままになります。ただし、マイクをオンにしてユーザーに入力を求めることはありません。詳細については、画面付きデバイスがスキルセッションに与える影響を参照してください。ユーザーが話しかけてきて、リクエストの前に「アレクサ」を付けた場合、Alexaはリクエストをスキルに送信します。それ以外の場合、Alexaはユーザーの音声を無視します。Alexa Gadgetsイベントハンドラーが有効な場合、スキルがCustomInterfaceController.StopEventHandlerを呼び出すまで、あるいはイベントハンドラーの有効期限が切れない限り、セッションは開いたままになります。

ブール値

✕

例

次の例は、apiResponseオブジェクトを含む応答を示しています。

例1

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        “movieShows”: [
          {
            "movieId" : "movie-1",
            “availableSeats” : 4,
            “movieTime” : "12:00"
          },
          {
            "movieId" : "movie-2",
            “availableSeats” : 2,
            “movieTime” : "16:00"
          }
        ]
      },
     "shouldEndSession": false      
   } 
}

例2

{
   "version" : "1.0",
   "sessionAttributes": {},
   "response" : {
      "apiResponse" : {
        "orderStatus" : "submitted",
        "pickupOrDelivery" : "pickup",
        "toppings": [
            "オリーブ", "ピーマン", "パイナップル"
        ],
        "orderTime": "14:00"
      },
     "shouldEndSession": false         
   } 
}

応答の処理

apiResponseオブジェクトで返せるディレクティブは、Dialog.DelegateRequestディレクティブのみです。これにより、ダイアログ管理をスキルにデリゲートし、標準のカスタムスキル応答を返すことができます。次のターンでは、リクエストはスキルに送信されます。Alexa Conversationsでダイアログを処理する場合は、Alexa Conversationsにデリゲートする必要があります。

Dialog.API.Invokedに応答を返すときは、次のルールに従います。

  • Alexa Conversationsモデルでダイアログの次のアクションの予測を継続するには、apiResponseオブジェクトを返します。
  • ダイアログ管理のコントロールをスキルに転送するには、Dialog.DelegateRequestディレクティブを返します。
  • Dialog.API.Invokedリクエストに応答を返すときは、応答オブジェクトでapiResponseオブジェクトまたはDialog.DelegateRequestディレクティブのどちらか一方のみを返す必要があります。
  • apiResponseオブジェクトとDialog.DelegateRequestディレクティブの両方を返すことはできません。
  • sessionAttributesオブジェクトでデータを設定できます。sessionAttributesオブジェクトは、応答のJSONエンベロープ内の応答オブジェクトの外側にあります。
  • apiResponseオブジェクトは、呼び出されたAPIのスキーマと一致する必要があります。
  • apiResponseオブジェクトの値は、使用しているスロットタイプの形式と一致する必要があります。たとえば、AMAZON.DATE（ユーザーの発話を数値や日付などのデータタイプに変換するスロットタイプ）に値を返す場合、その値は2020-01-01のようなAMAZON.DATE形式である必要があります。同様に、カタログベースのスロットの場合は、任意の文字列値を返すことができます。

次の例は、通常のAPI応答を返します。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "apiResponse": {
      "orderStatus": "submitted",
      "pickupOrDelivery": "pickup",
      ...
    }
  }
}

ダイアログ中にディレクティブやその他の応答オブジェクトが必要な場合は、まずスキルに再度デリゲートする必要があります。

次の応答は、ダイアログ管理をスキルにデリゲートします。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"Dialog.DelegateRequest",
        ..
      }
    ]
  }
}

次に、レンダリングする応答を次のように返します。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"AudioPlayer.Play",
        ..
      }
    ]
  }
}

完了したら、次のように同じDialog.DelegateRequestディレクティブを使用して、コントロールをAlexa Conversationsに戻すことができます。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "directives":[
      {
        "type":"Dialog.DelegateRequest",
        "target" : "AMAZON.Conversations",
        "period": {
           "until": "EXPLICIT_RETURN"
        },        
        "updatedRequest": {..}
        ..
      }
    ]
  }
}

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

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