開発者コンソール

GetDisplayableItemsMetadataディレクティブ


GetDisplayableItemsMetadataディレクティブ

GetDisplayableItemsに対するLambdaのレスポンスをAlexaが受信すると、すぐにVideoContentProvider APIがGetDisplayableItemsMetadataディレクティブをLambdaに返します。GetDisplayableItemsMetadataディレクティブの目的は、コンテンツを再生することではなく、検索結果を適切に表示するための情報を取得することです。

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

GetDisplayableItemsMetadataディレクティブとLambdaのGetDisplayableItemsMetadataResponse

GetDisplayableItemsMetadataディレクティブの発話

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

GetDisplayableItemsMetadataディレクティブの処理

Alexaは、検索結果をデバイスで表示する直前にGetDisplayableItemsMetadataを送信します。したがって、Alexaからこのディレクティブが送信されるシナリオは、検索、閲覧、ランディングページのいずれかとなります。

このディレクティブに含まれるのは、Alexaがメタデータを必要としているid値のリストだけです。id値は、その前に送信したGetDisplayableItemsResponseでLambdaから返したものです。

LambdaのGetDisplayableItemsResponseレスポンスには、アイコン、バッジselectionActionなどに関するメタデータのほか、ユーザーに対するAlexaの音声レスポンスのメタデータを含める必要があります。

ユーザーに表示するアートワークは、タイトルにふさわしいものにしてください。アートワークを使用すると、ユーザーが検索結果でおすすめのコンテンツを識別しやすくなります。

GetDisplayableItemsMetadataの例

GetDisplayableItemsMetadataディレクティブの例を次に示します。

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetDisplayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "ja-JP",
            "mediaIdentifiers": [
                {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf",
                    "displayContext": {
                        "imageWidth": "480px",
                        "imageHeight": "270px",
                        "imageAspectRatio": "16:9",
                        "imageSize": "MEDIUM"
                    }
                },
                {
                    "id": "channelId://provider1.channel.rp.1234-2345-63435-asdf",
                    "displayContext": {
                        "imageWidth": "480px",
                        "imageHeight": "270px",
                        "imageAspectRatio": "16:9",
                        "imageSize": "MEDIUM"
                    }
                }
            ]
        }
    }
}

ペイロードの説明

次の表は、GetDisplayableItemsMetadataディレクティブのpayloadフィールドについて説明しています。

ペイロードの説明
フィールド 説明 データ型



Lambdaのレスポンス

Lambdaのレスポンスにはメタデータ情報が含まれている必要があります。この情報は、(Amazonが提供する)デバイスでテンプレートに値を設定し、画面に検索結果を表示するうえで必要となります。レスポンスに含まれるのは、表示に関連した情報だけです。この場合、再生に関する情報は必要ありません。 

レスポンスの例

