サポート サポートへのお問い合わせ | システムステータス システムステータス
ページコンテンツ

    CMS /再生 API:ビデオ検索 v1

    このトピックでは、CMS API を使用してアカウント内の動画を検索する方法について説明します。ザ・CMS API VideoCloudライブラリでビデオを検索するプログラム的な方法を提供します。このトピックでは、検索構文について詳しく説明します。注：これは元の検索構文です-より単純なものを使用することをお勧めしますビデオ検索構文v2。

    はじめに

    このトピックでは、次の方法を学習します。

    • を使用して基本的な検索を作成および制限しますqパラメータ
    • 検索結果を並べ替える
    • 必須および除外された用語を使用して検索
    • 引用符で囲まれた検索を使用して、正確な用語と複数の単語を照合します
    • カスタムフィールドで検索
    • 特定の日付と範囲の日付フィールドを検索する
    • 検索条件を組み合わせる

    APIの使用法

    検索機能は、次のいずれかで使用できます。CMS APIまたはPlaybackAPI。

    CMS API

    CMS APIで検索を使用する場合、以下が適用されます。

    • すべてのリクエスト（検索を含む）には、アクセストークンを含む認証ヘッダーが必要です。クライアントクレデンシャルを取得してアクセストークンを取得する方法の詳細については、「 Brightcove OAuth の概要」を参照してください。
    • 検索から返される動画の最大数に制限はありませんが、レート制限が適用されます。
    • 検索結果には、再生可能かどうか、地理的に制限されているかどうかに関係なく、アカウント内のすべての動画が含まれます。

    APIリクエスト/レスポンスの詳細については、ビデオを入手のセクションCMSAPIリファレンス。

    再生API

    再生APIで検索を使用する場合、以下が適用されます。

    • 再生 API での検索リクエストには、検索が有効なポリシーキーが必要です。
    • あります制限検索から返される動画の最大数。
    • 検索結果には、再生可能な動画のみが返されます（state:inactive無視されます）。
    • 検索では、地理的に制限された動画を結果から除外するなど、再生ポリシーの制限が適用されます。
    • 結果をキャッシュすると、より高いリクエストレートとより迅速な応答が提供され、レート制限はありません。

    API リクエスト/レスポンスの詳細については、「再生 API リファレンス」の「ビデオの取得」セクションを参照してください。

    メディアライブラリ内の用語の検索を実行するには、qパラメータ。

          q={search terms}

    指定する検索用語は、スペースで区切られたURLエンコードされた用語のリストである必要があります。

    検索サポートステミング。ステミングとは、単語を単語の語根や、同じ語根に由来する他の単語にマッピングすることです。たとえば、「run」での検索は、指定されたフィールドに「running」または「ran」がある動画と一致する必要があります。それはない「rune」にはルートとして「run」がないため、「rune」と一致します。

    次のような検索語の修飾子を指定しない場合q=bird、リクエストは次のフィールドでその値を検索します。

    • id [1-1]
    • name
    • description
    • long_description
    • text（実際のメタデータフィールドではなく、検索に使用できる疑似フィールドname、description、およびlong_description -例：q=text:bird）
    • tags
    • reference_id
    • custom_fields ( すべてのカスタムフィールドを検索します)
    • custom_field_name（特定の名前付きカスタムフィールドを検索します） [1-2]

    備考

    [1-1]注：一貫性を保つためにIDによる検索が含まれていますが、q=id:12345リクエストとまったく同じ結果を返しますhttps://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345
    [1-2]リストタイプのカスタムフィールドがあり、いくつかの値のいずれかを持つビデオを返したい場合は、次のように行うことができます。

    あなたがというフィールドを持っているとしましょうcolorそれは値を取ることができます：red、green、yellow、またはblue。そのフィールドが値に設定されている動画を検索するgreenまたはblue：

          q=color:green%20color:blue

    例:このリクエストは、値がbird上記のフィールドの少なくとも1つ。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=bird

    検索を特定のプロパティに制限する

    次のような検索語の修飾子を指定する場合q=name:bird、リクエストは動画を検索しますnameの値のフィールドbird。

    例:このリクエストは、値がwildlifeの中にnameフィールド。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=name:wildlife

    サポートされる検索フィールドは以下のとおりです。

    サポートされている検索フィールド
    フィールド 法的価値
    name 文字列または引用符付き文字列
    テキスト 文字列または引用符で囲まれた文字列 (、namedescription、およびを検索しますlong_description )
    tags 文字列または引用符で囲まれた文字列 (複数のタグはカンマで区切る必要があります)
    custom_fields 文字列または引用符で囲まれた文字列（すべてのカスタムフィールドを検索します-特定のカスタムフィールドを使用することもできます内部名前） [2-1]
    reference_id 文字列または引用符で囲まれた文字列
    state ACTIVE、INACTIVE、PENDING、DELETED [2-3]
    updated_at 日付範囲
    created_at 日付範囲
    schedule.starts_at 日付範囲
    schedule.ends_at 日付範囲
    published_at 日付範囲
    complete [2-2] true または false

    注

    • [2-1]ですない値がない、または値がないカスタムフィールドを持つ動画を検索できますnull、フィールドに値が指定されていない限り、ビデオメタデータにはまったく含まれないためです。
    • [2-2]新しいビデオを作成すると、completeプロパティは自動的にに設定されますfalse。ビデオに1つのレンディションが存在するとすぐに、completeプロパティは自動的にに設定されますtrue。
    • [2-3]削除された動画の検索には、次の制限が適用されます。
      • 削除された動画の検索はのみ CMSAPIを使用して利用可能。再生APIはない削除された動画を返す
      • のみ過去10日間（現在の時刻から10日間を引いたもの）に削除された動画は返されます

    検索結果の並べ替え

    ザ・sortパラメータを使用すると、動画の取得リクエストの結果を並べ替えることができます。次のように並べ替えることができます。

    • reference_id
    • name
    • created_at
    • published_at
    • updated_at
    • schedule.starts_at
    • schedule.ends_at
    • state
    • plays_total
    • plays_trailing_week

    を使用して結果を明示的にソートしない場合sort、結果は、Term Frequency / Inverse DocumentFrequencyまたはInverseDocumentFrequencyとして知られるアルゴリズムに従ってソートされます。TF-IDF。見るここに詳細については。

    たとえば、用語で検索するとしますcoastal,cityアカウントには、動画メタデータのどこかにこれらの用語が含まれている120本の動画があります（name、description、tags、など）、結果の並べ替え基準にも一致します（たとえば、すべて同じです）schedule_starts_at日付時刻）。ビデオが表示される結果の高さは、一方または両方の用語がメタデータに表示される頻度によって決まり、ビデオライブラリ全体で最も頻繁に表示される用語に大きな重みが与えられます。

    必須/除外語

    検索語に必須（返される動画は一致する必要がある）、または除外（返される動画は一致してはいけない）のマークを付けることができます。これは、URIエンコードされたURIで制御されます+ (%2B)または-用語の直前に署名します。

    エンコードする必要があります+なので%2B必要な用語を示すために使用する場合。

    必須/除外条件
    例 urlエンコード 意味
    +foo %2Bfoo 動画には用語を含める必要がありますfooの中にname、description、long_description、tags、reference_idまたはcustom_fields
    +custom_fields:foo %2Bcustom_fields:foo ビデオには値を含める必要がありますfoo一部のカスタムフィールド用
    +foo -bar %2Bfoo%20-bar 動画には用語を含める必要がありますfooただし、この用語を含めることはできませんbarの中にname、description、long_description、tags、reference_idまたはcustom_fields
    +name:foo -name:bar %2Bname:foo%20-name:bar 動画には用語を含める必要がありますfooただし、この用語を含めることはできませんbarの中にname

    例:このリクエストは、値がseaただし、の値はありませんlakeの中にtagsフィールド。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=%2Btags:sea%20-tags:lake

    見る検索条件の組み合わせ以下では、必須/除外された構文を使用して、複数の検索用語にANDロジックを適用する方法を確認します。

    他のパラメータと組み合わせる

    検索（を使用してqパラメータ）は、次のような他のパラメータと組み合わせることができますsort、limitそしてoffset。すべてのURLパラメータは&。パラメータの順序は重要ではありません。

    例

    例:このリクエストは、次の値を持つ必要がある動画を返しますbarの中にtagフィールドがあり、name値を含むfoo

          .../videos?q=name:foo%20%2Btags:bar&sort=updated_at

    例:このリクエストは上記と同じ動画を返しますが、さらにそれらの結果をフィールドで並べ替えますupdated_at次に、結果を10本のビデオに制限します。

          .../videos?sort=updated_at&q=name:foo%20%2Btags:bar&limit=10

    引用された検索用語

    デフォルトでは、検索語と類似の語と一致します。複数の単語を一致させる場合は、単語を引用符で囲みます。

    ほとんどのブラウザおよびその他のエージェントは、リテラル引用符を扱います（"..."）正しく、ただし引用符で囲まれた検索語が正しい結果を返さないように見える場合は、引用符を%22（（%22...%22）

                
              q="foo" or q=%22foo%22
              q="foo%20bar" or q=%22foo%20bar%22

    これは、特定のフィールドに対する検索でも有効です。

                
              q=name:"home"
              q=name:"home%20run"

    複数の単語

    例:このリクエストは、次のいずれかの値を持つ動画を返すことに注意してくださいseaまたはmammalの中にtagsフィールド。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:sea,mammal

    ただし、次のリクエストでは、タグが付いている動画のみが返されますsea,mammal。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=tags:"sea,mammal"

    カスタムフィールド

    動画用に定義したカスタムフィールドで検索できます。

          q=my_field:foo
      q=my_field:"foo"

    注：すべてのカスタムフィールド値は文字列として扱われます。たとえば、値をとることができるリストタイプのカスタムフィールドがある場合trueまたはfalse、検索では、ブール値ではなく、これらの文字列が検索されます（多くのプログラミング言語では、1そして0と互換的に使用できますtrueそしてfalseブール値として、ただし検索中q=my_boolean_field:1を持っているビデオを返しませんmy_boolean_fieldに設定true）。

    例:このリクエストは、値が動物の中にsubjectカスタムフィールド。

          https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q=subject:animal

    日付範囲

    日付フィールドで検索する場合は、開始日と終了日を区切る2つの期間を使用して、特定の日付または日付の範囲を指定できます（q=updated_at:2018-01-01..2018-02-01）。

    これにより、updated_at 2012年8月1日から2012年10月8日までの値。ここでは、各日付をUTC形式で指定しています。

          q=updated_at:2012-08-01T00:00:00Z..2012-10-08T23:59:59Z

    時間コンポーネントを削除することで、この検索を簡略化できます。以下は、上記の検索と同等です。

          q=updated_at:2012-08-01..2012-10-08

    サポートされている日付形式

    サポートされている日付形式には、UTCと相対が含まれます。

    日付形式の例
    フォーマット（URIエンコードされたフォーマット） 意味
    2015-08-01T06：15：00Z これはUTCでの時間を表します。
    2012-08-01 これは、UTCの日の真夜中を表します。この例は、2012-08-01T00：00：00Zと同等です。
    -1d 現在の時刻から1日を引いたもの。 （見る未満）

    相対的な日付

    相対的な日付については、方向性をサポートします（+または-）の後に数字が続き、その後に期間が続きます。相対的な日付は常に現在の時刻から測定されます。法的期間は、分、時間、日です。

    例:

    相対的な日付のサンプル
    日付のqパラメータ 意味
    q = updated_at：-1day..NOW 1日前から当日に更新された動画
    q = created_at：-2日 2日前に追加されたビデオ
    q = updated_at：-4hours..NOW 4時間前から現在の時刻に更新されたビデオ
    q = created_at：-60分。 60分前から現在までに追加された動画
    q = created_at：2016-01-01 ..- 1d 2015年1月1日から1日前までに作成された動画
    q = updated_at：-14d..NOW 過去2週間のビデオ

    開始、終了の一方だけ指定する

    ある時間までのすべての日付と一致させたい、または、ある時間からのすべての日付と一致させたい場合、範囲の一方の端を指定しないでおきます。

    例:過去2日間に変更されたすべての動画を検索する

          q=updated_at:-2days..

    例:2013年8月11日以降に変更されたすべての動画を検索します。

          q=updated_at:2013-08-11T00:00:00Z..

    NOWスケジュール日の演算子

    にとってschedule.starts_atそしてschedule.ends_at、使用できますNOW日付値として。これは、現在の日時に基づいて動的クエリを設定できる便利な演算子です。いくつかの例：

    スケジュールデータの例
    from / to params URIエンコード 意味
    ?q=schedule.starts_at:..NOW ?q=schedule.starts_at:..NOW start_atは時間の始まりからこの瞬間までです
    ?q=schedule.starts_at:NOW ?q=schedule.starts_at:NOW start_atはこの瞬間からです
    ?q=schedule.ends_at:NOW.. ?q=schedule.ends_at:NOW.. extends_atはこの瞬間から時間の終わりまでです
    ？q = + schedule.starts_at：.. NOW + schedule.ends_at：NOW.。 ？q =％2Bschedule.starts_at：.. NOW％20％2Bschedule.ends_at：NOW .. この瞬間の前にstarts_at、この瞬間の後にends_at（ビデオはこの瞬間にスケジュールされています）

    検索条件を組み合わせる

    複雑な検索の基準を組み合わせることができます。

    例:このリクエストは、nameの値ゴシップ、2010年8月1日から2010年10月8日までの間に更新されました。次に、応答データを次のように並べ替えます。updated_at降順の日付。

          q=%2Bname:gossip%20%2Bupdated_at:2010-08-01..2010-10-08&sort=-updated_at

    同類項を整理する

    使用必須/除外された構文を持っているビデオを返すためにすべて指定された用語の。

    たとえば、次の検索を行う場合：

          q=name:foo +tags:bar (URI-encoded: q=name:foo%20%2Btags:bar)

    応答には、「バー」というタグが付いた動画が含まれます。foo名前に。あなたが持っているそれらのビデオだけを返したいならばfoo名前とタグ「bar」で、次を検索する必要があります。

          (unencoded) q=+name:foo +tags:bar (URI-encoded) q=%2Bname:foo%20%2Btags:bar

    同様に、次のような動画のみを返したい場合foo名前で、しかししますないタグ「バー」がある場合は、次の場所で検索します。

          (unencoded) q=+name:foo -tags:bar (encoded) q=%2Bname:foo%20-tags:bar

    例

    サンプル：同類項を整理する
    エンコードされていない検索文字列 URIエンコードされた検索文字列 意味
    q=foo bar q=foo%20bar 返品されたアイテムには「foo」または「bar」があります
    q=foo +bar q=foo%20%2Bbar 返品されるアイテムには「bar」が必要です。「foo」が含まれる場合があります
    q=+foo bar q =%2Bfoo%20bar 返品されるアイテムには「foo」が必要です。「bar」が含まれる場合があります
    q=+foo +bar q=%2Bfoo%20%2Bbar 返品されるアイテムには「foo」と「bar」が必要です
    q=-foo +bar q=-foo%20%2Bbar 返品されるアイテムには「bar」が含まれ、「foo」が含まれていない必要があります
    複数のタグ検索
    q=tags:bee,bop q=tags:bee,bop タグ「蜂」または「bop」の動画を返します。
    q=tags:bee tags:bop q=tags:bee%20tags:bop タグ「蜂」または「bop」の動画を返します。
    q=+tags:bee tags:bop q=%2Btags:bee%20tags:bop 返されるすべての動画には「bee」というタグが付いている必要があります。タグ「bop」もあるかもしれません
    q=+tags:bee +tags:bop q=%2Btags:bee%20%2Btags:bop 返されるすべての動画には、タグ「bee」とタグ「bop」があります

    特定のビデオを検索する

    検索を特定の動画セットに限定したい場合は、id：

    例:このリクエストはIDを持つ動画を返します123456789、987654321そして48376387

          q=id:123456789%20id:987654321%20id:48376387

    州で検索

    次のパラメータを使用して、ビデオの状態で検索を実行またはフィルタリングできます。

          q=state:ACTIVE( | INACTIVE | PENDING | DELETED)[3]

    注

    • [3]削除された動画の検索は、過去10日間（現在の時刻から10日を引いたもの）に削除された動画に対してのみ利用できます。CMS API（Playback APIではありません）。

    ステミング

    ステミングはサポートされていますが、ない部分的な単語検索。例えば、q=name:ban「」という名前の動画を返す必要がありますParking Ban Announced「または」Parking to be Banned「または」City Banning Parking " だがしかし " Bank Holiday「または」Bandit Captured "。

    スペース/特殊文字

    ザ・CMS API通常、検索文字列の特殊文字を処理しますが、いくつかの例外があります。

    • スペースは許可されておらず、次のようにエンコードする必要があります%20。（エンコードされていない+記号でスペースを置き換えることもできますが、これによりクエリが混乱する可能性があります。+用語が必要であることを示すこともできます。見る必須/除外された構文）

      たとえば、名前で「私のお気に入りの動画」を検索するには、次のようにします。

      q=name:"my%20favorite%20video"

    • リテラルを検索するには+署名または使用するには+返された動画を示すためしなければならない用語を含めるには、エンコードする必要があります+なので%2B：

      含まれている必要がある動画の検索"two+two"名前フィールドに

      q=name:two%2Btwo

      含まれている必要がある動画の検索"heron"名前フィールドに

      q=%2Bname:heron

    • 一部のエージェントはリテラル引用符を正しく処理しない可能性があるため、エンコードする方が安全です"foo"なので%22foo%22

    1回限りのリクエストには、BrightcoveLearningの文字列エンコーダ検索文字列をエンコードします。アプリの場合、使用している言語のURIエンコード関数を見つける必要があります。

    検索用語をクリップする

    クリップは、他のビデオのセクションから作成されたビデオです。クリップはによって生成することができますBrightcove ブソーシャル、および他の手段が将来利用可能になるでしょう。アカウントで生成されたクリップを見つけるために使用できる特別な検索用語がいくつかあります。

    • q=%2Bis_clip:true -クリップのみを返します
    • q=%2Bis_clip:false -非クリップのみを返します
    • q=%2Bclip_source_video_id:video_id -指定されたビデオから生成されたクリップを返します

    無視された単語

    特定の単語は、実際に検索しているものとは無関係に多くの結果を返す可能性があるため、検索文字列では無視されます。以下は、検索によって無視される単語のリストです。

    「a」,「an」,「と」,「ある」,「として」,「ある」,「ある」,「bt」,「by」,「のために」,「もし」,「で」,「に」,「ある」,「それは」,「ない」,「の」,「の」,「on」,「or」,「そのような」,「その」,「その」,「彼ら」,「それから」,「そこに」,「これらの」,「彼ら」,「これ」,「へ」,「た」,「意志を」,「と」

    既知の問題

    • 重複する結果：場合によっては、検索結果の一部のアイテムが複数回表示されることがあります。

      回避策：検索結果の重複を防ぐために、常にsort検索リクエストのパラメータ。