搜尋 Amazon 的 API 參考 CloudSearch - Amazon CloudSearch
搜尋提交建議請求建議搜尋服務錯誤

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

搜尋 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 欄位內搜尋 descriptiondogreview 一詞並將 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.optionsfields選項來指定預設要搜尋的欄位。

距離值必須是正整數。例如，若要尋找 欄位內 teenage 與 vampireplot 相隔 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.optionsfields選項來指定預設要搜尋的欄位。

在結構式查詢中使用 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-arrayliteral、或literal-array欄位中搜尋指定的首碼，後跟零個或多個字元。如果您省略field此選項，Amazon 預設會 CloudSearch 搜尋所有靜態設定的text-array欄位text和欄位。預設中，動態欄位和 literal 欄位不會進行搜尋。您可以透過指定q.optionsfields選項來指定預設要搜尋的欄位。

在結構式查詢中使用 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.optionsfields選項來指定預設要搜尋的欄位。

在結構式查詢中使用 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

由搜尋服務所傳回的錯誤的描述。