Alexa.Presentation.APLAインターフェースのリファレンス

Alexa.Presentation.APLAインターフェースのリファレンス

Alexa.Presentation.APLAインターフェースは、APLドキュメントで定義されたオーディオ応答をレンダリングするためのディレクティブを提供します。

RenderDocumentディレクティブ

指定したドキュメントで、指定したオーディオ応答を再生するようにデバイスに命令します。オプションで、1つまたは複数のdatasourcesを指定してコンテンツをドキュメントにバインドすることもできます。

標準の応答または再プロンプトの一部として、APL for AudioのRenderDocumentディレクティブを返すことができます。詳細については、Responseオブジェクトを参照してください。

次の例では、オーディオ応答を再生するためのドキュメント全体を渡します。

{
  "type": "Alexa.Presentation.APLA.RenderDocument",
  "token": "developer-provided-string",
  "document": {
    "version": "0.91",
    "type": "APLA",
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "item": {
        "type": "Selector",
        "items": [
          {
            "type": "Speech",
            "when": "${payload.user.name == ''}",
            "content": "こんにちは"
          },
          {
            "type": "Speech",
            "content": "${payload.user.name}さん、こんにちは！"
          }
        ]
      }
    }
  },
  "datasources": {
    "user": {
      "name": "太郎"
    }
  }
}

プロパティ

名前 説明 型 必須

datasources

ドキュメントにデータを指定するためのデータソースオブジェクトのマップです。データをテンプレートと分けるために使用します。データバインディングの評価とデータバインディングの構文を参照してください。

オブジェクト

✕

document

オーディオ応答に変換し、ユーザーのデバイスで再生するAPLドキュメントを表すオブジェクトです。

document.typeが"APLA"の場合、documentには完全なJSONドキュメントが含まれている必要があります。

document.typeが"Link"の場合、documentにはドキュメントへのURLリンクを指定したsrcプロパティが含まれている必要があります。

オブジェクト

◯

document.src

オーサリングツールでドキュメントを識別するURLです。APLAの場合、リンクの構文はdoc://alexa/apla/documents/<RESPONSE-NAME>です。<RESPONSE-NAME>をドキュメントの保存時に使用した名前に置き換えます。document.typeがAPLAの場合は、このプロパティを含めないでください。

doc://alexa/apla/documents/<RESPONSE-NAME>

✕

document.type

送信するドキュメントの種類を示します。documentに完全なドキュメントオブジェクトが含まれている場合は、"APLA"に設定します。document.srcにドキュメントへのリンクが含まれている場合は、"Link"に設定します。

APLA | Link

✕

token

プレゼンテーションの一意のIDです。各ドキュメントは独立したプレゼンテーションと見なされます。これは今後のイベントやディレクティブを適切なプレゼンテーションと関連付けるために使用されます。

文字列

✕

type

常にAlexa.Presentation.APLA.RenderDocumentです。

文字列

◯

オーサリングツールでAPLAドキュメントを保存すると、RenderDocumentディレクティブでそのドキュメントをリンクすることができます。つまり、ドキュメントのJSONをエクスポートしてコードにコピーする必要はありません。

オーサリングツールでAPLAドキュメントにリンクするには、次の構文を記述します。

doc://alexa/apla/documents/<RESPONSE-NAME>

<RESPONSE-NAME>は、オーサリングツールでドキュメントを保存するときに使用した名前です。

次の例では、オーディオ応答のsrcでリンクされたドキュメントのリンクを指定します。

{
   "type": "Alexa.Presentation.APLA.RenderDocument",
   "token": "developer-provided-string",
   "document": {
     "type": "Link",
     "src":  "doc://alexa/apla/documents/<RESPONSE-NAME>",
   },
   "datasources": {
     "user": {
       "name": "太郎"
     }
   }
 }

RuntimeErrorリクエスト

APLAの処理中に発生したエラーをスキルに通知するために送信されます。このリクエストは通知専用です。スキルは、RuntimeErrorリクエストに応答を返すことはできません。

名前 説明 型

errors

報告されたエラーを表すエラーオブジェクトの配列です。

配列

token

プレゼンテーションの一意のIDです。RenderDocumentでデバイスに以前送信されたAPLAドキュメントを識別します。

文字列

type

常にAlexa.Presentation.APLA.RuntimeErrorです。

文字列

 
{
  "type": "Alexa.Presentation.APLA.RuntimeError",
  "token": "developer-provided-string",
  "errors": [
    {
      "type": "UNKNOWN_ERROR",
      "reason": "発生したエラーのタイプを説明します。",
      "message": "人が読める形式でのエラーの説明です。"
    }
  ]
}

errors

発生したエラーを表すエラーオブジェクトの配列です。各エラーオブジェクトの構造は次のとおりです。

{
  "type": "ポリモーフィズムなエラータイプのインジケータ―です。",
  "reason": "発生したエラーのタイプを説明します。",
  "message": "人が読める形式でのエラーの説明です。"
}
プロパティ 型 説明
message 文字列 人が読める形式でのエラーの説明です。
reason 文字列 発生したエラーの理由を説明します。
type 文字列 ポリモーフィズムなエラータイプのインジケータ―です。

type

ポリモーフィズムなエラータイプのインジケータ―です。各エラータイプにはタイプ固有のパラメーターを指定できます。

プロパティ 説明
RENDER_ERROR クラウドベースのオーディオミキシングサービスに関連するエラーです。
LINK_ERROR リンクされたドキュメントに関連するエラーです。

reason

エラーの理由を示すエラーコードを提供します。以下の汎用的な値はすべてのタイプのエラーで利用できます。

エラーコード 説明
UNKNOWN_ERROR 発生元が不明な想定外の問題です。
INTERNAL_SERVER_ERROR Alexaサービスの想定外の問題です。

LINK_ERRORの場合、汎用的な値以外に以下の表に記載したエラーコードを返すことができます。

エラーコード 説明
NOT_FOUND_ERROR リンクされたドキュメントが見つかりませんでした。これは通常、指定されたdocument.srcが無効であるか、ドキュメントを利用するためにはスキルの再ビルドが必要であることを示しています。

RenderDocumentをoutputSpeechと再プロンプトに組み合わせる

APL for Audioは、既存のoutputSpeechプロパティおよびrepromptプロパティと併用できます。

応答にoutputSpeechとRenderDocumentディレクティブの両方が含まれている場合、デバイスは最初にoutputSpeechをレンダリングし、続いてAPLドキュメントで定義されているオーディオをレンダリングします。Alexaがユーザーの応答をリッスンするインタラクション中（shouldEndSessionがfalseの場合）にユーザーが数秒以内に応答しない場合、repromptが再生されます。

次の例は、outputSpeech、reprompt、RenderDocumentを含むレスポンスを示しています。ドキュメントの内容は、簡潔に示すために省略しています。

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

このサンプルコードはAlexa Skills Kit SDK for Node.js（v2）を使用しています。

return handlerInput.responseBuilder
     .speak("こんにちは")
     .addDirective({
            "type": "Alexa.Presentation.APLA.RenderDocument",
            "token": "launch_a",
            "document": {
                 "version": "0.91",
                 "type": "APLA",
                 "mainTemplate": {
                      "parameters": [
                           "payload"
                      ],
                     "item": {}
                 }
            }
     })
     .reprompt("これは再プロンプトです")
     .getResponse();

サービスインターフェースのリファレンス（JSON）

リクエストの形式と標準のリクエストタイプ：

インターフェース：

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

最終更新日: 2021 年 09 月 29 日