開発者コンソール

手順7: コンテンツレシピ: queryパラメーター

手順7: コンテンツレシピ: queryパラメーター

コンテンツレシピの構成を続行して、queryパラメーターとqueryResultTypeパラメーターを設定しましょう。

queryパラメーター

JSONフィードの構文はXMLフィードの構文と大きく異なるため、この2つの形式は別々のタブに分けて説明します。この構成のquery構文は少し複雑に見えますが、Fire App Builderでは、特定の順序や仕様は要求されず、任意のフィード構造を使用できます。この柔軟性の高さから、フィード内の要素をターゲットに指定するときには、より高度なクエリ構文を使用することが必要になります。

JSON

Fire App Builderのサンプルアプリでは、queryの値は$[?(@.categories[0] in [$$par0$$])]になっています。カテゴリーレシピのqueryパラメーターと同様に、この構文は(ほぼ)Jayway JsonPath(英語のみ)の構文です。この構文では、Jayway JsonPathフィルター演算子(英語のみ)を使用して、位置0に少なくとも1つのアイテムを持つcategories配列内のアイテムを選択します。

このクエリは、独自のフィードの構文に合わせてカスタマイズする必要があります。そこで、この構文について改めて詳しく見てみましょう。サンプルのLightcastフィード(Fire App Builderが使用するもの)は、次のようになっています。

[  
   {  
      "id":"169313",
      "title":"Beautiful Whale Tail Uvita Costa Rica",
      "description":"Beautiful Whale Tail Uvita Costa Rica",
      "duration":"86",
      "thumbURL":"http://le2.cdn01.net/videos/0000169/0169313/thumbs/0169313__007f.jpg",
      "imgURL":"http://le2.cdn01.net/videos/0000169/0169313/thumbs/0169313__007f.jpg",
      "videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169313/video_1880k/T7J66Z106.mp4?source=firetv&channel_id=13454",
      "categories":[  
         "Costa Rica Islands"
      ],
      "channel_id":"13454"
   },
   {  
      "id":"169322",
      "title":"Scuba Diving - Costa Rica",
      "description":"Scuba Diving - Costa Rica (Playa Ocotal & The Bat Islands)",
      "duration":"205",
      "thumbURL":"http://le1.cdn01.net/videos/0000169/0169322/thumbs/0169322__002f.jpg",
      "imgURL":"http://le1.cdn01.net/videos/0000169/0169322/thumbs/0169322__002f.jpg",
      "videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169322/video_1880k/S6IZ6M1QM.mp4?source=firetv&channel_id=13455",
      "categories":[  
         "Costa Rica Underwater"
      ],
      "channel_id":"13455"
   },
   {  
      "id":"169312",
      "title":"San Lucas Trip",
      "description":"Isla San Lucas, Puntarenas, Costa Rica",
      "duration":"192",
      "thumbURL":"http://le1.cdn01.net/videos/0000169/0169312/thumbs/0169312__003f.jpg",
      "imgURL":"http://le1.cdn01.net/videos/0000169/0169312/thumbs/0169312__003f.jpg",
      "videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169312/video_1880k/M0CAAG18G.mp4?source=firetv&channel_id=13454",
      "categories":[  
         "Costa Rica Islands"
      ],
      "channel_id":"13454"
   },
   {  
      "id":"169309",
      "title":"San Jose, Costa Rica",
      "description":"San Jose, Costa Rica",
      "duration":"130",
      "thumbURL":"http://le2.cdn01.net/videos/0000169/0169309/thumbs/0169309__009f.jpg",
      "imgURL":"http://le2.cdn01.net/videos/0000169/0169309/thumbs/0169309__009f.jpg",
      "videoURL":"http://edge-vod-media.cdn01.net/encoded/0000169/0169309/video_1880k/88HFXX0IL.mp4?source=firetv&channel_id=13453",
      "categories":[  
         "Costa Rica Attractions"
      ],
      "channel_id":"13453"
   }
]

(これはフィード全体ではありませんが、フィードが繰り返し構造になっていることがわかります。)

このフィードをJayway JsonPath Evaluator(英語のみ)に入力します。その後、以下のクエリを実行します。

$[?(@.categories[0] in ["Costa Rica Islands"])]

このクエリにより、次の結果が返されます。

