簡介
在本主題中,您將學習如何執行以下操作:
- 使用來創建和限制基本搜索
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]
筆記
q=id:12345
將返回與請求完全相同的結果 https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/12345
假設您有一個名為 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
搜索請求中的參數。