搜尋 Amazon 的 API 參考 CloudSearch

您所查詢的網域其搜尋請求端點。您可以使用 DescribeDomains 擷取網域的搜尋請求端點。

必要：是

擷取可讓您用於翻頁瀏覽大型結果集的游標值。使用 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

類型：字串

必要：否

定義可用於對結果進行排序的運算式。您也可以指定運算式做為傳回欄位。如需如何定義與使用運算式的詳細資訊，請參閱設定運算式。

單次搜尋請求可以定義與使用多個運算式。例如，以下請求建立兩個運算式用於對結果進行排序並將其納入搜尋結果：

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 是字段的名稱。指定的欄位必須由網域組態啟用面向分類。面向選項是指定成 JSON 物件。如果 JSON 物件是空的 (facet.FIELD={})，則會對所有欄位值計算面向數量，依面向數量將面向排序，並隨結果傳回前 10 名的面向。

此 JSON 物件可指定三個選項：

例如，以下請求取得 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"]，則所有面向數量都將為零。

類型：字串

必要：否

指定回應的內容類型。

類型：字串

有效值：json | xml

預設：json

必要：否

指定結構式查詢以篩選搜尋結果，但不會影響結果的計分和排序方式。您將使用 fq 搭配 q 參數，根據 q 參數所指定的限制條件篩選相符的文件。指定篩選條件只是控制結果將包含哪些相符的文件，並不會影響文件的計分和排序方式。fq 參數支援完整的結構式查詢語法。如需如何使用篩選條件的詳細資訊，請參閱篩選相符文件。如需結構式查詢的詳細資訊，請參閱結構化搜尋語法。

類型：字串

必要：否

擷取指定的 text 或 text-array 欄位內各個相符項目的反白句。反白選項是指定成 JSON 物件。如果 JSON 物件是空的，傳回的欄位文字即視同 HTML，且第一個相符項目將套用加強語氣標籤以示反白：<em>search-term</em>。

此 JSON 物件可指定四個選項：

範例: highlight.plot={}, highlight.plot={format:'text',max_phrases:2,pre_tag:'<b>',post_tag:'</b>'}

類型：字串

必要：否

控制若有一或多個索引分割區無法使用時，是否傳回局部結果。當您的搜尋索引跨多個搜尋執行個體進行分割時，預設情況下，Amazon CloudSearch 只會在每個分區都可以查詢時傳回結果。這表示任一搜尋執行個體發生故障均有可能導致 5xx (內部伺服器) 錯誤。當您指定時partial=true。Amazon 會 CloudSearch 傳回任何可用的結果，並包含在搜尋結果中搜尋的文件百分比 (percent-searched)。這讓您能夠更從容地降解使用者的搜尋體驗。例如，與其顯示沒有任何結果，不如顯示局部結果和一則訊息指出因為系統暫時停機以致結果可能不完整。

類型：布林值

預設：False

必要：否

格式化 JSON 輸出以使其更方便閱讀。

類型：布林值

預設：False

必要：否

請求的搜尋條件。您應如何指定搜尋條件，視乎用於請求的查詢剖析器以及 q.options 參數所指定的剖析器選項而定。預設情況下將使用 simple 查詢剖析器來處理請求。若要使用 structured、lucene 或 dismax 查詢剖析器，您還必須指定 q.parser 參數。如需如何指定搜尋條件的詳細資訊，請參閱使用 Amazon 搜索您的數據 CloudSearch。

類型：字串

必要：是

針對 q.parser 參數所指定的查詢剖析器設定其選項。各選項是指定成 JSON 物件，例如：q.options={defaultOperator: 'or', fields: ['title^5','description']}。

可供設定的選項因您所使用的剖析器類型而異：

類型：JSON 物件

預設：請參閱個別選項的說明。

必要：否

指定要用於處理請求的查詢剖析器：simple、structured、lucene 和 dismax。如果q.parser未指定，Amazon CloudSearch 會使用查simple詢剖析器。

類型：字串

預設：simple

必要：否

欲包含在回應中的欄位及運算式值，指定成以逗號分隔的清單。預設情況下，搜尋回應將包含所有啟用傳回的欄位 (return=_all_fields)。若只要傳回相符文件的文件 ID，請指定 return=_no_fields。若要擷取對每份文件算出的相關性分數，請指定 return=_score。您可將多個傳回欄位指定成以逗號分隔的清單。例如，return=title,_score 只會傳回片名和每份文件的相關性分數。

類型：字串

必要：否

欲傳回的搜尋命中數上限。

類型：正整數

預設：10

必要：否

