開発者コンソール

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のフィールドについて説明しています。

ペイロードの説明
フィールド 説明 データ型
locale
(必須)

ユーザーのロケール。検索結果に対応する表示可能な情報を取得するために必要となります。ロケールの形式は、Network Working Groupの「Best Current Practice 47(BCP-47)」(英語のみ)で規定されている言語の形式と同じです。認識されないロケールを受信した場合は、デフォルトでen-USになります。



例:en-USen-GBde-DE

文字列
mediaIdentifiers
(必須)

メディアのid値のリストが格納されます。

配列
id
(必須)

ビデオアイテムの識別子。後続のGetDisplayableItemsMetadataまたはGetPlayableItemsMetadataの呼び出しで、表示または再生に関連したメタデータ情報を取得する目的で使用されます。この識別子は、Alexaからは認識できず、メタデータ情報を照会する際にそのまま使用されます。

文字列

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": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "https://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": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "https://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": "https://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": "https://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": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "https://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": "https://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": "https://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": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
                            "size": "SMALL",
                            "widthPixels": 720,
                            "heightPixels": 480
                        }
                    ]
                },
                "viewingDisplayString": "エピソードを表示"
            }
        ]
    }
}

ペイロードの説明

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

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

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



例: インターステラー

文字列
contentType
(必須)

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

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



例: RECORDINGLIVEON_DEMAND

列挙型
itemType
(必須)

itemTypeは、検索するアイテムのタイプを指定します。itemTypeは、ランディングページテンプレートに関連したGetDisplayableItemsディレクティブに固有です。ユーザーが(「アレクサ、ACMEのビデオを開いて」と言うか、「ビデオホーム」と言った後でビデオスキルを選択することで)ランディングページを開くと、Alexaは次の2つのGetDisplayableItemsディレクティブを送信します。

  • 1つ目のGetDisplayableItemsディレクティブは、ランディングページのカテゴリーを取得するためのものです。itemTypeプロパティはCATEGORYで、sortTypeRECOMMENDEDに設定されています。
  • 2つ目のGetDisplayableItemsディレクティブは、ランディングページの注目ビデオを取得するためのものです。1つ目のディレクティブとは異なり、このリクエストではitemTypeVIDEOに設定されています。

Alexaは両方のディレクティブに対するレスポンス(GetDisplayableItemsResponse)を受信したら、カテゴリーIDとビデオIDを組み合わせたリストを含むGetDisplayableItemsMetadata呼び出しを1回送信します。レスポンスには、カテゴリーとビデオに関するメタデータが含まれます。



例: VIDEOCATEGORY

列挙型
releaseYear
(省略可能)

ビデオのリリース年。画面にアイテムを表示する際にリリース年を表示する目的で使用されます。



2018
文字列
selectionAction
(必須)

ユーザーがこのアイテムを選択したときのエンティティの閲覧方法についての指示です。たとえば、検索結果を送信する際、類似するアイテムをグループ化することがあります。映画やテレビ番組は、ジャンル、俳優などでグループ化できます。このような場合、グループを選択してアイテムをドリルダウンすることで、結果をさらに表示することができます。

次の列挙値を使用できます。

  • BROWSE: グループ化されたエンティティでブラウズノードアイテムを取得し、結果をさらに表示できることを意味します。この場合、Alexaは最終的に、選択されたエンティティidでGetBrowseNodeItemsを呼び出します。
  • PLAY: 指定のエンティティはグループ化されていないため、選択すれば再生できることを意味します。この場合、Alexaは最終的に、選択されたエンティティidGetPlayableItemsMetadataを呼び出します。



例: BROWSEPLAY

列挙型
thumbnailImage
(必須)

画像の情報。画面に結果アイテムの画像を表示する目的で使用されます。URLのプレフィックスはhttpsである必要があります。



例:

 {
  "contentDescription": "string",
  "sources": [
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    {
      "url": "string",
      "size": "string",
      "widthPixels": integer,
      "heightPixels": integer
    },
    { ... }
  ]
} 

オブジェクト
runtime
(省略可能)
ビデオの再生時間についての詳細。 オブジェクト
runTimeInMilliseconds
(省略可能)
ビデオの再生時間(ミリ秒)。

例: 271871324

長整数
displayString(runtime)
(省略可能)
ビデオの再生時間を表すフォーマットされた表示文字列。画面に再生時間を表示する目的で使用されます。

例: 2時間30分

文字列
closedCaption
(省略可能)
ビデオや表示情報でクローズドキャプションが利用できるかどうかについての詳細。 オブジェクト
status(closedCaption)
(省略可能)

ビデオでクローズドキャプションが利用できるかどうか。次の値を取る列挙値です。

  • AVAILABLE: ビデオでクローズドキャプションが利用できることを意味します。
  • NOT_AVAILABLE: ビデオでクローズドキャプションが利用できないことを意味します。



