CM/播放API：影片搜尋 v1

在本主題中，您將學習如何使用 CMS API 搜尋帳戶中的影片。這CMS API提供一種編程方式來搜索您的視頻雲庫中的視頻。本主題提供搜尋語法的詳細資訊。注意：這是原始搜索語法 - 我們建議您使用更簡單的視頻搜索語法 v2 .對於 Playback API，您必須使用 此版本。

簡介

在本主題中，您將學習如何執行以下操作：

  • 使用q範圍
  • 排序搜索結果
  • 使用必填項和排除項進行搜索
  • 使用帶引號的搜索來匹配確切的詞和多個詞
  • 搜索自定義字段
  • 搜索具有特定日期和範圍的日期字段
  • 合併搜尋條件

API使用

搜索功能可以與CMS API或回放 API。

CMS 應用程式

將搜索與CMS API結合使用時，以下條件適用：

  • 所有請求（包括搜索）都需要包含您的訪問令牌的授權標頭。有關如何獲取客戶端憑據並使用它們檢索訪問令牌的詳細信息，請參閱Brightcove OAuth 概述 .
  • 搜索返回的最大視頻數量沒有限制，但速率限制確實適用。
  • 搜索結果包括您帳戶中的所有視頻，無論它們是否可以播放和/或受地理位置限制。

有關 API 請求/響應的詳細信息，請參閱獲取視頻的部分內容管理系統 API 參考 .

播放API

將搜索與Playback API結合使用時，適用以下條件：

  • 使用 Playback API 的搜索請求需要一個策略密鑰啟用搜索 .
  • 有一個限制從搜索返回的最大視頻數。
  • 搜索結果只會返回可播放的視頻（帶有state:inactive將被忽略）。
  • 搜索會強制執行播放策略限制，例如從結果中刪除受地理位置限制的視頻。
  • 緩存結果可提供更高的請求速率和更快的響應，並且沒有速率限制。

有關 API 請求/響應的詳細信息，請參閱獲取視頻的部分播放 API 參考 .

要在媒體庫中搜索術語，請使用q範圍。

      q={search terms}

您指定的搜索字詞應該是網址編碼的字詞列表，以空格分隔。

搜索支持詞幹 .詞幹是詞到詞根以及其他詞源於相同詞根的映射。例如，對“運行”的搜索應匹配在指定字段中具有“正在運行”或“運行”的視頻。它會不是匹配“rune”因為“rune”沒有“run”作為它的詞根。

當您沒有為搜索詞提供限定詞時，例如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至少在上面列出的領域之一。

      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或者false

注意事項

  • [2-1]這是不是可以搜索具有沒有值或值為的自定義字段的視頻null，因為除非該字段已被賦予一個值，否則它根本不包含在視頻元數據中。
  • [2-2]當您創建新視頻時，complete屬性自動設置為false .一旦視頻存在一個再現，complete屬性將自動設置為true .
  • [2-3]以下限制適用於搜索已刪除的視頻：
    • 搜索已刪除的視頻是僅有的使用 CMS API 可用；回放 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，結果將根據稱為詞頻/逆文檔頻率或TF-IDF .看這裡了解更多信息。

例如，假設您搜索字詞coastal,city並且您的帳戶中有 120 個視頻在視頻元數據中的某處具有這些術語（name , description , tags , 等等）並且也符合結果的排序標準（例如，它們都具有相同的schedule_starts_at約會時間）。視頻出現在結果中的程度取決於一個或兩個術語在元數據中出現的頻率，並且對在整個視頻庫中最頻繁出現的術語給予更大的重視。

必要/排除的詞彙

您可以將搜尋詞彙標示為必要 (傳回的視訊必須相符) 或排除 (傳回的視訊不必相符)。這是通過 URI 編碼控制的+ (%2B)或者-緊接在術語之前簽名。

你必須編碼+作為%2B當使用它來指示必填項時。

必要/排除條款
例 網址編碼 意義
+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

日期範圍

如果您要在日期字段中進行搜索，則可以指定特定日期或日期範圍，使用兩個句點將開始日期和結束日期分開（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 日到一天前創建的視頻
q = updated_at：-14d..NOW 過去兩週的視頻

開放結束範圍

如果您想要比對指定時間之前的所有日期，或者比對自指定時間以來的所有日期，請留下範圍的一個結尾。

範例：搜索最近2天修改的所有視頻

      q=updated_at:-2days..

範例：搜索在 2013 年 8 月 11 日或之後修改的所有視頻：

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

NOW計劃日期的操作員

為了schedule.starts_at和schedule.ends_at， 您可以使用NOW作為日期值。這是一個便利運算符，可讓您基於當前日期時間設置動態查詢。幾個例子：

計劃數據示例
從/到參數 URI編碼 意思
?q=schedule.starts_at:..NOW ?q=schedule.starts_at:..NOW starts_at是從時間開始到這一刻
?q=schedule.starts_at:NOW ?q=schedule.starts_at:NOW 從這一刻開始
?q=schedule.ends_at:NOW.. ?q=schedule.ends_at:NOW.. 從這個時刻到時間的終點
?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)

響應將包含帶有標籤“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 返回帶有標籤「蜜蜂」或「國際收支」的視頻
q=tags:bee tags:bop q=tags:bee%20tags: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]搜索 DELETED 視頻僅適用於過去 10 天（當前時間減去 10 天）內刪除的視頻，並且只能通過CMS API（不是播放 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

對於一次性請求，您可以使用 Brightcove Learning 的字符串編碼器對您的搜索字符串進行編碼。對於應用程序，您需要找到所用語言的URI編碼功能。

剪輯搜索詞

剪輯是從其他視頻部分創建的視頻。剪輯可以由Brightcove 社會 , 其他方式將在未來可用。您可以使用一些特殊的搜索詞來查找帳戶中生成的剪輯：

  • q=%2Bis_clip:true -只傳回剪輯片段
  • q=%2Bis_clip:false -僅返回非剪輯
  • q=%2Bclip_source_video_id:video_id -返回從指定視頻生成的剪輯

忽略的單字

某些字在搜尋字串中會被忽略，因為它們非常常普遍，因此可能會傳回許多與您實際搜尋內容無關的結果。以下是搜尋所忽略的單字清單：

「a」，「a」，「和」，「是」，「作為」，「在」，「是」，「但」，「通過」，「對」，「如果」，「進」，「進」，「是」，「它」，「不」，「不」，「不」，「的」，「開」，「」或「」，「」，「他們的」，「然後」，「那裡」，「這些」，「他們」，「這」，「到」，「是」，「將」，「與」

已知問題

  • 重複結果：在某些情況下，搜索結果中的某些項目可能會出現不止一次。

    解決方法：為防止重複搜索結果，請始終使用sort搜索請求中的參數。