[
   {
      "id" : "136216",
      "title" : "Falmouth Jamaica Nature's Lullaby ",
      "description" : "Falmouth Jamaica Nature's Lullaby",
      "duration" : "1813",
      "thumbURL" : "http://l4.cdn01.net/_thumbs/0000136/0136216/0136216__001f" type="jpg",
      "imgURL" : "http://l4.cdn01.net/_thumbs/0000136/0136216/0136216__001f" type="jpg",
      "videoURL" : "http://media.cdn01.net/802E1F/process/encoded/video_1880k/0000136/0136216/L2XGJI1LM.mp4?source=firetv&channel_id=13672",
      "categories" : [
         "The Country Jamaica"
      ],
      "channel_id" : "13672"
   }
]

以下に、クエリ構文の各部分によってフィード内で何が選択されるかを示します。

クエリ構文 一致する部分
$[ ルートから開始して、名前のない配列を選択します。
?(@.categories[0] in ["The Country Jamaica"])] インデックス位置0["The Country Jamaica"]を含むすべてのcategories配列に一致するフィルターを作成します。

ただし、Fire App Builderのサンプルアプリで使用されているクエリ構文には、わずかな違いが1つあります。次のように、queryパラメーターで["The Country Jamaica"]の代わりに$$par0$$が使用されています。

"query": "$[?(@.categories[0] in [$$par0$$])]"

$$par0$$は、Fire App Builderに定義されているカスタム変数です。レシピコードでは、カテゴリーレシピのkeyDataTypeパラメーターを通じて、コンテンツレシピの$par0$$変数にカテゴリーのリストが設定されます。

この動作を明らかするために、もう1つの例を見てみましょう。次のようなJSONがあるとします。

{
    "titles": {
        "video": [
            {
                "category": "リファレンス",
                "publisher": "Jess",
                "title": "ビデオタイトル1",
                "price": 3.95
            },
            {
                "category": "歴史",
                "publisher": "John",
                "title": "ビデオタイトル2",
                "price": 2.99
            },
            {
                "publisher": "Dave",
                "title": "ビデオタイトル3",
                "price": 8.99
            },
            {
                "category": "科学",
                "publisher": "Jess",
                "title": "ビデオタイトル4",
                "price": 3.99
            }
        ]
     }
}

カテゴリーとして科学を含むすべての配列を選択するには、次のクエリを使用します。

$.titles.video[?(@.category contains "科学")]

これにより、次の結果が返されます。

[
   {
      "category" : "科学",
      "publisher" : "Jess",
      "title" : "ビデオタイトル4",
      "price" : 3.99
   }
]

ただし、ここで必要としているのは、配列内でcategoryを含むすべてのアイテムです。そこで、次のように@.categoryに対する条件を削除します。

$.titles.video[?(@.category)]

次に、[$par0$$]変数を追加します。

$.titles.video[?(@.category in [$$par0$$])]

この構文の要点を以下に示します。

