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

Note: Sign in to the developer console to build or publish your skill.

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

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

リクエスト／応答のメッセージ
認証
ディレクティブとイベントの形式
- リクエストの例
- 応答の例
Headerオブジェクト
Endpointオブジェクト
- Scopeオブジェクト
Contextオブジェクト
Payloadオブジェクト
- 検出ディレクティブとイベント
- そのほかのディレクティブとイベント
日付と時刻の形式

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

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

認証

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

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

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

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

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

Header
Endpoint
Payload

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

Context

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`	`TurnOn`、`TurnOff`など、ディレクティブの名前です。
`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

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

フィードバックを送信