CMS /Playback API：視頻搜索v1

簡介

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

使用來創建和限制基本搜索 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。所有網址參數均以 &。參數順序無關緊要。

搜索參數 limit 的最大值為 100 每個請求。請參閱頁面搜索結果關於視頻分頁。

實例

示例：此請求返回的視頻值必須為 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

請注意，引號要求匹配的視頻中包含所有術語，但不一定與這些術語完全匹配。例如，在 "home run" 可能會返回帶有以下文字的視頻 homeless 和 running 在標題中。

當針對特定字段進行搜索時，這也適用：

            
              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=tags:"bird"%20name:"owl".

自定義字段

您可以搜索為視頻定義的任何自定義字段。

      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 -），然後是數字，然後是持續時間。相對日期始終從當前時間開始計算。合法持續時間為：分鐘，小時，天。

+ 標誌必須用URI編碼為 %2B.

例子：

相對日期樣本
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

筆記：

對於多字標籤或字符串，請將標籤/字符串括在URI編碼的引號（ %22），並用URI編碼空格 (%20):

多字標籤示例
未編碼的搜索字符串	編碼的搜索字符串
`q=tags:"multi word tag"`	`q=tags:%22multi%20word%20tag%22`

引號確保返回的視頻與所有條款匹配，但不一定與確切條款匹配。詞幹仍然適用-例如，在 "new house" 還將返回帶有 name or description 像 news about housing.

對於一次性申請，您可以使用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 搜索請求中的參數。