サポート サポート問い合わせ先 | システムステータス システムステータス

CMS /Playback API:動画検索v1

このトピックでは、あなたのアカウントの動画を検索する方法について説明します。 CMS API CMS API プログラム内で動画を検索する方法を提供します Video Cloud としょうかん。 このトピックでは、検索構文の詳細について説明します。 注:これは元の検索構文です-より簡単な方法を使用することをお勧めします ビデオ検索構文v2.

概要

このトピックでは、次の操作方法について学習します。

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

APIの使用

検索機能は、 CMS API または Playback API.

CMS API

検索を CMS API以下が適用されます。

  • すべてのリクエスト(検索を含む)には、アクセストークンを含む承認ヘッダーが必要です。 クライアントの資格情報を取得してアクセストークンを取得する方法の詳細については、 Brightcove OAuth の概要.
  • 検索から返される動画の最大数に制限はありませんが、レート制限が適用されます。
  • 検索結果には、アカウント内のすべての動画、再生可能かどうか、地域限定の動画が含まれます。

APIリクエスト/レスポンスの詳細については、 ビデオを入手する のセクション CMS API 参照.

Playback API

検索を Playback API以下が適用されます。

  • 検索リクエストは Playback API ポリシーキーが必要です 検索が有効になっている.
  • あり 制限 検索から返される動画の最大数
  • 検索結果には、再生可能な動画のみが表示されます( state:inactive 無視されます)。
  • 検索では、結果から地域制限付きの動画を除外するなどの再生ポリシーの制限が適用されます。
  • 結果をキャッシュすると要求率が高くなり、応答が速くなり、レート制限はありません。

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

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

      q={search terms}

指定する検索語句は、スペースで区切られたURLのエンコードされたリストでなければなりません。

検索サポート ステミング。 ステミングは単語を単語rootにマッピングし、他の単語は同じルートから生じる単語をマッピングします。 たとえば、「実行」の検索では、指定したフィールドに「実行中」または「実行済み」がある動画と一致する必要があります。 それは Studio上ではサポートされていません。 "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] リストタイプのカスタムフィールドがあり、いくつかの値のうちの1つを持つビデオを返す場合は、次のようにします。

たとえば、フィールドが呼び出されたとします color 次の値を取ることができます: red, green, yellowまたは blue。 そのフィールドが値に設定されている動画を探したい green or 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 文字列または引用された文字列
テキスト 文字列または引用された文字列( name, descriptionおよび 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 or false

ノート

  • [2-1] それは Studio上ではサポートされていません。 価値のないカスタムフィールドを持つ動画や値を検索することは可能です nullなぜなら、フィールドに値が与えられていなければ、それはビデオメタデータには全く含まれていないからです。
  • [2-2] 新しいビデオを作成すると、 complete プロパティは自動的にに設定されます false。 ビデオ用に1つのレンディションがあるとすぐに、 complete プロパティは自動的にに設定されます true.
  • [2-3] 削除された動画の検索には、次の制限があります。
    • 削除された動画を検索する のみ 利用可能な CMS API; ザ・ Playback API 意志 Studio上ではサポートされていません。 削除した動画を返す
    • のみ 以前の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、結果は、用語頻度/逆文書頻度として知られるアルゴリズムに従ってソートされます。 TF-IDF。 見る ぜひこちらから皆様もその幸せなお客様の輪に加わりましょう。 詳細については。

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

必須/除外条件

必要に応じて検索語句にマークを付けることができます(返された動画は一致する必要があります)、または除外されます(返された動画は一致してはいけません)。 これは、URIでエンコードされた + (%2B) or - その直前の記号。

エンコードする必要があります + as %2B 必要な用語を示すためにそれを使うとき。

必須/除外条件
URLエンコードされた 意味
+foo %2Bfoo 動画には用語を含める必要があります foo name, description, long_description, tags, reference_id or custom_fields
+custom_fields:foo %2Bcustom_fields:foo ビデオには値を含める必要があります foo カスタムフィールドの場合
+foo -bar %2Bfoo%20-bar 動画には用語を含める必要があります foo しかし、用語を含めてはいけません bar name, description, long_description, tags, reference_id or 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, limitoffset。 すべての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 or 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 or false、検索でブール値ではなくそれらの文字列が検索されます(多くのプログラミング言語では、 10 交換可能に使用することができます truefalse ブール値として 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 8月1、2012と10月8、2012の間の値。 ここでは、各日付を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での1日の真夜中を表します。 この例は、2012-08-01T00と同等です。00:00Z
-1d 現在の時刻から1日を引いたもの。 (見る 以下)

相対日付

相対的な日付については、 + or -)に続いて数字が続き、続いて継続時間が続きます。 相対日付は常に現在の時刻から測定されます。 法的な期間は分、時間、日です。

例:

相対日付サンプル
日付のqパラメータ 意味
q = updated_at:-1day..NOW 1日前から現在の日に更新された動画
q = created_at:-2days 2日前に追加された動画
q = updated_at:-4hours..NOW 4時間前から現在に更新された動画
q = created_at:-60minutes .. 60分前から現在に追加された動画
q = created_at:2016-01-01 ..- 1d 1月の1、2015から1日前に作成された動画
q = updated_at:-14d..NOW 過去2週間の動画

オープンエンド範囲

指定された時刻までのすべての日付を一致させたい場合、または指定された時刻以降のすべての日付と一致させる場合は、範囲の一方の端を残します。

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

      q=updated_at:-2days..
      
      

例:8月以降に変更されたすべての動画を検索する11、2013:

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

NOW 予定日のオペレータ

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

スケジュールデータの例
パラレルから/へ URIエンコードされた 意味
?q = schedule.starts_at:.. NOW ?q = schedule.starts_at:.. NOW starts_atは最初からこの瞬間までです
?q = schedule.starts_at:今すぐ ?q = schedule.starts_at:今すぐ starts_atは現時点以降
?q = schedule.ends_at:NOW .. ?q = schedule.ends_at:NOW .. ends_atはこの瞬間から時間の終わりまでです
?q = + schedule.starts_at:..今すぐ+ schedule.ends_at:今すぐ.. ?q =%2Bschedule.starts_at:.. NOW%20%2Bschedule.ends_at:NOW .. この瞬間の前にstarts_at、この瞬間の後にends_at(ビデオはこの瞬間にスケジュールされています)

検索基準を結合する

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

例:このリクエストでは、 name の値 ゴシップ8月の1、2010、10月の8、2010の間で更新されました。 次に、応答データを 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)

