支持 聯繫支持 | 系統狀況 系統狀態
頁面內容

    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}

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

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

    如果您沒有為搜索詞提供限定詞，例如 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 or 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 or false

    筆記

    • [2-1] 這是 不 可以搜索自定義字段沒有值或值為的視頻 null，因為除非為該字段提供值，否則它根本不會包含在視頻元數據中。
    • [2-2] 當您創建新視頻時， complete 屬性自動設置為 false。 視頻存在一個副本時， complete 屬性將自動設置為 true.
    • [2-3] 以下限制適用於搜索DELETED視頻：
      • 搜索已刪除的視頻是 只能 可使用 CMS API;的 Playback 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) or - 在學期前立即簽名。

    您必須編碼 + as %2B 當使用它來表示必填項時。

    必要/排除條款
    例子 網址編碼 意
    +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, limit 和 offset。 所有網址參數均以 &。 參數順序無關緊要。

    實例

    示例：此請求返回的視頻值必須為 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，搜索將查找那些字符串，而不是布爾值（在許多編程語言中， 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 值介於1年2012月8日至2012年XNUMX月XNUMX日之間。此處我們以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天。 （看到 下面)

    相對日期

    對於相對日期，我們支持一個方向（ + or -），然後是數字，然後是持續時間。 相對日期始終從當前時間開始計算。 合法持續時間為：分鐘，小時，天。

    例子：

    相對日期樣本
    q日期參數 意思
    q = updated_at：-1day..NOW 從1天前更新到今天的視頻
    q = created_at：-2天 影片於2天前加入
    q = updated_at：-4hours..NOW 視頻已從4小時前更新為當前時間
    q = created_at：-60minutes .. 從60分鐘前添加到當前時間的視頻
    q = created_at：2016-01-01 ..- 1d 從1年2015月XNUMX日到一天前創建的視頻
    q = updated_at：-14d..NOW 過去兩週的視頻

    開放式範圍

    如果要匹配直到給定時間的所有日期，或者要匹配到給定時間的所有日期，請不要使用範圍的一端。

    範例：搜尋過去2天修改的所有影片

          q=updated_at:-2days..

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

          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：現在 ？q = schedule.starts_at：現在 從這一刻開始
    ？q = schedule.ends_at：現在。 ？q = schedule.ends_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 值 閒話，它們在1年2010月8日至2010年XNUMX月XNUMX日之間進行了更新。 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 以這個名字，但是 不 具有標籤“ 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”或“ bop”的視頻
    q=tags:bee tags:bop q=tags:bee%20tags:bop 返回標籤為“ bee”或“ 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"

    • 搜索文字 + 簽名或使用 + 表示返回的視頻 必須的， 包括一個術語，您必須對 + as %2B:

      搜索必須包含以下內容的視頻 "two+two" 在名稱字段中

      q=name:two%2Btwo

      搜索必須包含以下內容的視頻 "heron" 在名稱字段中

      q=%2Bname:heron

    • 一些代理可能無法正確處理文字引號，因此編碼起來更安全 "foo" as %22foo%22

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

    剪輯搜索詞

    剪輯是從其他視頻部分創建的視頻。 剪輯可以通過 Brightcove公司 Social，將來還會有其他方式。 您可以使用一些特殊的搜索詞來查找帳戶中生成的剪輯：

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

    忽略的單詞

    某些單詞在搜索字符串中會被忽略，因為它們是如此普遍，以至於它們很可能返回許多與您實際搜索的內容無關的結果。 以下是搜索忽略的單詞列表：

    “ a”，“ an”，“ and”，“ are”，“ as”，“ at”，“ be”，“ but”，“ by”，“ for”，“ if”，“ in”，“ into” ”，“是”，“它”，“否”，“不是”，“ of”，“ on”，“ or”，“ such”，“ that”，“ the”，“ their”，“ then”， “那裡”，“這些”，“他們”，“這個”，“到”，“是”，“將”，“有”

    已知的問題

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

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

    頁面最後更新於12年2020月XNUMX日