クエリ構文 一致する部分
$.titles.video[ titleオブジェクトとvideo配列を選択します。
?(@.category in [$$par0$$] categoryを持つすべてのアイテムに一致するように配列をフィルタリングします。

[$$par0$$]は、Jayway JsonPathの一部ではなく、Fire App Builderに固有の構文です。したがって、この構文をJayway JsonPath Evaluatorに追加しても、Evaluatorには認識されません。このクエリをテストするには、Fire App Builderで作成したアプリをFire TVで実行する必要があります。

実際のクエリは、使用するフィードと、コンテンツオブジェクトをマッチさせるために必要な構文によって異なることにも注意してください。例として、より複雑なクエリを以下に示します。

$.assets[?(@.type == 'movie.Container' && @.assetId in $$par0$$)]

このクエリは、ルート($)から開始して、最初のディレクトリレベル(.)でassetsという名前のオブジェクトを選択し、typeオブジェクトがmovie.Containerに等しく、かつassetId要素を含むという条件で配列をフィルタリングします。この複雑な例は、Jayway JsonPathの強力な機能を示しています。これを使用すれば、どのようなフィード構造の要素でもターゲットにすることができます。

XML

フィードがXMLの場合、フィードの特定の要素をターゲットにするには、Jayway JsonPathではなくXPath式(英語のみ)を使用します。XPathは、XMLドキュメントをさまざまな「ノード」に集約します。 XPath構文を使用すると、特定のノードの位置をターゲットにすることができます。

サンプルMRSS XMLアプリでは、コンテンツレシピのqueryパラメーターの値は次のようになっています。

"query": "//item[./category='$$par0$$']"

このクエリは、独自のフィードの構文に合わせてカスタマイズする必要があります。そこで、この構文について改めて詳しく見てみましょう。

サンプルのXMLフィードを以下に示します。

<rss>
    <channel>
        <item>
            <title>サンプルタイトル1</title>
            <pubDate>Wed, 26 Oct 2016 20:34:22 PDT</pubDate>
            <link>https://example.com/myshow/episodes/110</link>
            <author>サンプル作者名</author>
            <category>ガジェット</category>
        </item>

        <item>
            <title>サンプルタイトル2</title>
            <pubDate>Mon, 24 Oct 2016 09:24:12 PDT</pubDate>
            <link>https://example.com/myshow/episodes/109</link>
            <author>サンプル作者名</author>
            <category>テクノロジー</category>
        </item>
    </channel>
</rss>

このフィード構造では、コンテンツレシピのqueryを次のように指定できます。

//item[./category='$$par0$$']

このサンプルXMLフィードをXPath Tester(英語のみ)に入力します。その後、以下のクエリを実行します。

//item[./category='テクノロジー']

結果は次のようになります。

Element='<item>
        <title>サンプルタイトル2</title>
        <pubDate>Mon, 24 Oct 2016 09:24:12 PDT</pubDate>
        <link>https://example.com/myshow/episodes/109</link>
        <author>サンプル作成者名</author>
        <category>テクノロジー</category>
        </item>'

以下に、このクエリ構文の各部分が何に一致するかを示します。

クエリ構文 一致する部分
//item XML構造内での位置に関係なく、item要素のすべてのインスタンスに一致します。
?[./category='テクノロジー'] item要素の子要素であるcategoryのうち、値がテクノロジーに等しいものをすべて選択します。

ただし、Fire App Builderのサンプルアプリで使用されているクエリ構文には、わずかな違いが1つあります。次のように、queryパラメーターで["テクノロジー"]の代わりに$$par0$$が使用されています。

"query": "//item[./category='$$par0$$']"

$$par0$$は、Fire App Builderに定義されているカスタム変数です。レシピコードでは、カテゴリーレシピのkeyDataTypeパラメーターを通じて、コンテンツレシピの$par0$$変数にカテゴリーのリストが設定されます。

作成したクエリによってフィード内の特定のカテゴリーが選択されることを確認したら、カテゴリー(テクノロジーなど)を変数$par0$$に置き換えます。

この構文の要点を以下に示します。

クエリ構文 一致する部分
//item フィード内のすべてのitem要素を選択します。
[./category='$$par0$$'] categoryを持つすべてのアイテムに一致するように選択結果をフィルタリングします。

XPathクエリの作成方法の詳細については、XMLでのクエリの実行を参照してください。

名前空間付き要素のターゲット指定

queryパラメーターの構文を作成するときは、名前空間に関する以下の制限事項に注意してください。<media:category>Media RSS仕様(英語のみ)で必要)や<itunes: category text="Apples"/>iTunesのRSSタグ(英語のみ)で必要)など、名前空間付きの要素をターゲットにする場合は、すべてのXPath式が機能するとは限りません。以下の2つのセクションでは、このようなシナリオ向けのガイダンスを提供します。

Media RSSのカテゴリーの例

