開発者コンソール
ログイン
ログイン
開発者コンソール

GetPlayableItemsMetadataディレクティブ（VSK Echo Show）

GetPlayableItemsMetadataディレクティブ (VSK Echo Show)

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ディレクティブもほぼ同じですが、mediaIdentifierのidが異なる場合があります。その例を次に示します。

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

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

advertisingオブジェクト

advertisingオブジェクトは、ユーザーの広告IDと、インタレストベース広告の受信に関する設定を提供します。Alexaはビデオスキルへのリクエストにadvertisingオブジェクトを追加して、広告を配信することを宣言します。詳しくは、Alexa広告IDについての説明を参照してください。

Alexaの広告IDを取得するには、そのスキルが広告を配信することを表明し、プライバシーポリシーを公開して、スキルの再認定を申請する必要があります。

advertisingオブジェクトの構造

プロパティ 説明 型 必須・任意
advertisingId ユーザーによるリセットが可能な一意の識別子であり、OpenRTB API仕様のifa属性に該当します。バージョン4 UUID文字列の形式で表され、ダッシュで区切られます（8-4-4-4-12）。例： E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367 文字列 必須
limitAdTracking ユーザーがインタレストベース広告の受信を希望しているかどうかを示します。ユーザーがインタレストベース広告をオプトアウトしている場合はtrueに設定されます。limitAdTrackingプロパティは、OpenRTB API仕様のlmt属性に該当します。 ブール型 必須
設定例

以下は、ユーザーがインタレストベース広告を受信しないように選択した場合の設定例です。

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": true
}

"advertising": {
    "advertisingId": "00000000-0000-0000-0000-00000000",
    "limitAdTracking": true
}

以下は、ユーザーがインタレストベース広告の受信を選択した場合の設定例です。

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": false
}

広告配信に必要なビデオスキルAPI

再生中にインストリーム広告が表示されるようにするため、以下のAlexaビデオスキルAPIでは、GetPlayableItemsMetadataペイロードにrequestContextオブジェクトを追加しています。

このオブジェクトには、広告配信に関するユーザーの設定を示す広告コンテキストが含まれます。advertisingオブジェクトを使用できるように、該当するAPIでスキルのコードを更新してください。これらのAPIの詳細については、Alexaから送信されるディレクティブを参照してください。

リクエストごとにadvertisingオブジェクトを使用するようにスキルを設計します。コードで、advertisingIdにアクセスする前に、limitAdTrackingフラグを検証するコードを挿入します。limitAdTracking == trueの場合、ユーザーの選択を尊重してトラッキングを無効にする必要があります。

スキルセッション中またはスキルセッション後に、ユーザーが自分のIDをリセットして、インタレストベース広告の受信に関する設定を変更する可能性があるため、広告のプロパティをキャッシュに格納しないでください。Alexaは、スキルへの次のリクエストで最新の値を送信します。ユーザーから明示的な同意を得ていない限り、以前のadvertisingIdや、以前のadvertisingIdに割り当てられている値に新しいadvertisingIdを関連付けないでください。また、ユーザーから明示的な同意を得ていない限り、個人データをadvertisingIdに関連付けないでください。

ユーザーがインタレストベース広告を受信しないことを選択した場合、advertisingIdを分析で使用することは可能ですが、トラッキングとインタレストベース広告を無効にする必要があります。リクエストによっては、advertisingオブジェクトが含まれない可能性があります。advertisingIdを使用する場合と、使用しない場合を想定してスキルを設計してください。ユーザーのオプトアウトの選択に従う必要があります。

GetPlayableItemsMetadataリクエストの例

以下は、advertisingオブジェクトを使用したGetPlayableItemsMetadataリクエストの例です。

{

    "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"
            },
            "requestContext": {
                "advertising": {
                    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
                    "limitAdTracking": false
                }
            }
        }
    }
}

Lambdaレスポンス

Lambdaのレスポンス（GetPlayableItemsMetadataResponse）には、再生に必要となるメタデータ情報と、ビデオの再生前に成功のプロンプトを提供するために必要となるメタデータ情報のみを含める必要があります。GetPlayableItemsMetadataResponseとGetDisplayableItemsMetadataResponseはよく似ていますが、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",
                                     "start": "2018-01-24T00:00:00Z",
                                     "end": "2018-01-24T02:30: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",
                                     "start": "2018-01-24T00:00:00Z",
                                     "end": "2018-01-24T02:30:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

ペイロードの説明

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

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

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



例： インターステラー

 文字列

（省略可能）

contentType
（必須）

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

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



例： RECORDING、LIVE、ON_DEMAND

 列挙型
playbackContextToken
（必須）

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

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

 不透明型の文字列
parentalControl
（必須）

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

 オブジェクト
pinControl
（必須）

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

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



例： REQUIRED、NOT_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に設定する必要があります。



例：true、false

 ブール型
start
（省略可能）

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



例： 2016-09-07T23:59:00+00:00、2018-01-24T02:30:00Z

 ISO 8601形式の文字列
end
（省略可能）

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



例： 2016-09-07T23:59:00+00:00、2018-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

 長整数