Lambdaから送信されるGetDisplayableItemsMetadataResponseの例を次に示します。このレスポンスには、デバイスに表示するアイテムのid値のリストが含まれています。

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetDisplayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "ビッグバン・セオリー",
                    "contentType": "ON_DEMAND",
                    "releaseYear": "2014",
                    "selectionAction": "BROWSE",
                    "thumbnailImage": {
                        "contentDescription": "ビッグバン・セオリーの画像",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "2時間49分"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "字幕"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "ビッグバン・セオリー",
                        "episodeName": "パイロット"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "購入オプション",
                    "reviews": [
                        {
                            "totalReviewCount": 41951,
                            "type": "FIVE_STAR",
                            "ratingDisplayString": "4.06"
                        }
                    ],
                    "rating": {
                        "category": "PG-13"
                    }
                },
                {
                    "name": "ビッグバン・セオリー",
                    "contentType": "LIVE",
                    "releaseYear": "2011",
                    "selectionAction": "PLAY",
                    "thumbnailImage": {
                        "contentDescription": "ビッグバン・セオリーの画像",
                        "sources": [
                            {
                                "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                                "size": "SMALL",
                                "widthPixels": 720,
                                "heightPixels": 480
                            }
                        ]
                    },
                    "runtime": {
                        "runTimeInMilliseconds": 120931123,
                        "displayString": "30分"
                    },
                    "closedCaption": {
                        "status": "AVAILABLE",
                        "displayString": "字幕"
                    },
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "1",
                        "seriesName": "ビッグバン・セオリー",
                        "episodeName": "パイロット"
                    },
                    "absoluteViewingPositionMilliseconds": 0,
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "viewingDisplayString": "今すぐ再生",
                    "rating": {
                        "category": "TV-PG"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "number": "1234",
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9",
                                "uri": "someUrl"
                            },
                            "channelMetadata": {
                                "name": "代替チャンネル名",
                                "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true",
                                     "end": "2018-01-24T02:30:00Z",
                                     "start": "2018-01-24T00:00:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

レスポンスのペイロードの例

GetDisplayableItemsMetadataResponsepayloadオブジェクトには、メディアに応じてさまざまなフィールドが格納されます。次のレスポンス例は、各種メディアのpayloadを示しています。

レスポンスのペイロードの例:オンデマンドの映画

{
    "payload": {
        "searchResults": [
            {
                "name": "インターステラー",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "インターステラーの画像",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2時間49分"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "字幕"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "購入オプション",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

ペイロードの例:オンデマンドのテレビ番組

{
    "payload": {
        "searchResults": [
            {
                "name": "ビッグバン・セオリー",
                "contentType": "ON_DEMAND",
                "releaseYear": "2014",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "ビッグバン・セオリーの画像",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2時間49分"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "字幕"
                },
                "series": {
                    "seasonNumber": "1",
                    "episodeNumber": "1",
                    "seriesName": "ビッグバン・セオリー",
                    "episodeName": "パイロット"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "購入オプション",
                "reviews": [
                    {
                        "totalReviewCount": 41951,
                        "type": "FIVE_STAR",
                        "ratingDisplayString": "4.06"
                    }
                ],
                "rating": {
                    "category": "PG-13"
                }
            }
        ]
    }
}

ペイロードの例:ライブコンテンツ

{
    "payload": {
        "searchResults": [
            {
                "name": "インターステラー",
                "contentType": "LIVE",
                "releaseYear": "2011",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "インターステラーの画像",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2時間30分"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "字幕"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "今すぐ再生",
                "rating": {
                    "category": "PG-13"
                },
                "networkDetails": [
                    {
                        "channel": {
                            "number": "1234",
                            "callSign": "PBS",
                            "affiliateCallSign": "KCTS9",
                            "uri": "someUrl"
                        },
                        "channelMetadata": {
                            "name": "代替チャンネル名",
                            "image": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
                        },
                        "airingDetails": [
                              {
                                  "isLiveBroadcast": "true"
                                  "end": "2018-01-24T02:30:00Z",
                                  "start": "2018-01-24T00:00:00Z"
                              }
                          ]
                    }
                ]
            }
        ]
    }
}

ペイロードの例:閲覧可能なコンテンツ

{
    "payload": {
        "searchResults": [
            {
                "name": "ビッグバン・セオリー",
                "contentType": "RECORDING",
                "selectionAction": "BROWSE",
                "thumbnailImage": {
                    "contentDescription": "ビッグバン・セオリーの画像",
                    "sources": [
                        {
                            "url": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "viewingDisplayString": "エピソードを表示"
            }
        ]
    }
}

ペイロードの説明

次の表は、GetDisplayableItemsMetadataResponsepayloadフィールドについて説明しています。

ペイロードの説明
フィールド 説明 データ型












































mediaIdentifierオブジェクトからの画像サイズデータの取得

GetDisplayableItemsMetadata APIは、カタログ内のアイテムに関連する情報を返します。返されるメタデータフィールドの1つがサムネイル画像のURLです。このURLは、検索結果、ランディングページ、カテゴリー選択の画面で表示される画像を読み込む際に使用されます。また、Echo Showデバイスにはさまざまなサイズと解像度があるため、このURLによって設定される画像コンテナのサイズと解像度もさまざまです。GetDisplayableItemsMetadataが返す画像がリクエスト元のデバイスに適合しない場合、ディスプレイによっては画像がゆがむことがあります。

これを回避するには、mediaIdentifierに属するdisplayContextオブジェクトのデータを使用します。

displayContextオブジェクトのデータの使用方法

displayContextオブジェクトには、次のフィールドがあります。

フィールド 必須/任意
imageAspectRatio Ratio(文字列型)
現時点では、「2:1」「16:10」「16:9」のいずれか
必須
imageHeight dimension(文字列型)
例:「480px」
任意
imageSize 列挙型
imageSizeのプロパティを参照
必須
imageWidth dimension(文字列型)
例:「270px」
任意

リクエストのimageWidthフィールドとimageHeightフィールドにより、使用する画像のサイズを正確に把握できます。また、画像の最適なアスペクト比を指定するimageAspectRatioフィールドと、画像サイズを指定するimageSizeフィールドを使用して、画像を調整することも可能です。リクエストされた正確な比率やサイズの画像がない場合、スキルはまずimageAspectRatioを適用し、次にimageSizeを適用することで、画像を自動的に拡大・縮小します。

複数の画像を使用する場合、APIはまずimageAspectRatioでマッチングを行い、画像の伸長やトリミングを回避します。

各デバイスについて、APIが返す画像プロパティを以下に示します。開発者は、自身で決定した粒度の画像を提供することができます。たとえば、16:9の画像は、Echo Show 5を除くすべてのデバイスで拡大表示されます。ただし、各デバイスに適した解像度の画像を提供することも可能です。

imageSizeのプロパティ

以下は、imageSizeフィールドの列挙型プロパティの一覧です。

プロパティ 説明 推奨サイズ(ピクセル)
幅x高さ
X_SMALL 極小コンテナ内に表示 480x320
SMALL 小さなコンテナ内に表示 720x480
MEDIUM 中程度の大きさのコンテナ内に表示 960x640
LARGE 大きなコンテナ内に表示 1200x800
X_LARGE 特大コンテナ内に表示 1920x1280

Echo Showデバイスでサポートされる画像サイズ

サポートされる画像サイズは次のとおりです。

デバイス デバイスの解像度 ヒーロータイトルの解像度
(ピクセル)
ヒーロータイトルの
アスペクト比
検索結果の解像度
(ピクセル)
検索結果の
アスペクト比
Echo Show 10
第2世代
1280x800 1280x800 16:10 364x204 16:9
Echo Show 5 960x480 960x480 2:1 368x184 2:1
Echo Show
第1世代
1024x600 1024x600 16:10 564x320 16:9
Echo Show 8 1280x800 1280x800 16:10 522x293 16:9

リクエストの例

{
    "locale": "ja-JP",
    "mediaIdentifiers": [
        {
            "id": "recordingId://provider1.dvr.rp.1234-2345-63434-abcde",
            "displayContext": {
                "imageWidth": "480px",
                "imageHeight": "270px",
                "imageAspectRatio": "16:9",
                "imageSize": "MEDIUM"
            }
        }
    ]
}