本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
搜尋 Amazon 的 API 參考 CloudSearch
您可以使用搜尋 API 向您的 Amazon CloudSearch 網域提交搜尋或建議請求。如需如何進行搜尋的詳細資訊,請參閱使用 Amazon 搜索您的數據 CloudSearch。如需關於建議的詳細資訊,請參閱在 Amazon 中獲取自動完成建議 CloudSearch。
您用來與 Amazon 交互的其他 API CloudSearch 是:
搜尋
本節說明 search 資源的 HTTP 請求和回應訊息。
搜尋語法
GET /2013-01-01/search
搜尋請求標頭
- HOST
-
您所查詢的網域其搜尋請求端點。您可以使用 DescribeDomains 擷取網域的搜尋請求端點。
必要:是
搜尋請求參數
- cursor
-
擷取可讓您用於翻頁瀏覽大型結果集的游標值。使用
size
參數控制您希望納入到每次回應的命中數。請求中可指定cursor
或start
參數,兩者為互斥。如需詳細資訊,請參閱 Paginate the results。若要取得第一個游標,請於初次請求時指定
cursor=initial
。在後續的請求中,指定由回應的 hits 區段所傳回的游標值。例如,以下請求將游標值設為
initial
並將size
參數設為 100 以取得第一組命中項目。回應會隨附下一組命中項目的游標。search?q=john&cursor=initial&size=100&return=_no_fields { "status": { "rid": "+/Xu5s0oHwojC6o=", "time-ms": 15 }, "hits": { "found": 503, "start": 0, "cursor": "VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA", "hit": [ {"id": "tt0120601"}, {"id": "tt1801552"}, ... ] } }
若要取得下一組命中項目,則指定游標值以及欲擷取的命中數。
search?q=john&cursor=VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA&size=100
類型:字串
必要:否
- expr.NAME
-
定義可用於對結果進行排序的運算式。您也可以指定運算式做為傳回欄位。如需如何定義與使用運算式的詳細資訊,請參閱設定運算式。
單次搜尋請求可以定義與使用多個運算式。例如,以下請求建立兩個運算式用於對結果進行排序並將其納入搜尋結果:
search?q=(and (term field=genres 'Sci-Fi')(term field=genres 'Comedy'))&q.parser=structured &expr.expression1=_score*rating &expr.expression2=(1/rank)*year &sort=expression1 desc,expression2 desc &return=title,rating,rank,year,_score,expression1,expression2
類型:字串
必要:否
- facet.FIELD
-
指定要獲取 Facet 信息的字段-
FIELD
是字段的名稱。指定的欄位必須由網域組態啟用面向分類。面向選項是指定成 JSON 物件。如果 JSON 物件是空的 (facet.FIELD={}
),則會對所有欄位值計算面向數量,依面向數量將面向排序,並隨結果傳回前 10 名的面向。此 JSON 物件可指定三個選項:
-
sort
指定您想要以何種方式將結果中的面向排序:bucket
或count
。指定bucket
會依面向值按字母順序或數字大小排序 (遞增排序)。指定count
則會依據對每個面向值所計算的面向數量排序 (遞減順序)。若要擷取特定值或特定範圍值的面向數量,請使用buckets
選項代替sort
。 -
buckets
指定您要計算其數量的面向值或範圍的陣列。各值區將依其在請求中所指定的順序傳回。若要指定值的範圍,請使用逗號 (,) 來區隔上下限,並以括號將範圍括住。方括號 [或] 表示邊界包含在範圍內,大括號 {或} 會排除該邊界。您可以省略上限或下限來指定開放式範圍。省略邊界時,您必須使用大括號。如果您指定,則sort
和size
選項無效buckets
。 -
size
指定結果所要包含的面向數量上限。默認情況下,Amazon CloudSearch 返回前 10 名的計數。size
參數僅限於已指定sort
選項時有效;此參數不得搭配buckets
使用。
例如,以下請求取得
year
欄位的面向數量、將面向數量依其值排序並傳回前三名的數量:facet.year={sort:"bucket", size:3}
如欲指定您要計算其面向數量的值或值的範圍,請使用
buckets
選項。例如,以下請求將計算並傳回每隔十年的面向數量:facet.year={buckets:["[1970,1979]","[1980,1989]", "[1990,1999]","[2000,2009]", "[2010,}"]}
您也可以指定個別的值做為值區:
facet.genres={buckets:["Action","Adventure","Sci-Fi"]}
請注意,面向值有區分大小寫 - 對於 IMDb 電影範例資料,若您指定
["action","adventure","sci-fi"]
而非["Action","Adventure","Sci-Fi"]
,則所有面向數量都將為零。類型:字串
必要:否
-
- format
-
指定回應的內容類型。
類型:字串
有效值:json | xml
預設:json
必要:否
- fq
-
指定結構式查詢以篩選搜尋結果,但不會影響結果的計分和排序方式。您將使用
fq
搭配q
參數,根據q
參數所指定的限制條件篩選相符的文件。指定篩選條件只是控制結果將包含哪些相符的文件,並不會影響文件的計分和排序方式。fq
參數支援完整的結構式查詢語法。如需如何使用篩選條件的詳細資訊,請參閱篩選相符文件。如需結構式查詢的詳細資訊,請參閱結構化搜尋語法。類型:字串
必要:否
- highlight.FIELD
-
擷取指定的
text
或text-array
欄位內各個相符項目的反白句。反白選項是指定成 JSON 物件。如果 JSON 物件是空的,傳回的欄位文字即視同 HTML,且第一個相符項目將套用加強語氣標籤以示反白:<em>search-term</em>
。此 JSON 物件可指定四個選項:
-
format
指定文字欄位中資料的格式:text
或html
。以 HTML 傳回資料時,所有非英數字元都將經過編碼處理。預設值為html
。 -
max_phrases
指定您要反白顯示的搜尋字詞出現次數上限。預設會反白第一次出現的位置。 -
pre_tag
— 指定要在出現搜尋字詞的前面加上的字串。HTML 反白的預設值為<em>
。文字反白的預設值為*
。 -
post_tag
— 指定要附加到出現的搜尋字詞的字串。HTML 反白的預設值為</em>
。文字反白的預設值為*
。
範例:
highlight.plot={}
,highlight.plot={format:'text',max_phrases:2,pre_tag:'<b>',post_tag:'</b>'}
類型:字串
必要:否
-
- partial
-
控制若有一或多個索引分割區無法使用時,是否傳回局部結果。當您的搜尋索引跨多個搜尋執行個體進行分割時,預設情況下,Amazon CloudSearch 只會在每個分區都可以查詢時傳回結果。這表示任一搜尋執行個體發生故障均有可能導致 5xx (內部伺服器) 錯誤。當您指定時
partial=true
。Amazon 會 CloudSearch 傳回任何可用的結果,並包含在搜尋結果中搜尋的文件百分比 (percent-searched
)。這讓您能夠更從容地降解使用者的搜尋體驗。例如,與其顯示沒有任何結果,不如顯示局部結果和一則訊息指出因為系統暫時停機以致結果可能不完整。類型:布林值
預設:False
必要:否
- pretty
-
格式化 JSON 輸出以使其更方便閱讀。
類型:布林值
預設:False
必要:否
- q
-
請求的搜尋條件。您應如何指定搜尋條件,視乎用於請求的查詢剖析器以及
q.options
參數所指定的剖析器選項而定。預設情況下將使用simple
查詢剖析器來處理請求。若要使用structured
、lucene
或dismax
查詢剖析器,您還必須指定q.parser
參數。如需如何指定搜尋條件的詳細資訊,請參閱使用 Amazon 搜索您的數據 CloudSearch。類型:字串
必要:是
- q.options
-
針對
q.parser
參數所指定的查詢剖析器設定其選項。各選項是指定成 JSON 物件,例如:q.options={defaultOperator: 'or', fields: ['title^5','description']}
。可供設定的選項因您所使用的剖析器類型而異:
defaultOperator
用來組合搜尋字串中個別字詞的預設運算子。例如:defaultOperator: 'or'
。對於dismax
剖析器,您應指定百分比而非預設運算子,其代表搜尋字串中必須符合的字詞所佔百分比 (無條件捨去)。值為0%
相當於 OR,值為100%
相當於 AND。百分比指定的值必須在 0-100 的範圍內,後面加上百分比 (%) 符號。例如defaultOperator: 50%
。有效值:and
、or
、0%-100% 範圍內的百分比 (dismax
)。預設:and
(simple
、structured
、lucene
) 或100
(dismax
)。適用於:simple
、structured
、lucene
和dismax
。fields
搜尋中未指定任何欄位時要搜尋的欄位陣列。如果搜尋時未指定任何欄位且未指定此選項,則會搜尋所有靜態設定的text
和text-array
欄位。您可以為每個欄位指定權重,以控制 Amazon CloudSearch 計算相關性分數時每個欄位的相對重要性。若要指定欄位權重,請於欄位名稱後面附加插入號 (^
) 及其權重。例如,若要提升title
欄位的重要性高過description
欄位,您可以指定:fields: ['title^5','description']
。有效值:任何設定的欄位其名稱和大於零的選用數值。預設:所有靜態設定的text
和text-array
欄位。預設中,動態欄位和literal
欄位不會進行搜尋。適用於:simple
、structured
、lucene
和dismax
。operators
您要停用簡單查詢剖析器的運算子或特殊字元陣列。若您停用了and
、or
或not
運算子,其對應的運算子 (+
、|
、-
) 即毫無特殊意義且將從搜尋字串中卸除。同樣地,停用prefix
會停用萬用字元運算子 (*
),而停用phrase
將停用由雙引號括住片語的方式進行片語搜尋的能力。停用 precedence 會停用由括號控制優先順序的能力。停用near
會停用由 ~ 運算子進行鬆散片語搜尋的能力。停用fuzzy
運算子將會禁止使用 ~ 運算子來執行模糊搜尋的功能。escape
禁止使用反斜線 (\
) 來運用搜尋字串避開特殊字元。停用 whitespace 屬於進階選項,可防止剖析器將空白字元字符化,對於剖析越南文非常有用 (能避免越南單詞拆解錯誤)。例如,您可以停用 phrase 運算子除外的所有運算子,藉此僅支援簡單的字詞和片語查詢:operators:['and', 'not', 'or', 'prefix']
。有效值:and
、escape
、fuzzy
、near
、not
、or
、phrase
、precedence
、prefix
、whitespace
。預設:啟用所有運算子和特殊字元。適用於:simple
。phraseFields
您要用於片語搜尋的text
或text-array
欄位陣列。當搜尋字串中的字詞非常近似於某欄位時,該欄位會得到較高的分數。您可為每個欄位指定權重以提高此分數。phraseSlop
選項控制著與搜尋字串的相符度可偏離多少而仍會提高其分數的範圍。若要指定欄位權重,請於欄位名稱後面附加插入號 (^
) 及其權重。例如,若要提升title
欄位的片語比對份量高過abstract
欄位,您可以指定:phraseFields:['title^3', 'abstract']
。有效值:任何text
或text-array
欄位的名稱和大於零的選用數值。預設:無任何欄位。如果phraseFields
未指定任何欄位,即使指定了phraseSlop
還是會停用近似性評分。適用於:dismax
。phraseSlop
整數值,指定可以偏離搜尋片語的相符項目,但仍會根據選項中指定的權數提升。phraseFields
例如phraseSlop: 2
。您還必須指定phraseFields
以啟用近似性評分。有效值:正整數。預設:0. 適用於:dismax
。explicitPhraseSlop
整數值,指定當搜尋字串中的片語用雙引號括住時,相符項目可以偏離搜尋片語的程度。(超過此接近距離的詞組不被視為匹配項。)explicitPhraseSlop: 5
。 有效值:正整數。預設:0. 適用於:dismax
。tieBreaker
當在文件的欄位中找到搜尋字串中的字詞時,系統會根據該字段中該字詞與其他文件相比的常見程度來計算該欄位的分數。若該字詞出現於某文件的多個欄位內,預設只會將最高分的欄位計入文件的整體分數。您可以指定tieBreaker
值,使較低分的相符欄位也能計入文件的分數。如此一來,若兩份文件找到特定字詞的欄位最高分數相同,相符欄位愈多的文件其分數就會愈高。tieBreaker 計算分數的公式如下:(max field score) + (tieBreaker) * (sum of the scores for the rest of the matching fields)
例如,以下查詢在 、 和
title
欄位內搜尋description
dogreview
一詞並將tieBreaker
設為 0.1:q=dog&q.parser=dismax&q.options={fields:['title', 'description', 'review'], tieBreaker: 0.1}
如果某文件的上述三個欄位內都有 dog 一詞,而各欄位的分數分別是 title=1、description=3 且 review=1,則 dog 的整體分數如下:
3 + 0.1 * (1+1) = 3.2
tieBreaker
設定為 0 將忽略最高分除外的所有欄位 (純最高分)。設定為 1 會加總所有欄位的分數 (純加總)。有效值:0 到 1.0。預設:0.0。適用於:dismax
。
類型:JSON 物件
預設:請參閱個別選項的說明。
必要:否
- q.parser
-
指定要用於處理請求的查詢剖析器:
simple
、structured
、lucene
和dismax
。如果q.parser
未指定,Amazon CloudSearch 會使用查simple
詢剖析器。-
simple
— 執行簡單的搜尋text
和text-array
欄位。預設情況下,simple
查詢剖析器會搜尋所有靜態設定的text
和text-array
欄位。您可以使用q.options
參數指定要搜尋哪些欄位。如果您用加號 (+) 做為搜尋詞彙的字首,文件即必須包含該詞彙才會視為相符 (預設是如此,除非您透過q.options
參數設定預設運算子)。您可以使用-
(NOT)、|
(OR) 和*
(萬用字元) 運算子排除特定字詞、尋找符合任何指定之字詞的結果,或是搜尋字首。若要搜尋片語而非個別字詞,請用雙引號括住整段片語。如需詳細資訊,請參閱 使用 Amazon 搜索您的數據 CloudSearch。 -
structured
透過組合多個運算式來定義搜尋條件來執行進階搜尋。您也可以在特定欄位內搜尋、搜尋值和值的範圍,並使用像是增加詞彙相關度、matchall
和near
等進階選項。如需詳細資訊,請參閱 建構複合查詢。 -
lucene
使用阿帕奇尼查詢解析器語法進行搜索。如需詳細資訊,請參閱 Apache Lucene 查詢剖析器語法。 -
dismax
使用查詢剖析器定義的 Apache Lucene 查詢剖析器語法的簡化子集進行搜尋。 DisMax 如需詳細資訊,請參閱DisMax 查詢剖析器語法。
類型:字串
預設:
simple
必要:否
-
- return
-
欲包含在回應中的欄位及運算式值,指定成以逗號分隔的清單。預設情況下,搜尋回應將包含所有啟用傳回的欄位 (
return=_all_fields
)。若只要傳回相符文件的文件 ID,請指定return=_no_fields
。若要擷取對每份文件算出的相關性分數,請指定return=_score
。您可將多個傳回欄位指定成以逗號分隔的清單。例如,return=title,_score
只會傳回片名和每份文件的相關性分數。類型:字串
必要:否
- size
-
欲傳回的搜尋命中數上限。
類型:正整數
預設:10
必要:否
- sort
-
用於對搜尋結果進行排序的欄位或自訂運算式以逗號分隔的清單。您必須為每個欄位指定排序方向 (
asc
或desc
)。例如sort=year desc,title asc
。最多共可指定 10 個欄位和運算式。若要使用欄位對結果進行排序,該欄位必須由網域組態啟用排序。陣列類型的欄位無法用於排序。若未指定sort
參數,結果將依其預設相關性分數以遞減順序排序:sort=_score desc
。排序方式也可以依據文件 ID (sort=_id
) 及版本 (sort=_version
)。類型:字串
必要:否
- start
-
欲傳回的第一個搜尋命中項目的位移。請求中可指定
start
或cursor
參數,兩者為互斥。如需詳細資訊,請參閱 Paginate the results。類型:正整數
預設:0 (第一個命中項目)
必要:否
結構化搜尋語法
使用structured
查詢剖析器時,您可以使用 Amazon CloudSearch 結構化搜尋語法來定義搜尋條件,並使用fq
參數指定篩選條件。
使用結構式查詢運算子,您將依序指定運算子的名稱和運算子的選項,接著是所要運算的字詞:(OPERATOR OPTIONS STRING|EXPRESSION)
。務必先指定任何選項再指定字串或運算式。例如 (and (not field=genres 'Sci-Fi')(or (term field=title boost=2 'star')(term field=plot 'star')))
。
重要
查詢字串中的特殊字元必須以 URL 編碼處理。例如,您必須將結構化查詢中的=
運算子編碼為%3D
:(term+field%3Dtitle+'star'
)。Amazon CloudSearch 返回一個InvalidQueryString
錯誤,如果特殊字符不是 URL 編碼。如需 URL 編碼的完整參考內容,請參閱 W3C HTML URL 編碼參考
使用結構式查詢剖析器時若未指定欲搜尋的欄位,則會搜尋所有靜態設定的 text
和 text-array
欄位。預設中,動態欄位和 literal
欄位不會進行搜尋。您可以透過 q.options
參數,指定預設將要搜尋哪些欄位。
括號控制著對複合查詢的運算式進行評估的順序。當運算式用括號括住時,會先評估該運算式,接著再使用其結果值評估查詢的剩餘部分。運算式可包含任何結構式查詢運算子。
您也可以使用結構式查詢剖析器搜尋簡單的文字字串,只需用單引號括住您想要搜尋的字串:q='black swan'&q.parser="structured"
。
如需使用結構式查詢運算子建構複合查詢的詳細資訊,請參閱建構複合查詢。
- FIELD
-
語法:
FIELD: 'STRING'|value
搜尋指定的欄位以找出字串、數值、日期或是數值或日期的範圍。
字串必須用單引號括住。字串中的任何單引號或反斜線都必須以反斜線逸出。若要指定值的範圍,請使用逗號 (,) 來區隔上下限,並以括號將範圍括住。方括號 [或] 表示邊界包含在範圍內,大括號 {或} 會排除該邊界。您可以省略上限或下限來指定開放式範圍。省略邊界時,您必須使用大括號。
日期和時間以 UTC(國際標準時間)指定,根據 IETF RFC3339
:。 yyyy-mm-ddTHH:mm:ss.SSSZ
以世界標準時間為例,1970 年 8 月 23 日下午 5 點為:1970-08-23T17:00:00Z
。請注意,在以 UTC 指定時間時,您也可以指定小數秒數。例如:1967-01-31T23:20:50.650Z.
範例:
title:'star' year:2000 year:[1998,2000] year:{,2011] release_date:['2013-01-01T00:00:00Z',}
- and
-
語法:
(and boost=N EXPRESSION EXPRESSION ... EXPRESSIONn)
僅當文件符合所有指定的表達式時才予納入 。 (布林值
AND
運算子) 運算式可包含任何結構式查詢運算子,或是簡單的搜尋字串。搜尋字串必須用單引號括住。請注意,若要比對任何搜尋的欄位內包含指定之字詞的文件,則應以個別的運算式指定每個字詞:(and 'star' 'wars')
。如果您指定(and 'star wars')
,star 和 wars 必須出現於同一個欄位內才會視為相符。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(and title:'star' actors:'Harrison Ford' year:{,2000])
- matchall
-
語法:
matchall
比對網域內的每一份文件。預設會傳回前 10 項。使用
size
和start
參數可翻頁瀏覽結果。 - near
-
語法:
(near field=FIELD distance=N boost=N 'STRING')
搜尋
text
或text-array
欄位以找出指定的多字詞字串,並比對其中包含各字詞彼此相隔在指定距離內的文件 (這有時稱為草率短語搜索。) 如果您省略field
此選項,Amazon 預設會 CloudSearch 搜尋所有靜態設定的text-array
欄位text
和欄位。預設中,動態欄位和literal
欄位不會進行搜尋。您可以透過指定q.options
fields
選項來指定預設要搜尋的欄位。距離值必須是正整數。例如,若要尋找 欄位內 teenage 與 vampire
plot
相隔 10 個單詞以內的所有文件,則指定距離值為 10:(near field=plot distance=10 'teenage vampire')
。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(near field=plot distance=10 'teenage vampire')
- not
-
語法:
(not boost=N EXPRESSION)
若文件符合指定的運算式即予排除 (布林值
NOT
運算子)。運算式可包含任何結構式查詢運算子,或是簡單的搜尋字串。搜尋字串必須用單引號括住。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(not (or actors:'Harrison Ford' year:{,2010]))
- or
-
語法:
(or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)
若文件符合任何指定的運算式即予納入 (布林值
OR
運算子)。運算式可包含任何結構式查詢運算子,或是簡單的搜尋字串。搜尋字串必須用單引號括住。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(or actors:'Alec Guinness' actors:'Harrison Ford' actors:'James Earl Jones')
- phrase
-
語法:
(phrase field=FIELD boost=N 'STRING')
在
text
或text-array
欄位中搜尋指定的片語。如果您省略field
此選項,Amazon 預設會 CloudSearch 搜尋所有靜態設定的text-array
欄位text
和欄位。預設中,動態欄位和literal
欄位不會進行搜尋。您可以透過指定q.options
fields
選項來指定預設要搜尋的欄位。在結構式查詢中使用
phrase
運算子以結合片語搜尋和其他搜尋條件。例如,q=(and (term field=title 'star') (range field=year {,2000]))
會比對片名欄位內包含 star 且年份值小於或等於 2000 的所有文件。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(phrase field=plot 'teenage girl')
- prefix
-
語法:
(prefix field=FIELD boost=N 'STRING')
在
text
、text-array
literal
、或literal-array
欄位中搜尋指定的首碼,後跟零個或多個字元。如果您省略field
此選項,Amazon 預設會 CloudSearch 搜尋所有靜態設定的text-array
欄位text
和欄位。預設中,動態欄位和literal
欄位不會進行搜尋。您可以透過指定q.options
fields
選項來指定預設要搜尋的欄位。在結構式查詢中使用
prefix
運算子以結合字首搜尋和其他搜尋條件。例如,q=(and (prefix field=title 'sta') (range field=year {,2000]))
會比對片名欄位內包含字首 sta 且年份值小於或等於 2000 的所有文件。boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
注意
若要實作搜尋建議,您應設定並查詢建議者,而非進行字首搜尋。如需更多資訊,請參閱 建議請求。
範例:
(prefix field=title 'star')
- range
-
語法:
(range field=FIELD boost=N RANGE)
搜尋數值欄位 (double、double-array、int、int-array) 或日期欄位 (date、date-array) 以找出落在指定範圍內的值。比對其欄位內至少有一個值落在指定範圍內的文件。務必指定
field
選項。在結構式查詢中使用
range
運算子以結合範圍搜尋和其他搜尋條件。例如,q=(and (term field=title 'star') (range field=year {,2000]))
會比對片名欄位內包含 star 且年份值小於或等於 2000 的所有文件。若要指定值的範圍,請使用逗號 (,) 來區隔上下限,並以括號將範圍括住。方括號 [或] 表示邊界包含在範圍內,大括號 {或} 會排除該邊界。您可以省略上限或下限來指定開放式範圍。省略邊界時,您必須使用大括號。
日期和時間以 UTC(國際標準時間)指定,根據 IETF RFC3339
:。 yyyy-mm-ddTHH:mm:ss.SSSZ
以世界標準時間為例,1970 年 8 月 23 日下午 5 點為:1970-08-23T17:00:00Z
。請注意,在以 UTC 指定時間時,您也可以指定小數秒數。例如:1967-01-31T23:20:50.650Z.
boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(range field=year [1990,2000]) (range field=year {,2000]) (range field=year [1990,})
- term
-
語法:
(term field=FIELD boost=N 'STRING'|VALUE)
搜尋指定的欄位以找出某字串、數值或日期。搜尋值時必須指定
field
此選項。如果您省略field
此選項,Amazon 預設會 CloudSearch 搜尋所有靜態設定的text-array
欄位text
和欄位。預設中,動態欄位和literal
欄位不會進行搜尋。您可以透過指定q.options
fields
選項來指定預設要搜尋的欄位。在結構式查詢中使用
term
運算子以結合字詞搜尋和其他搜尋條件。例如,q=(and (term field=title 'star') (range field=year {,2000]))
會比對片名欄位內包含 star 且年份值小於或等於 2000 的所有文件。字串和日期必須用單引號括住。字串中的任何單引號或反斜線都必須用反斜線逸出。
日期和時間以 UTC(國際標準時間)指定,根據 IETF RFC3339
:。 yyyy-mm-ddTHH:mm:ss.SSSZ
以世界標準時間為例,1970 年 8 月 23 日下午 5 點為:1970-08-23T17:00:00Z
。請注意,在以 UTC 指定時間時,您也可以指定小數秒數。例如:1967-01-31T23:20:50.650Z.
boost 值是正數值,會增加搜尋查詢此部分相對於其他部分的重要性。
範例:
(term field=title 'star') (term field=year 2000)
簡易搜尋語法
使用simple
查詢剖析器時,您可以使用 Amazon CloudSearch 簡單搜尋語法來定義搜尋條件。若您並未指定 q.parser
參數,預設即會使用 simple 查詢剖析器。
使用 simple 查詢剖析器可搜尋個別字詞或片語。預設會搜尋所有靜態設定的 text
和 text-array
欄位。預設中,動態欄位和 literal
欄位不會進行搜尋。您可以使用 q.options
參數指定欲搜尋的欄位、變更用於結合搜尋字串中個別字詞的預設運算子,或是停用任何 simple 剖析器運算子 (and
、escape
、fuzzy
、near
、not
、or
、phrase
、precedence
、prefix
、whitespace
)。
如需使用 simple 查詢剖析器的詳細資訊,請參閱text。
- + (and)
-
語法:
+TERM
需要指定的字詞。文件必須包含指定的字詞才算符合條件。
範例:+star
- \ (escape)
-
語法:
\CHAR
逸出欲搜尋的特殊字元。若您希望查詢列入以下字元,即必須將其逸出:+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /.
範例:
M\*A\*S\*H
- ~ (fuzzy)
-
語法:
TERM~N
進行模糊搜尋。於字詞後面附加 ~ 運算子和一個值,以表示容許各字詞差別到什麼程度下仍會視為相符。
範例:
stor~1
- ~ (near)
-
語法:
"PHRASE"~N
進行鬆散片語搜尋。於片語後面附加 ~ 運算子和一個值,以表示各字詞在相隔多遠的情況下仍會視為與該片語相符。
範例:
"star wars"~4
- - (not)
-
語法:
-TERM
禁止指定的字詞。文件必須不含該字詞才算符合條件。
範例:star -wars
- | (or)
-
語法:
|TERM
將指定的字詞視為選擇性。
範例:star |wars
- "..." (phrase)
-
語法:
"PHRASE"
進行整段片語搜尋。可結合
~
運算子以進行鬆散片語搜尋。範例:"star wars"
- (...) (precedence)
-
語法:
(...)
控制對查詢限制條件進行評估的順序。最內側括號的內容最先評估。
範例:
+(war|trek)+star
- * (prefix)
-
語法:
CHARS*
比對其所包含的字詞具有指定之字首的文件。
範例:
sta*
搜尋回應
成功完成請求後,回應內文將包含搜尋結果。預設會以 JSON 格式傳回搜尋結果。如果 format
參數設為 xml
,則會以 XML 傳回搜尋結果。
除非您明確指定 return
參數,否則將附上每份相符文件 (命中項目) 的文件 ID 及所有可傳回的欄位。回應也會顯示找到的命中總數 (found
) 以及所列第一份文件的索引 (start
)。預設情況下,回應會包含前 10 個命中項目。您可在請求中指定 size
參數,以控制每次回應所要納入的命中數。若要翻頁瀏覽命中項目,您可以使用 start
或 cursor
參數。如需詳細資訊,請參閱 Paginate the results。
典型的 JSON 回應如以下範例所示。
{ "status": { "rid": "rtKz7rkoeAojlvk=", "time-ms": 10 }, "hits": { "found": 3, "start": 0, "hit": [ { "id": "tt1142977", "fields": { "rating": "6.9", "genres": [ "Animation", "Comedy", "Family", "Horror", "Sci-Fi" ], "plot": "Young Victor conducts a science experiment to bring his beloved dog Sparky back to life, only to face unintended, sometimes monstrous, consequences.", "release_date": "2012-09-20T00:00:00Z", "title": "Frankenweenie", "rank": "1462", "running_time_secs": "5220", "directors": [ "Tim Burton" ], "image_url": "http://ia.media-imdb.com/images/M/MV5BMjIx ODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@._ V1_SX400_.jpg", "year": "2012", "actors": [ "Winona Ryder", "Catherine O'Hara", "Martin Short" ] } }, . . . ] } }
對等的 XML 回應如以下範例所示。
<results> <status rid="itzL7rkoeQojlvk=" time-ms="34"/> <hits found="3" start="0"> <hit id="tt1142977"> <field name="rating">6.9</field> <field name="genres">Animation</field> <field name="genres">Comedy</field> <field name="genres">Family</field> <field name="genres">Horror</field> <field name="genres">Sci-Fi</field> <field name="plot">Young Victor conducts a science experiment to bring his beloved dog Sparky back to life, only to face unintended, sometimes monstrous, consequences. </field> <field name="release_date">2012-09-20T00:00:00Z</field> <field name="title">Frankenweenie</field> <field name="rank">1462</field> <field name="running_time_secs">5220</field> <field name="directors">Tim Burton</field> <field name="image_url">http://ia.media-imdb.com/images/M/MV5BMjI xODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@. _V1_SX400_.jpg </field> <field name="year">2012</field> <field name="actors">Winona Ryder</field> <field name="actors">Catherine O'Hara</field> <field name="actors">Martin Short</field> </hit> . . . </hits> </results>
回應格式的設定僅會影響到對於成功請求的回應。錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。因為伺服器逾時和其他要求路由問題造成的 5xx 錯誤會以 XML 格式傳回。當要求傳回錯誤碼時,回應主體會包含發生錯誤的相關資訊。如果在要求主體進行剖析和驗證時發生錯誤,則錯誤代碼會設定為 400,而回應主體會包含錯誤及其發生位置的清單。
搜尋回應標頭
- Content-Type
-
描述物件資料格式的標準 MIME 類型。如需詳細資訊,請參閱 W3C RFC 2616 第 14 節
。 有效值:application/json 或 application/xml
預設:application/json
- Content-Length
-
回應內文以位元組為單位的長度。
搜尋回應屬性 (JSON)
- status
-
包含資源 id (rid) 以及處理請求所花費的時間 (time-ms)。
- rid
-
經過加密的資源 ID。
- time-ms
-
處理搜尋請求所花費的時間 (毫秒)。
- hits
-
包含符合的文件份數 (
found
)、回應所附第一份文件的索引 (start
) 以及列出每個命中項目的文件 ID 和資料的陣列 (hit
)。- found
-
Amazon CloudSearch 完成處理請求後,符合搜尋請求的點擊總數。
- start
-
此次回應所傳回第一個命中項目的索引。
- hit
-
列出每個命中項目的文件 ID 和資料的陣列。
- id
-
文件的唯一識別符。
- fields
-
傳回的欄位清單。
- facets
-
包含面向資訊和面向數量。
- FACETFIELD
-
面向經過計算的欄位。
- buckets
-
計算出的面向值與數量的陣列。
- value
-
列入計數的面向值。
- count
-
FACETFIELD
包含面向值的命中數。
搜尋回應元素 (XML)
- results
-
包含搜尋結果。處理請求時發生的任何錯誤將以訊息的形式由 info 元素傳回。
- status
-
包含資源 id (
rid
) 以及處理請求所花費的時間 (time-ms
)。 - hits
-
包含命中統計資料和一組 hit 元素。找到的屬性是 Amazon CloudSearch 完成處理結果後,符合搜尋請求的點擊總數。包含的 hit 元素將依其相關性分數或搜尋請求所指定的
sort
選項進行排序。- hit
-
符合搜尋請求的文件。id 屬性是該份文件獨一無二的 id。包含
d
(資料) 元素,代表傳回的各個欄位。- field
-
從命中項目傳回的欄位。hit 元素包含
d
(資料) 元素,代表傳回的各個欄位。 - facets
-
包含 facet 元素,代表搜尋請求所請求的各個面向。
- facet
-
包含 bucket 元素,代表已計算面向數量的某欄位的各個值。使用
facet.FIELD
的 size 選項可指定欲傳回的限制條件數。預設情況下會傳回前 10 項限制條件的面向數量。使用facet.FIELD
的 buckets 選項可明確指定欲列入計數的值。- bucket
-
面向欄位值以及該值在搜尋命中項目內出現的次數 (計數)。
在 Amazon 提交建議請求 CloudSearch
您將透過 HTTP GET 向您網域的搜尋端點 2013-01-01/suggest
提交建議請求。如需如何控制建議服務存取權的相關資訊,請參閱configure access policies。
所有建議請求皆必須指定 API 版本,且該版本必須與網域建立時所指定的 API 版本相符。
例如,以下請求使用名為 title
的建議者,向 search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com
網域取得對查詢字串 oce
的建議。
http://search-imdb-hd6ebyouhw2lczkueyuqksnuzu.us-west-2.cloudsearch.amazonaws.com/2013-01-01/suggest -d"q=oce&suggester=suggest_title"
您可以使用任何想要傳送 GET 要求到網域搜尋端點的方法 — 您可以直接在網頁瀏覽器中輸入要求 URL、使用 cURL 提交要求,或使用您最愛的 HTTP 程式庫產生 HTTP 呼叫。您也可以使用 Amazon CloudSearch 控制台中的搜索測試儀獲取建議。如需詳細資訊,請參閱 使用搜尋測試器進行搜尋。
重要
網域的文件和搜尋端點在網域生命週期當中會保持不變。應當對端點進行快取處理,而非在每次上傳或搜尋請求之前擷取端點。透過呼叫aws cloudsearch describe-domains
或在每個請求DescribeDomains
之前查詢 Amazon CloudSearch 組態服務,可能會導致您的請求受到限制。
默認情況下,Amazon CloudSearch 返回 JSON 響應。您可藉由指定 format
參數 format=xml
取得 XML 格式的結果。回應格式的設定僅會影響到對於成功請求的回應。錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。因為伺服器逾時和其他要求路由問題造成的 5xx 錯誤會以 XML 格式傳回。
建議
建議請求
在 Amazon 中建議語法 CloudSearch
GET /2013-01-01/suggest
在 Amazon 中建議請求標題 CloudSearch
- HOST
-
您所查詢的網域其搜尋請求端點。您可以使用 DescribeDomains 擷取網域的搜尋請求端點。
必要:是
在 Amazon 建議請求參數 CloudSearch
- q
-
您要取得其建議的字串。
類型:字串
必要:是
- suggester
-
用於尋找所建議相符項目的建議者的名稱。
類型:字串
必要:是
- size
-
欲傳回的建議數目上限。
類型:正整數
預設:10
必要:否
- format
-
指定回應的內容類型。
類型:字串
有效值:json | xml
預設:json
必要:否
建議回應
成功完成請求後,回應內文將包含建議項目。預設會以 JSON 格式傳回建議。將 format
參數設為 xml
可取得 XML 格式的結果。
回應格式的設定僅會影響到對於成功請求的回應。錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。因為伺服器逾時和其他要求路由問題造成的 5xx 錯誤會以 XML 格式傳回。當要求傳回錯誤碼時,回應主體會包含發生錯誤的相關資訊。如果在要求主體進行剖析和驗證時發生錯誤,則錯誤代碼會設定為 400,而回應主體會包含錯誤及其發生位置的清單。
對建議請求發出的 JSON 回應如以下範例所示:
{ "status": { "rid": "qOSM5s0oCwr8pVk=", "time-ms": 2 }, "suggest": { "query": "oce", "found": 3, "suggestions": [ { "suggestion": "Ocean's Eleven", "score": 0, "id": "tt0054135" }, { "suggestion": "Ocean's Thirteen", "score": 0, "id": "tt0496806" }, { "suggestion": "Ocean's Twelve", "score": 0, "id": "tt0349903" } ] } }
對等的 XML 回應如以下範例所示:
<results> <status rid="/pSz580oDQr8pVk=" time-ms="2"/> <suggest query="oce" found="3"> <suggestions> <item suggestion="Ocean's Eleven" score="0" id="tt0054135"/> <item suggestion="Ocean's Thirteen" score="0" id="tt0496806"/> <item suggestion="Ocean's Twelve" score="0" id="tt0349903"/> </suggestions> </suggest> </results>
搜尋服務錯誤
搜尋或建議請求可能傳回以下三類的狀態碼:
-
5xx 狀態碼表示發生內部伺服器錯誤。您應截獲並重試所有 5xx 錯誤碼,因為這通常代表暫時性錯誤情況。如需詳細資訊,請參閱 處理錯誤。
-
4xx 狀態碼表示請求的格式不正確。請更正錯誤後再重新提交您的請求。
-
2xx 狀態碼表示已成功處理請求。
錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。因為伺服器逾時和其他要求路由問題造成的 5xx 錯誤會以 XML 格式傳回。
搜尋服務傳回的錯誤包含以下資訊:
- error
-
包含由搜尋服務所傳回的錯誤訊息。每項錯誤均附有
code
和msg
屬性。 - code
-
錯誤代碼。
- msg
-
由搜尋服務所傳回的錯誤的描述。