たとえば、Media RSS仕様に準拠した次のようなXMLフィードがあるとします。

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
   <channel>
      <title>MRSSフィードのサンプル</title>
      <link>https://some-site.com/mrss.xml</link>
      <language>ja-jp</language>
      <description>Amazonテスト用MRSSフィード</description>
      <atom:link href="https://some-site.com/mrss.xml" rel="self" type="application/rss+xml" />
      <item>
         <title>2018年5月18日 - リンゴ</title>
         <description>2018年5月18日。おいしい果物、リンゴ。リンゴの栽培と生産についての楽しいドキュメンタリーをご覧ください。</description>
         <pubDate>Thu, 31 May 2018 22:45:38 GMT</pubDate>
         <guid>https://some-site.com/apples.mp4</guid>
         <itunes:subtitle>2018年5月18日。おいしい果物、リンゴ。リンゴの栽培と生産についての楽しいドキュメンタリーをご覧ください。</itunes:subtitle>
         <media:category>農業</media:category>
         <media:content url="https://some-site.com/apples.mp4" type="application/mp4" medium="video" duration="2610.688" isDefault="true">
            <media:title>2018年5月18日 - リンゴ</media:title>
            <media:description>2018年5月18日。 おいしい果物、リンゴ。リンゴの栽培と生産についての楽しいドキュメンタリーをご覧ください。</media:description>
            <media:thumbnail url="http://some-site.com/thumbnails/apples.jpg" height="393" width="699" />
         </media:content>
      </item>
      <item>
         <title>2018年5月23日 - バナナ</title>
         <description>2018年5月23日。魅力が詰まったバナナ。バナナの栽培方法についての興味深いドキュメンタリーをご覧ください。</description>
         <pubDate>Thu, 31 May 2018 22:45:41 GMT</pubDate>
         <guid>https://sample-server..net/3023434001/2345/2335/30349384989301.mpd</guid>
         <itunes:subtitle>2018年5月23日。魅力が詰まったバナナ。バナナの栽培方法についての興味深いドキュメンタリーをご覧ください。</itunes:subtitle>
         <media:category>ライフスタイル</media:category>
         <media:content url="https://some-site.com/bananas.mp4" type="application/mp4" medium="video" duration="2610.688" isDefault="true">
            <media:title>2018年5月18日 - リンゴ</media:title>
            <media:description>2018年5月18日。魅力が詰まったバナナ。バナナの栽培方法についての興味深いドキュメンタリーをご覧ください。</media:description>
            <media:thumbnail url="http://some-site.com/thumbnails/bananas.jpg" height="393" width="699" />
         </media:content>
      </item>
   </channel>
</rss>

コンテンツレシピでアイテムをターゲットにする場合、次のクエリは使用できません。

"query": "//item/media:category/text() in $$par0$$",

これはXPath Tester(英語のみ)では機能しますが、Fire App Builderで同じXPathパーサーが使用されるわけではありません。このため、代わりに次の構文を使用する必要があります。

"query": "//item[*[name()='media:category']='$$par0$$']"

このクエリでは、itemという名前のノードをすべて調べます。Fire App Builderは、ワイルドカードを使用して、それらのノードでmedia:categoryという名前を検索します。

名前空間に関するこの特別な構文制限は、queryパラメーターにのみ適用されます。matchListパラメーターはXPath式を使用しないため、matchListでは特別な処理は必要ありません。

iTunesのRSSタグの例

たとえば、iTunesのRSSタグに準拠した次のようなフィードがあるとします。

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:media="http://search.yahoo.com/mrss/" version="2.0" xml:base="http://www.nasa.gov/">
   <channel>
      <title>サンプル1</title>
      <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit.Sed tincidunt vehicula placerat.Nunc eget auctor leo.Donec vitae neque vehicula, fermentum risus et, scelerisque felis. </description>
      <link>http://www.example.org/</link>
      <itunes:subtitle>Quisque egestas nec metus ac ullamcorper.In a semper ex, vulputate pellentesque massa.</itunes:subtitle>
      <itunes:summary>Lorem ipsum dolor sit amet, consectetur adipiscing elit.Sed tincidunt vehicula placerat.Nunc eget auctor leo.Donec vitae neque vehicula, fermentum risus et, scelerisque felis. </itunes:summary>
      <itunes:category text="果物" />
      <itunes:keywords>果物, バスケット, 農園</itunes:keywords>
      <itunes:image href="https://www.example.org/images/somelogo.png" />
      <item>
         <title>ウィークリーニュース(2018年8月11日)</title>
         <link>http://www.example.org/weeklynews/august-18-2018.html</link>
         <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit.Sed tincidunt vehicula placerat.Nunc eget auctor leo.Donec vitae neque vehicula, fermentum risus et, scelerisque felis. </description>
         <enclosure url="https://amzndevresources.com/fire-app-builder/media/bunny.mp4" length="44842035" type="video/mp4" />
         <guid isPermaLink="false">august-11-2018</guid>
         <pubDate>Sat, 11 Aug 2018 09:00 EDT</pubDate>
         <source url="http://example.org.rss">ビデオの例</source>
         <itunes:category text="リンゴ" />
         <itunes:image href="https://amzndevresources.com/fire-app-builder/media/card.png" />
      </item>     
      <item>
         <title>ウィークリーニュース(2018年8月30日)</title>
         <link>http://www.example.org/weeklynews/august-18-2018.html</link>
         <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit.Sed tincidunt vehicula placerat.Nunc eget auctor leo.Donec vitae neque vehicula, fermentum risus et, scelerisque felis. </description>
         <enclosure url="https://amzndevresources.com/fire-app-builder/media/bunny.mp4" length="44842333" type="video/mp4" />
         <guid isPermaLink="false">august-12-2018</guid>
         <pubDate>Sat, 12 Aug 2018 09:00 EDT</pubDate>
         <source url="http://example.org.rss">ビデオの例</source>
         <itunes:category text="オレンジ" />
         <itunes:image href="https://amzndevresources.com/fire-app-builder/media/card.png" />
      </item>  
   </channel>