用於對搜尋結果進行排序的欄位或自訂運算式以逗號分隔的清單。您必須為每個欄位指定排序方向 (asc 或 desc)。例如 sort=year desc,title asc。最多共可指定 10 個欄位和運算式。若要使用欄位對結果進行排序，該欄位必須由網域組態啟用排序。陣列類型的欄位無法用於排序。若未指定 sort 參數，結果將依其預設相關性分數以遞減順序排序：sort=_score desc。排序方式也可以依據文件 ID (sort=_id) 及版本 (sort=_version)。

類型：字串

必要：否

欲傳回的第一個搜尋命中項目的位移。請求中可指定 start 或 cursor 參數，兩者為互斥。如需詳細資訊，請參閱 Paginate the results。

類型：正整數

預設：0 (第一個命中項目)

必要：否

語法: 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 boost=N EXPRESSION EXPRESSION ... EXPRESSIONn)

僅當文件符合所有指定的表達式時才予納入 。 (布林值 AND 運算子) 運算式可包含任何結構式查詢運算子，或是簡單的搜尋字串。搜尋字串必須用單引號括住。請注意，若要比對任何搜尋的欄位內包含指定之字詞的文件，則應以個別的運算式指定每個字詞：(and 'star' 'wars')。如果您指定 (and 'star wars')，star 和 wars 必須出現於同一個欄位內才會視為相符。

boost 值是正數值，會增加搜尋查詢此部分相對於其他部分的重要性。

範例：

(and title:'star' actors:'Harrison Ford' year:{,2000])

語法: matchall

比對網域內的每一份文件。預設會傳回前 10 項。使用 size 和 start 參數可翻頁瀏覽結果。

語法: (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 boost=N EXPRESSION)

若文件符合指定的運算式即予排除 (布林值 NOT 運算子)。運算式可包含任何結構式查詢運算子，或是簡單的搜尋字串。搜尋字串必須用單引號括住。

boost 值是正數值，會增加搜尋查詢此部分相對於其他部分的重要性。

範例：

(not (or actors:'Harrison Ford' year:{,2010]))

語法: (or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)

若文件符合任何指定的運算式即予納入 (布林值 OR 運算子)。運算式可包含任何結構式查詢運算子，或是簡單的搜尋字串。搜尋字串必須用單引號括住。

boost 值是正數值，會增加搜尋查詢此部分相對於其他部分的重要性。

範例：

(or actors:'Alec Guinness' actors:'Harrison Ford' actors:'James Earl Jones')

語法: (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 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 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 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)

語法: +TERM

需要指定的字詞。文件必須包含指定的字詞才算符合條件。

範例：+star

語法: \CHAR

逸出欲搜尋的特殊字元。若您希望查詢列入以下字元，即必須將其逸出：+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /.

範例：M\*A\*S\*H

語法: TERM~N

進行模糊搜尋。於字詞後面附加 ~ 運算子和一個值，以表示容許各字詞差別到什麼程度下仍會視為相符。

範例：stor~1

語法: "PHRASE"~N

進行鬆散片語搜尋。於片語後面附加 ~ 運算子和一個值，以表示各字詞在相隔多遠的情況下仍會視為與該片語相符。

範例："star wars"~4

語法: -TERM

禁止指定的字詞。文件必須不含該字詞才算符合條件。

範例：star -wars

語法: |TERM

將指定的字詞視為選擇性。

範例：star |wars

語法: "PHRASE"

進行整段片語搜尋。可結合 ~ 運算子以進行鬆散片語搜尋。

範例："star wars"

語法: (...)

控制對查詢限制條件進行評估的順序。最內側括號的內容最先評估。

範例：+(war|trek)+star

語法: CHARS*

比對其所包含的字詞具有指定之字首的文件。

範例：sta*

描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 W3C RFC 2616 第 14 節。

有效值：application/json 或 application/xml

預設：application/json

回應內文以位元組為單位的長度。

包含資源 id (rid) 以及處理請求所花費的時間 (time-ms)。

包含符合的文件份數 (found)、回應所附第一份文件的索引 (start) 以及列出每個命中項目的文件 ID 和資料的陣列 (hit)。

包含搜尋結果。處理請求時發生的任何錯誤將以訊息的形式由 info 元素傳回。

您所查詢的網域其搜尋請求端點。您可以使用 DescribeDomains 擷取網域的搜尋請求端點。

必要：是

您要取得其建議的字串。

類型：字串

必要：是

用於尋找所建議相符項目的建議者的名稱。

類型：字串

必要：是

欲傳回的建議數目上限。

類型：正整數

預設：10

必要：否

指定回應的內容類型。

類型：字串

有效值：json | xml

預設：json

必要：否

包含由搜尋服務所傳回的錯誤訊息。每項錯誤均附有 code 和 msg 屬性。

錯誤代碼。

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