ビデオスキルのメッセージとデータの形式



ビデオスキルのメッセージとデータの形式

ビデオスキルAPIを使用する場合、メッセージ、日付、時刻、URIの形式は共通です。このドキュメントではこれらの形式について説明します。

リクエスト/応答のメッセージ

Alexaは、ユーザーに代わって何らかのリクエストをするディレクティブメッセージをスキルに送信します。ディレクティブには、ユーザーの認証データとリクエスト内容を伝えるペイロードが含まれます。スキルは、Alexa.Responseまたはリクエストに関連するエラーメッセージイベントとその理由で応答します。

認証

ビデオスキルAPIは、OAuth2.0の仕様に準拠しています。ビデオスキルAPIからスキルアダプターに対するすべてのリクエストには、OAuthアクセストークンが含まれます。また、クラウド対応デバイスの場合、デバイス制御クラウドでAuthorization code grantフロータイプをサポートする必要があります。

OAuthプロバイダーを使用するビデオスキルに割り当てられたOAuthのリダイレクトエンドポイントを、ホワイトリストに設定してください。これらのURLは、開発者コンソールのスキルのアカウントリンクページでリダイレクト先のURLとして記載されます。また、OAuthプロバイダーは、Amazon認定の認証局が署名した証明書を持っている必要があります。

Alexaでのユーザーの認証とアカウントリンクの詳細については、アカウントリンクとはを参照してください。

ディレクティブとイベントの形式

スキルに送信されるディレクティブとスキルからAlexaに返されるイベントは、同じ基本構造を共有しています。ディレクティブとイベントには、以下の上位レベルオブジェクトが含まれます。

また一部のイベントには以下も含まれます。

EndpointとHeaderオブジェクトを以下の例と表に示します。

ペイロードのコンテンツはヘッダーで指定されるメッセージの種類によって大きく異なります。ペイロードの詳細については、検出再生コントロールといった、送信するメッセージの種類についてのドキュメントを参照してください。

リクエストの例

以下は、チャンネルの変更リクエストの例です。

 {
  "directive": {
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "header": {
      "messageId": "47971513-5e09-4c5f-826b-d1c2b75800a7",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "name": "ChangeChannel",
      "namespace": "Alexa.ChannelController",
      "payloadVersion": "3"
    },
    "payload": {
      "channel": {
        "affiliateCallSign": "JOAK-DTV",
        "callSign": "JOAK-DTV",
        "channelImage": "http://s3.amazonaws.com/channel_images/pbs.png",
        "name": "NHK",
        "number": "1"
      }
    }
  }
 }

応答の例

{
  "context": {
    "properties": []  
  },
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"DirectedUserId",
          "userId":"some-Amazon-user-id"
       },
       "endpointId":"videoDevice-001"
    },
    "payload": { }
  }
}

Headerオブジェクト

ヘッダーに含まれるフィールドは、すべての種類のメッセージに共通です。これらのフィールドでは、さまざまな種類の識別情報を提供します。以下は、典型的なメッセージヘッダーの例です。


"header": {
  "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
  "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
  "namespace": "Alexa",
  "name": "Response",
  "payloadVersion": "3"
}

ヘッダーには以下のプロパティを含めることができます。

プロパティ 説明

correlationToken

メッセージの交換を識別するトークンです。検出メッセージを除き、以下の種類のメッセージに相関トークンが含まれます。
  • Alexaからスキルへのディレクティブ
  • ディレクティブへの応答のイベント
ディレクティブリクエストに対する応答イベントには、同じ相関を含む必要があります。イベントがAlexaからのリクエストへの応答に含まれない場合、相関トークンは提供されません。

messageID

1つのリクエストまたは応答の一意の識別子です。この情報はトラッキングに使用されます。スキルのログに記録しますが、ビジネスロジックのサポートには使用しません。すべてのメッセージのこのフィールドに値が含まれている必要があります。有効な値は、英数字とダッシュで構成される128文字未満の文字列ですが、ランダムな数値から生成されるバージョン4のUUIDが推奨されます。
name TurnOnTurnOffなど、ディレクティブの名前です。
namespace メッセージペイロードのカテゴリーを示す文字列です。そのディレクティブを含むインターフェースと同じものを使用します。名前空間は、共通のAPIメソッドをグループにまとめるのに使用します。また、メッセージのルーティングに名前空間の値を使用できます。例:
  • Alexa.PlaybackController
  • Alexa.ChannelController
payloadVersion ペイロードメッセージに適用するAPIのバージョンです。このドキュメントおよび関連ドキュメントは、バージョン3を対象としています。

Endpointオブジェクト

Endpointオブジェクトは、通信するデバイスを識別します。また、デバイスとの通信を可能にする認証トークンが含まれます。

以下は、JSONで記述した典型的なメッセージエンドポイントの例です。

 "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "ターゲットエンドポイントのIDです",
      "cookie": {
         "key1": "何らかの情報",
         "key": "検出中に受け取ったペアの値"
      }
    },