</rss>

iTunesフィードには、フィードに適用される全般的なカテゴリー(<itunes:category text="果物">)と、アイテムごとのカテゴリー(<itunes:category text="リンゴ" />)があります。レシピでカテゴリーをターゲットにするときは、通常、全般的なフィードカテゴリーではなく、フィードの各アイテムのカテゴリーをターゲットにします。

<itunes:category text="リンゴ" />を選択するには、コンテンツレシピで次のクエリを使用します。

"query": "//item[./*[name()='itunes:category'][@text='$$par0$$']]"

これにより、目的のカテゴリー名だけでなく、パラメーターに一致するすべてのアイテムが返されます。

<item>
   <title>ウィークリーニュース(2018年8月11日)</title>
   <link>http://www.example.org/weeklynews/august-18-2018.html</link>
   <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit.Sed tincidunt vehicula placerat.Nunc eget auctor leo.Donec vitae neque vehicula, fermentum risus et, scelerisque felis. </description>
   <enclosure length="44842035"
        type="video/mp4"
        url="https://amzndevresources.com/fire-app-builder/media/bunny.mp4"/>
   <guid isPermaLink="false">august-11-2018</guid>
   <pubDate>Sat, 11 Aug 2018 09:00 EDT</pubDate>
   <source url="http://example.org.rss">ビデオの例</source>
   <itunes:category xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" text="リンゴ"/>
   <itunes:image xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"
           href="https://amzndevresources.com/fire-app-builder/media/card.png"/>
</item>

次に、レシピでmatchListパラメーター(次の手順で説明)を使用して、実際の属性を選択できます。たとえば、コンテンツレシピは次のようになります。

{
  "cooker": "DynamicParser",
  "format": "xml",
  "model": "com.amazon.android.model.content.Content",
  "translator": "ContentTranslator",
  "modelType": "array",
  "query": "//item[./*[name()='itunes:category'][@text='$$par0$$']]",
  "matchList": [
    "title/#text@mTitle",
    "guid/#text@mId",
    "description/#text@mDescription",
    "enclosure/#attributes/url@mUrl",
    "itunes:image/#attributes/href@mCardImageUrl",
    "itunes:image/#attributes/href@mBackgroundImageUrl"
  ]
}

queryResultTypeパラメーター

Fire App Builderでは、queryパラメーターから結果を取得し、HashMapに変換して、Javaクラスで処理する必要があります。結果をオブジェクトの配列に変換するには、queryResultTypeパラメーターが使用されます。Fire App Builderのサンプルアプリでは、queryResultTypeの値は次のようになっています。

"queryResultType": "[]$",

この場合、queryパラメーターの結果は文字列のリストです。構文[]$は、これらの文字列を処理できるようにHashMapに変換します。

queryパラメーターの結果が文字列のリストを返す場合は、コンテンツレシピにqueryResultTypeパラメーターを含めて、その値を[]$に設定します。クエリの結果が既にオブジェクト(マップ)である場合は、このパラメーター全体を省略します。

次のステップ

コンテンツレシピを完成させるには、matchListパラメーターとkeyDataTypeパラメーターを構成する必要があります。次の手順の コンテンツレシピ:matchListパラメーターに進みます。


Last updated: 2020年6月5日