レスポンスにはタグ 'bar'を持つ動画が含まれています foo 名前に。 返品したい動画のみを返品したい場合は foo 名前とタグ 'bar'には、次のものを検索する必要があります。

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

同様に、あなたが持っているビデオだけを返す場合は、 foo 名前ではなく、行う Studio上ではサポートされていません。 タグ 'bar'を持っている場合は、次のように検索します。

      (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 タグ "bee" OR "bop"の動画を返します
q=tags:bee tags:bop q=tags:bee%20tags:bop タグ "bee" OR "bop"の動画を返します
q=+tags:bee tags:bop q=%2Btags:bee%20tags:bop 返されるすべての動画はタグ「bee」を持っていなければなりません。 彼らはタグ "bop"も持つかもしれない
q=+tags:bee +tags:bop q=%2Btags:bee%20%2Btags:bop 返されるすべての動画にタグ「蜂」があり、タグ「bop」には、

特定の動画を検索する

検索を特定の動画セットに限定したい場合は、検索を行うことができます id:

例:このリクエストは、ID付きの動画を返します。 123456789, 98765432148376387

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

州別で検索する

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

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

ノート

  • 【3] 削除された動画の検索は、過去10日(現在の時間から10日を引いた日)に削除された動画、および CMS API ( Playback API).

ステミング

ステミングはサポートされていますが Studio上ではサポートされていません。 部分的な単語の検索。 例えば、 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"

  • リテラルを検索する + 署名するか、または + 返された動画 しなければなりません 用語を含めるには、 + as %2B:

    含まれているはずの動画を検索する "two+two" 名前フィールドに

    q=name:two%2Btwo

    含まれているはずの動画を検索する "heron" 名前フィールドに

    q=%2Bname:heron

  • エージェントによっては、文字通りの引用符を正しく処理できない場合があるため、エンコードする方が安全です "foo" as %22foo%22

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

検索語をクリップする

クリップは他のビデオのセクションから作成されたビデオです。 クリップは Brightcove Social将来的には他の手段も利用できるようになります。 アカウント内で生成されたクリップを見つけるために使用できる特別な検索用語がいくつかあります。

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

無視された単語

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

「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、 「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、「〜」、 「そこ」、「これら」、「彼ら」、「これ」、「〜」、「あり」、

既知の問題点

  • 重複した結果: 場合によっては、検索結果の一部の項目が複数回表示されることがあります。

    回避策: 検索結果が重複しないようにするには、常に sort 検索リクエストのパラメータ。


ページの最終更新日:12年2020月XNUMX日