開発者コンソール

GetPlayableItemsMetadataディレクティブ


GetPlayableItemsMetadataディレクティブ

GetPlayableItemsに対するLambdaのレスポンスをAlexaが受信すると、すぐにVideoContentProvider APIがGetPlayableItemsMetadataディレクティブを送信します。このディレクティブは、GetPlayableItemsで返されたアイテムのメタデータを取得するためのフォローアップとして送信されます。

下の図は、Alexaディレクティブとそれに対するLambdaのレスポンスを示しています。

GetPlayableItemsMetadataItemsディレクティブとLambdaのGetPlayableItemsMetadataResponse

GetPlayableItemsMetadataディレクティブの発話

GetPlayableItemsMetadataディレクティブの送信をAlexaに促すような発話はありません。このディレクティブは、GetPlayableItemsに対するLambdaのレスポンスを受信したAlexaがフォローアップとして送信します。

GetPlayableItemsMetadataディレクティブの処理

GetPlayableItemsMetadataの目的は、リクエストされたアイテムの再生を開始するうえで必要なメタデータを取得することです。Alexaが正しい音声レスポンスを提供してコンテンツの再生を開始できるよう、Lambdaのレスポンスには基本的なメタデータを含める必要があります。

GetDisplayableItemsMetadataと同様に、GetPlayableItemsMetadataディレクティブに含まれるのは、Alexaが(メディアを再生するために)メタデータを必要としているコンテンツのid値だけです。検索結果の表示に必要となるメタデータは一切レスポンスに含めないでください。

GetPlayableItemsMetadataの例

GetPlayableItemsMetadataディレクティブの例を次に示します。この例では、recordingId://provider1.dvr.rp.1234-2345-63434-asdfを値に持つmediaIdentifierのメタデータをAlexaがリクエストしています。返すのはGetPlayableItemsMetadataディレクティブで指定されたエンティティid値のメタデータのみです。

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "ja-JP",
            "mediaIdentifier": {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                }
        }
    }
}

チャンネル変更に使用されるGetPlayableItemsMetadataディレクティブもほぼ同じですが、mediaIdentifieridが異なる場合があります。その例を次に示します。

"payload": {
    "locale": "ja-JP",
    "mediaIdentifier": {
            "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
        }
}

このケースでは、idが特定のメディアタイトルではなくチャンネルに関連付けられています。

Lambdaのレスポンス

Lambdaのレスポンス(GetPlayableItemsMetadataResponse)には、再生に必要となるメタデータ情報と、ビデオの再生前に成功のプロンプトを提供するために必要となるメタデータ情報のみを含める必要があります。GetPlayableItemsMetadataResponseGetDisplayableItemsMetadataResponseはよく似ていますが、GetPlayableItemsMetadataResponseにはplaybackContextTokenが存在します。このトークンには、Alexaがウェブプレーヤーに渡す識別子が含まれています。playbackContextTokenは、対象のメディアに関して開発者が決定する識別子です。

AlexaがplaybackContextTokenをウェブプレーヤーに送信すると、その識別子がウェブプレーヤーで再生URLに変換されます。このプロセスについては、手順4: ウェブプレーヤーでメディア再生URLを取得する方法を理解するで説明しています。前出のコード例で、playbackContextTokenが文字列化されたオブジェクト(streamUrlパラメーターとtitleパラメーターから成るキーと値のペア)になっているのは、この形式がサンプルウェブプレーヤーで想定されているためです。

"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",

この識別子を処理するウェブプレーヤーのコーディングによっては、単純に文字列などの形式を使用することもあります。

ON_DEMAND(VOD)メディアのレスポンスは、LIVE(リニア)メディアのレスポンスとは異なります。contentTypeが異なるだけでなく、LIVEのレスポンスにはnetworkDetailsが含まれます。

レスポンスの例:オンデマンドのテレビ番組

ビデオオンデマンド(VOD)コンテンツのレスポンスの例を次に示します。

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "ビッグバン・セオリー",
                    "contentType": "ON_DEMAND",
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "2",
                        "seriesName": "ビッグバン・セオリー",
                        "episodeName": "ターミネーターキャメロンVSオタクの法則"
                    },
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "absoluteViewingPositionMilliseconds": 1232340
                }
            ]
        }
    }
}

レスポンスの例:ライブの映画

ライブコンテンツのレスポンスの例を次に示します。

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "インターステラー",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "代替チャンネル名"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

レスポンスの例:チャンネル変更のシナリオ

チャンネル変更のシナリオでのレスポンスの例を次に示します。

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "インターステラー",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "代替チャンネル名"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true"
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

ペイロードの説明

次の表は、GetPlayableItemsMetadataResponseレスポンスのペイロードについて説明しています。

ペイロードの説明
フィールド 説明 データ型
searchResults
(必須)
検索結果のリスト。 リスト
name
(必須)

ビデオの名前。再生されるビデオについてのプロンプトをユーザーに提供する目的で使用します。たとえば、「インターステラーはこちらです」などです。

例: インターステラー

文字列
contentType
(必須)

