このトピックでは、Media API の search_videos メソッドを使用して、メディア ライブラリにある動画を見つける方法について説明します。Media API の読み取りメソッドには、比較的簡単に検索が実行できるメソッド群（find_video、find_video_by_id など）が含まれます。search_videos メソッドでは、より複雑な検索ができます。search_videos を使用すると、（カスタム フィールドを含む）動画オブジェクトのフィールドの多くの組み合わせによって検索できます。また、検索語を組み合わせて、任意の検索語に一致、すべての検索語に一致、またはどの検索語にも一致しない場合に動画を返すように検索できます。
Media API リファレンスでは、search_videos メソッドと使用される全パラメータ、および search_videos メソッドが返す ItemCollectionobject の全プロパティを説明しています。このメソッドのシグネチャは以下のとおりです。
search_videos(token:String, all:List, any:List, none:List, sort_by:List, exact:Boolean,
page_size:Integer, page_number:Integer, get_item_count:Boolean,
video_fields:List, custom_fields:List, media_delivery:Enum, output:Enum):ItemCollection
読み取りメソッドなので、お持ちのアカウントの Media API 読み取りトークンを使用してください。
動画の検索が可能なフィールドを組み合わせて値を検索することができます。field:value のフォーマットで検索したいフィールドおよび値を指定します。たとえば、名前に alien が含まれる動画を検索するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234. &all=display_name:alien
フィールド名を省略すると、このメソッドは、動画名、短い説明、および長い説明を検索します。たとえば、名前、短い説明、または長い説明に単語「alien」が含まれる動画を検索するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=alien
search_videos メソッドを使って、動画の次のフィールドを検索できます。
| search_videos コマンドのフィールド名 | Video オブジェクトのプロパティ名 |
|---|---|
| display_name | displayName |
| reference_id | referenceId |
| tag | tag |
| custom_fields | customFields |
| search_text | searchText |
search_text フィールド名は、動画の displayName、shortDescription、および longDescription フィールドを検索する場合と同等です。また、フィールド名をすべて省略する場合と同等です。
custom_fields フィールド名は、アカウントに定義されたカスタム メタデータ フィールドをすべて検索する場合と同等です。カスタム フィールドを設定する場合、標準の動画やプレイリストのフィールド名と同じフィールド名を使用しないでください。標準フィールドと名前が同じカスタム フィールドを検索しても、標準フィールドだけが検索されます。category という名前は、標準フィールドに予約されていることに注意してください。そのため category という名のカスタム フィールドを検索しても、カスタム フィールドは検索されません。
完全一致検索、つまり exact 引数が true に設定され、パーセント、ダッシュ、フォワード スラッシュ、丸括弧、下線、大なり記号、小なり記号が完全にサポートされています。これらの文字を含む完全一致検索は、完全に一致する文字を含むテキストすべてを返します。あいまい検索では、exact 引数が false に設定され、パーセント、ダッシュ、フォワード スラッシュ、丸括弧、下線、大なり記号、小なり記号が無視されて検索に影響を与えません。たとえば He's 100% Dog のあいまい検索では、He's 100 Dog のあいまい検索と同じ結果が返されます。
注意:exact を false に設定して searchText を検索しすべての動画が返される場合のみ、これらの特殊文字を検索条件として入力します。つまり、searchText フィールドの非完全検索で % を検索すると、すべての動画が返されます。
all、any、および none 引数を使用して、使用する検索基準を指定します。
複雑な検索には all、any、および none 引数を組み合わせることができます。たとえば、名前に jobs が含まれ、Steve が含まれない動画を検索するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=display_name:jobs&none=display_name:steve
検索語は大文字と小文字を区別しません。gibbous、GIBBOUS、Gibbous のどれを検索語に使用しても、結果は同じになります。
exact 引数は、動画の値が、検索基準の値と正確に一致しなければならないかどうかを指定します。exact=false（デフォルト）を使用すると、値は正確に一致する必要はありません。たとえば、exact=false では、値 run を検索すると、値 runs および running もヒットします。一致は単語の部分一致ではなく言語学的語幹規則に基づいており、run の検索で runt あるいは rung が返されることはありません。このリリースでは、この機能は英語についてのみ機能します。アカウントの地域が米国でなければ、検索はすべて exact=true として実行されます。
search_videos メソッドは、検索基準と一致する動画をすべて含む ItemCollection オブジェクトを返します。性能を最大限に発揮するには、返される動画の数（ページングを使用する）および返される動画のプロパティ（(video_fields 引数を使用する）の両方について、結果を限定する必要があります。
search_videos メソッドが返す動画はページでグループ化されています。page_size 引数により、ページ当たりの返された動画の数を指定できます。最大ページ サイズは 100 です。この引数を設定しないか、100 より大きい整数に設定すると、page_size=100 の設定で結果が返されます。
page_number 引数によって、多数の結果の中の特定のページにアクセスできます。page_number は 0 から始まります。したがって、結果の 4 ページ目を希望する場合は、page_number=3 とします。
get_item_count 引数が true の場合、メソッドは、結果集合の動画の総数を返します。この数を使用して、結果が何ページあるか確認できます。
video_fields 引数によって、検索で返された Video オブジェクトの、どのフィールドにデータを読み込むか指定できます。この引数を使用して、実際に使用したい情報だけを得ることできます。
カスタム メタデータ フィールドを使用している場合、オプションの custom_fields 引数を使用して、どのカスタム メタデータ フィールドを返してもらうかを指定できます。さらに、video_fields 引数に値 customFields を含めると、自分のアカウントの動画に定義したカスタム メタデータ フィールドをすべて取得できます。
sort_by 引数を使用して結果を並び替えることができます。この引数はリストを取得します。リストの各項目はフィールドと SortOrderType（昇順の ASC または 降順の DESC）が対になっています。DISPLAY_NAME、REFERENCE_ID、PUBLISH_DATE、CREATION_DATE、MODIFIED_DATE、START_DATE、PLAYS_TRAILING_WEEK、PLAYS_TOTAL フィールドで並び替えができます。例：
日付の並び替えや検索はミリ秒単位で行われます。したがって Media モジュール内の公開日が同じ動画が、並び替え目的に異なる公開日を持っている可能性があります。
重要:search_videos メソッドの並び替え構文は、別の Media API 読み込みメソッドの並び替え構文とは異なります。search_videos メソッドは、上の例のように昇順か降順の並び替え順を含む sort_by 引数を使用します。複数の動画を返す他の Media API 読み込みメソッドには、次の例のように sort_by 引数と sort_order 引数を別々に使用するものがあります。
http://api.brightcove.co.jp/services/library?command=find_all_videos&sort_by=plays_total&sort_order=DESC&token=[token]
すべての Media API 読込みメソッドと同様に、search_videos メソッドにはオプションの出力引数があります。デフォルトでは search_videos からの結果は JSON フォーマットになります。output=mrss を設定すると、MRSS フォーマットで結果を取得することができ、これをフィードとして公開できます。詳細は、Media API からの RSS 出力を参照してください。
次の各例は、Media API トークン用のプレースホルダーを使用しています。これらの例を使用する場合は、自分の Video Cloud アカウントの Media API 読み込みトークンを使用してください。
名前、短い説明、または長い説明に「football」および「Chicago」が含まれ、さらにタグに「free」がある動画をすべて見つけたいとします。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=football&all=chicago&all=tag:free
前の検索を、タグに「color」または「technicolor」がある動画に限定します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=football&all=chicago&all=tag:free&any=tag:color&any=tag:technicolor
タグに「black_and_white」がある動画をすべて除外するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=football&all=chicago&all=tag:free&none=tag:black_and_white
自分のアカウントの動画に「season」という名前のカスタム フィールドがあり、このフィールドは、値が「Fall 2009」、「Winter 2009」、「Winter 2010」、または「Spring 2010」の列挙型だとします。2009 年秋の動画を検索するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=football&all=chicago&all=tag:free&all=season:Fall+2009&exact=true
2009 年のいずれかのシーズンの動画を検索するには、以下を入力します。
http://api.brightcove.co.jp/services/library?command=search_videos&token=1234.
&all=football&all=chicago&all=tag:free&all=season:2009