ディレクティブで送信されるEndpointオブジェクトには以下のプロパティが含まれます。

プロパティ 説明

scope

メッセージ交換の認証付与に関する設定を記述する、ポリモーフィズムなオブジェクトです。詳細については、Scopeオブジェクトを参照してください。

endpointId

デバイスの識別子です。この識別子は、スキルのドメイン内であるエンドユーザーが所有するすべてのデバイスで一意である必要があります。デバイスの検出中に最初に提供され、このユーザーに関連付けられたデバイスを識別する際に、共通で使用される必要があります。

cookie

エンドポイントに関連付けられたキー/値ペアのリストです。これらは検出中に提供され、エンドポイントの各メッセージで送信されます。

Scopeオブジェクト

Scopeは、メッセージに認可および識別情報を提供するポリモーフィズムなオブジェクトです。Scopeには、typeフィールドと、型によって大きく異なる追加のキー/値ペアが含まれます。以下の表では、サポートされる型を示しています。

Scopeのtype 説明 関連フィールドと説明
BearerToken リンクされたユーザーアカウントにアクセスするためのOAuthベアラートークンを提供します。 tokenは、以下の形式で記述します。
"token" : "atc|tokenvalue"
DirectedUserId 現時点では使用されていませんが、要素としては記述しなければなりません。Alexaに関連付けられたアカウント識別子のプレースホルダーフィールドです。 directedUserIdは、以下の形式で記述します。
"directedUserId" : "someID"

Contextオブジェクト

Contextオブジェクトは、ChangeChannelディレクティブに返されるイベントメッセージ内で状態をレポートするために使用します。Contextには、プロパティオブジェクトの配列と、複数のプロパティスキーマうちいずれか1つから取得したそのオブジェクトの状態が含まれます。Contextを使って応答イベントを送信する場合、出力される値には、ディレクティブの処理によって生じる副次的な影響がすべて含まれることを確認する必要があります。つまり、出力されるプロパティの値はディレクティブの処理によって変化した後の値である必要があります。

以下は、Alexa.ChannelControllerインターフェースを実装するエンドポイントのContextの例です。


  "context": {
    "properties": [
      {
        "namespace": "Alexa.ChannelController",
        "name": "channel",
        "value": {
          "number": 1234,
          "callSign": "callsign1",
          "affiliateCallSign": "callsign2"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
フィールド 説明
namespace プロパティのインターフェースを指定します。
name レポートに表示されるプロパティ名です。
timeOfSample プロパティ値がサンプリングされた時刻です。UTCで指定されます。文字列はISO 8601形式で、YYYY-MM-DDThh:mm:ssZとなります。
uncertaintyInMilliseconds レポートされるプロパティが不確実である期間です。プロパティ値が取得された時点からの経過時間(ミリ秒)で示します。たとえば、60秒ごとにハードウェアデバイスをポーリングすることで値を取得する場合、サンプリングされた値が不確実な期間は60000ミリ秒です。

Payloadオブジェクト

ディレクティブまたはイベントのペイロードは、ヘッダーで指定されたディレクティブの名前によって異なります。Payloadディレクティブとイベントのコンテンツの詳細は、各機能のインターフェースのドキュメントで説明します。

検出ディレクティブとイベント

ビデオスキルでは、まず最初にユーザーのデバイスの検出を有効にし、スキルがデバイスを制御できる機能をレポートします。検出リクエストと応答のメッセージは他の種類のメッセージとは若干異なります。検出のメッセージ形式の詳細については、Alexa.Discoveryを参照してください。

そのほかのディレクティブとイベント

インターフェース別のドキュメントでは、デバイスやサービスの制御に関連するディレクティブとイベントのペイロードについて説明しています。

操作 機能インターフェース
デバイスのチャンネルを変更します Alexa.ChannelController
早送り、早戻り、一時停止など、デバイスの再生を制御します Alexa.PlaybackController
アプリまたはショートカットを起動します Alexa.Launcher
現在再生しているビデオコンテンツを録画します Alexa.RecordController
ビデオコンテンツの録画を予約します Alexa.VideoRecorder
ビデオの特定の位置をシークします Alexa.SeekController
ビデオコンテンツの検索と再生を行います Alexa.RemoteVideoPlayer
エラーが発生したことを示します 一般的なエラー: Alexa.ErrorResponse
ビデオ特有のエラー: Alexa.Video.ErrorResponse

日付と時刻の形式

メッセージの日付と時刻はISO 8601形式の文字列です。

例:

  • 日付のみ: 2016-09-13
  • 日付と時刻(UTC):
    • 2016-09-13T20:11:32+00:00
    • 2016-09-13T20:11:32Z
    • 20160913T201132Z
  • 日付と時刻(PDT): 2016-09-13T20:11:32-07:00
  • 週: 2016-W37
  • 日付と週数: 2016-W37-2
  • 年なしの日付:--09-13
  • 序数の日付: 2016-257