ContentTypeは、検索結果で返されたビデオのコンテンツタイプを示します。録画された映画やテレビ番組を送信する場合、contentTypeRECORDINGに設定されます。ライブのテレビ番組に関する情報が結果に含まれる場合、contentTypeLIVEに設定されます。オンデマンドコンテンツが結果に含まれる場合、contentTypeON_DEMANDに設定されます。

contentTypeは、ユーザーにプロンプトを提供する際にも使用されます。たとえば、contentTypeLIVEの場合、「CBSで現在放送中のアカデミー賞はこちらです」などのプロンプトがAlexaから提供されます。 contentTypeRECORDINGの場合は、「アカデミー賞はこちらです」などのプロンプトが提供されます。

例: RECORDINGLIVEON_DEMAND

列挙型
playbackContextToken
(必須)

その後の識別のためにエンティティをシステムに逆マッピングするためのトークン。開発者側で逆マッピングによってエンティティを識別できれば、どのような文字列識別子を送信しても構いません。このトークンはAlexaからは認識できず、再生目的でデバイスに送信されます。メタデータ情報を取得したときと同じメディア識別子が再生に必要であれば、それを使用して構いません。または、再生に必要な追加情報を含んだ別の文字列をシリアル化して使用することもできます。

注: サンプルウェブプレーヤーを使用する場合、playbackContextTokenは文字列に変換したJSONオブジェクトにする必要があります。このオブジェクトには、streamUrltitleのキーと値のペアを含める必要があります。詳細については、手順4: ウェブプレーヤーでメディア再生URLを取得する方法を理解するを参照してください。

不透明型の文字列
parentalControl
(必須)

ユーザーとビデオに基づくペアレンタルコントロール情報。

オブジェクト
pinControl
(必須)

このフィールドは、このビデオのユーザーに対して、設定に基づくペアレンタルコントロールが必要であるかどうかを示します。次の2つの値を取る列挙値です。

  • REQUIRED: ユーザーの設定に基づくペアレンタルコントロールがこのアイテムに適用されることを意味します。これが設定されている場合は、アイテムにロックアイコンが表示されます。これにより、そのアイテムにはペアレンタルコントロールが適用されており、ユーザーがビデオを視聴するにはPINの入力が必要であることがわかります。
  • NOT_REQUIRED: ユーザーの設定に基づくペアレンタルコントロールがこのアイテムには適用されないことを意味します。

例: REQUIREDNOT_REQUIRED

列挙型
networkDetails

番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組(contentType = LIVE)である場合は、そのメタデータがこのオブジェクトに格納されます。

リスト
channel

ビデオを放送しているチャンネルに関する情報。

オブジェクト
callSign(channel)
PBSなどのコールサインでチャンネルを指定します。

例: PBS

文字列
affiliateCallSign(channel)
KCTS9などの地方系列局のコールサインでチャンネルを指定します。

例: KCTS9

文字列
channelMetadata

指定されたチャンネルの追加情報を指定します。

オブジェクト
name(channelMetadata)
「FOX」などのチャンネルを識別する別の値。 文字列
airingDetails

このオブジェクトには、コンテンツがいつ放送されるかの情報が含まれます。

リスト
isLiveBroadcast

このコンテンツがリアルタイムで放送されているかどうか。NFLフットボールの試合中継や、アカデミー賞、エミー賞のような授賞式など、リアルタイムで放送されるライブイベントの場合は、trueに設定します。

実際に放送される時刻よりも前に撮影されたコンテンツの場合は、falseに設定します(毎週木曜日に放送される「ビッグバン・セオリー」の新しいエピソードなど)。また、リアルタイムでは二度と行われない過去のフットボールの試合など、一度リアルタイムで配信されたコンテンツの場合も、falseに設定する必要があります。

例:truefalse

ブール型
start

タイムウィンドウの開始時刻。

例: 2016-09-07T23:59:00+00:002018-01-24T02:30:00Z

ISO 8601形式の文字列
end

タイムウィンドウの終了時刻。

例: 2016-09-07T23:59:00+00:002018-01-24T02:30:00Z

ISO 8601形式の文字列
networkDetails

番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組(contentType = LIVE)である場合は、そのメタデータがこのオブジェクトに格納されます。

リスト
series

シリーズに関するメタデータ(このアイテムがシリーズの一部である場合)。この情報は、テレビ番組にのみ設定してください。ここに値が設定されている場合は、その情報を使用してユーザーにプロンプトが提供されます(例:「『ビッグバン・セオリー』のシーズン1、エピソード4はこちらです」)。

オブジェクト
seasonNumber(series)

ビデオのシーズン番号。

例: 1

文字列
episodeNumber(series)

ビデオのエピソード番号。

例: 3

文字列
episodeName(series)

エピソード名。

例: 4

文字列
seriesName(series)
文字列
absoluteViewingPositionMilliseconds
(必須)

ユーザーの視聴履歴に基づいたビデオの進行状況オフセット(ミリ秒)。ユーザーに視聴履歴がある場合、このフィールドが表すオフセットは0より大きくなります。結果アイテムで進行状況バーを表示して、ユーザーが以前どこまで視聴したかを示す目的で使用されます。

例: 1248625

長整数