例: AVAILABLENOT_AVAILABLE

列挙型
displayString(closedCaption)
(省略可能)

画面に表示される、クローズドキャプションを表すフォーマットされた表示文字列。



例: 字幕

文字列
series
(省略可能)

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

オブジェクト
seasonNumber(series)
(省略可能)

ビデオのシーズン番号。



例: 1

文字列
episodeNumber(series)
(省略可能)

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



例: 3

文字列
episodeName(series)
(省略可能)

エピソード名。



例: 4

文字列
absoluteViewingPositionMilliseconds
(必須)

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



例: 1248625

長整数
parentalControl
(必須)

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

オブジェクト
pinControl
(必須)

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

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



例: REQUIREDNOT_REQUIRED

列挙型
viewingDisplayString
(省略可能)

表示文字列は結果アイテムと共に画面に表示され、すぐに再生できるのか、または購入・レンタル・定期購入などが必要なのかをユーザーに示します。非消費型アイテムのステータスに基づいて、異なる文字列を使用できます。この文字列は、リクエストで送信されたロケールに基づいてローカライズする必要があります。



例: 今すぐ再生定期購入

文字列
reviews
(省略可能)
ビデオのレビューに関する情報。 リスト
totalReviewCount
(省略可能)
ビデオの合計レビュー数。

例: 13425

長整数
type(review)
(省略可能)
情報の基となるレビューのタイプ。

例: FIVE_STAR

列挙型
ratingDisplayString
(省略可能)
上記のタイプとレビューに基づくビデオの評価。検索結果に含まれる各アイテムの下にその評価を表示する目的で使用されます。

例: 4.06

文字列
rating
(省略可能)
ビデオのレーティングに関連した情報。 オブジェクト
ratingCategory
(省略可能)
ビデオのレーティングカテゴリー(PG-13など)。このレーティングはこのビデオが視聴される地域で適用されます。また、レーティングの値はコンテンツによっても異なる場合があります。たとえば、映画の場合はMPAAレーティング(「PG-13」など)を、テレビ番組の場合はテレビレーティング(「TV-PG」など)を送信できます。

例: PG-13TV-PG

文字列
recording
(省略可能)

録画に関連する情報。現在のところ、構造体のフィールドはstatusの1つのみです。単独のフィールドではなく構造体にしている理由は、将来Alexa Skills Kitによって、recording構造体にほかの情報が追加される可能性があるためです。オブジェクトとして利用できるようにすることで、Alexa Skills Kitでこうしたアイテムをグループ化し、将来の要件に合わせて拡張することが可能になります。

オブジェクト
status(recording)
(省略可能)

コンテンツの録画ステータス。次の列挙値を使用できます。

  • RECORDED: コンテンツが以前に録画されたことを意味します。
  • RECORDING: リクエストの時点でコンテンツが意図的に録画されていることを意味します。
  • SCHEDULED: コンテンツが将来録画されるようにスケジュールされていることを意味します。



例: RECORDEDRECORDINGSCHEDULED

文字列
contentFreshness
(省略可能)

コンテンツの鮮度についての詳細。

オブジェクト
state(contentFreshness)
(省略可能)

Alexaに結果を返しているプロバイダーの新しいコンテンツであるかどうか。使用できる列挙値はNEWのみです。これは、コンテンツが新しいもので、そのプロバイダーでの初回放送であることを意味します。



例: NEW

文字列
networkDetails
(省略可能)

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

リスト
channel
(省略可能)

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

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

例: PBS

文字列
affiliateCallSign(channel)
(省略可能)
KCTS9といった地方系列局のコールサインでチャンネルを指定します。

例: KCTS9

文字列
uri(channel)
(省略可能)
チャンネルのURIです(「entity://provider/channel/12307」など)。
channelMetadata
(省略可能)

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

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


例:http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg

文字列
airingDetails
(省略可能)

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

リスト
isLiveBroadcast
(省略可能)

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

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



例:truefalse

ブール型
end
(省略可能)

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



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

ISO 8601形式の文字列
start
(省略可能)

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



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

ISO 8601形式の文字列
mediaIdentifier
(必須)

mediaItemの識別子。mediaIdentifierオブジェクトからの画像サイズデータの取得を参照してください。

オブジェクト

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

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

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

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

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

フィールド 必須/任意
imageAspectRatio 比率(文字列型)
現時点では、「2:1」「16:10」「16:9」のいずれか
必須
imageHeight サイズ(文字列型)
例:「480px」
任意
imageSize 列挙型
imageSizeのプロパティを参照
必須
imageWidth サイズ(文字列型)
例:「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"
            }
        }
    ]
}