本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon CloudSearch 的搜尋 API 參考
**Topics**
+ [搜尋](#search-request)
+ [在 Amazon CloudSearch 中提交建議請求](#submitting-suggest-requests)
+ [建議](#suggest)
+ [搜尋服務錯誤](#search-service-errors)
您可以使用搜尋 API 將搜尋或建議請求提交到您的 Amazon CloudSearch 網域。如需如何進行搜尋的詳細資訊，請參閱[使用 Amazon CloudSearch 搜尋您的資料](searching.md)。如需關於建議的詳細資訊，請參閱[在 Amazon CloudSearch 中取得自動完成建議](getting-suggestions.md)。
您用來與 Amazon CloudSearch 互動的其他 APIs 包括：
+ [組態 API](configuration-api.md) - 設定和管理您的搜尋網域。
+ [文件服務 API](document-service-api.md) - 提交您要搜尋的資料。
## 搜尋
本節說明 search 資源的 HTTP 請求和回應訊息。
### 搜尋語法
```
GET /2013-01-01/search
```
### 搜尋請求標頭
HOST
您所查詢的網域其搜尋請求端點。您可以使用 [DescribeDomains](API_DescribeDomains.md) 擷取網域的搜尋請求端點。
必要：是
### 搜尋請求參數
cursor
擷取可讓您用於翻頁瀏覽大型結果集的游標值。使用 `size` 參數控制您希望納入到每次回應的命中數。請求中可指定 `cursor` 或 `start` 參數，兩者為互斥。如需詳細資訊，請參閱[對結果進行分頁](paginating-results.md)。
若要取得第一個游標，請於初次請求時指定 `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
定義可用於對結果進行排序的運算式。您也可以指定運算式做為傳回欄位。如需如何定義與使用運算式的詳細資訊，請參閱[設定運算式](configuring-expressions.md)。
單次搜尋請求可以定義與使用多個運算式。例如，以下請求建立兩個運算式用於對結果進行排序並將其納入搜尋結果：
```
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
指定您要取得面向資訊的欄位 -`FIELD` 是欄位的名稱。指定的欄位必須由網域組態啟用面向分類。面向選項是指定成 JSON 物件。如果 JSON 物件是空的 (`facet.FIELD={}`)，則會對所有欄位值計算面向數量，依面向數量將面向排序，並隨結果傳回前 10 名的面向。
此 JSON 物件可指定三個選項：
+ `sort` 指定您想要以何種方式將結果中的面向排序：`bucket` 或 `count`。指定 `bucket` 會依面向值按字母順序或數字大小排序 (遞增排序)。指定 `count` 則會依據對每個面向值所計算的面向數量排序 (遞減順序)。若要擷取特定值或特定範圍值的面向數量，請使用 `buckets` 選項代替 `sort`。
+ `buckets` 指定您要計算其數量的面向值或範圍的陣列。各值區將依其在請求中所指定的順序傳回。若要指定值的範圍，請使用逗號 (,) 來區隔上下限，並以括號將範圍括住。方括號 【 或 】 表示邊界包含在範圍中，大括號 \$1 或 \$1 排除邊界。您可以省略上限或下限，以指定開放式範圍。省略邊界時，您必須使用大括弧。如果您指定 ，則 `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 \$1 xml
預設：json
必要：否
fq
指定結構式查詢以篩選搜尋結果，但不會影響結果的計分和排序方式。您將使用 `fq` 搭配 `q` 參數，根據 `q` 參數所指定的限制條件篩選相符的文件。指定篩選條件只是控制結果將包含哪些相符的文件，並不會影響文件的計分和排序方式。`fq` 參數支援完整的結構式查詢語法。如需如何使用篩選條件的詳細資訊，請參閱[篩選相符文件](filtering-results.md)。如需結構式查詢的詳細資訊，請參閱[結構化搜尋語法](#structured-search-syntax)。
類型：字串
必要：否
highlight.FIELD
擷取指定的 `text` 或 `text-array` 欄位內各個相符項目的反白句。反白選項是指定成 JSON 物件。如果 JSON 物件是空的，傳回的欄位文字即視同 HTML，且第一個相符項目將套用加強語氣標籤以示反白：`search-term`。
此 JSON 物件可指定四個選項：
+ `format`- 指定文字欄位中資料的格式： `text`或 `html`。以 HTML 傳回資料時，所有非英數字元都將經過編碼處理。預設值為 `html`。
+ `max_phrases`- 指定您要反白顯示之搜尋詞彙的出現次數上限 (s)。預設會反白第一次出現的位置。
+ `pre_tag`- 指定字串，以在出現搜尋詞彙之前加上。HTML 反白的預設值為 ``。文字反白的預設值為 `*`。
+ `post_tag`- 指定要附加至搜尋詞彙出現的字串。HTML 反白的預設值為 ``。文字反白的預設值為 `*`。
範例: `highlight.plot={}`, `highlight.plot={format:'text',max_phrases:2,pre_tag:'',post_tag:''}`
類型：字串
必要：否
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 搜尋您的資料](searching.md)。
類型：字串
必要：是
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` 會停用由 \$1 運算子進行鬆散片語搜尋的能力。停用 `fuzzy` 運算子將會禁止使用 \$1 運算子來執行模糊搜尋的功能。`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`dog`review` 一詞並將 `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` 參數指定要搜尋哪些欄位。如果您用加號 (\$1) 做為搜尋詞彙的字首，文件即必須包含該詞彙才會視為相符 (預設是如此，除非您透過 `q.options` 參數設定預設運算子)。您可以使用 `-` (NOT)、`|` (OR) 和 `*` (萬用字元) 運算子排除特定字詞、尋找符合任何指定之字詞的結果，或是搜尋字首。若要搜尋片語而非個別字詞，請用雙引號括住整段片語。如需詳細資訊，請參閱[使用 Amazon CloudSearch 搜尋您的資料](searching.md)。
+ `structured`- 透過結合多個表達式來定義搜尋條件來執行進階搜尋。您也可以在特定欄位內搜尋、搜尋值和值的範圍，並使用像是增加詞彙相關度、`matchall` 和 `near` 等進階選項。如需詳細資訊，請參閱[建構複合查詢](searching-compound-queries.md)。
+ `lucene`- 使用 Apache Lucene 查詢剖析器語法進行搜尋。如需詳細資訊，請參閱 [Apache Lucene 查詢剖析器語法](https://cwiki.apache.org/confluence/display/solr/The+Standard+Query+Parser)。
+ `dismax`- 使用 DisMax 查詢剖析器定義的 Apache Lucene 查詢剖析器語法簡化子集進行搜尋。如需詳細資訊，請參閱 [DisMax 查詢剖析器語法](https://cwiki.apache.org/confluence/display/solr/The+DisMax+Query+Parser)。
類型：字串
預設：`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` 參數，兩者為互斥。如需詳細資訊，請參閱[對結果進行分頁](paginating-results.md)。
類型：正整數
預設：0 (第一個命中項目)
必要：否
#### 結構化搜尋語法
您可以使用 Amazon CloudSearch 結構化搜尋語法，在使用`structured`查詢剖析器時定義搜尋條件，並使用 `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'`)。如果特殊字元不是 URL 編碼，Amazon CloudSearch 會傳回`InvalidQueryString`錯誤。如需 URL 編碼的完整參考內容，請參閱 W3C [HTML URL 編碼參考](http://www.w3schools.com/tags/ref_urlencode.asp)。
使用結構式查詢剖析器時若未指定欲搜尋的欄位，則會搜尋所有靜態設定的 `text` 和 `text-array` 欄位。預設中，動態欄位和 `literal` 欄位*不會*進行搜尋。您可以透過 `q.options` 參數，指定預設將要搜尋哪些欄位。
括號控制著對複合查詢的運算式進行評估的順序。當運算式用括號括住時，會先評估該運算式，接著再使用其結果值評估查詢的剩餘部分。運算式可包含任何結構式查詢運算子。
您也可以使用結構式查詢剖析器搜尋簡單的文字字串，只需用單引號括住您想要搜尋的字串：`q='black swan'&q.parser="structured"`。
如需使用結構式查詢運算子建構複合查詢的詳細資訊，請參閱[建構複合查詢](searching-compound-queries.md)。
FIELD
語法: `FIELD: 'STRING'|value`
搜尋指定的欄位以找出字串、數值、日期或是數值或日期的範圍。
字串必須用單引號括住。字串中的任何單引號或反斜線都必須以反斜線逸出。若要指定值的範圍，請使用逗號 (,) 來區隔上下限，並以括號將範圍括住。方括號 【 或 】 表示邊界包含在範圍中，大括號 \$1 或 \$1 排除邊界。您可以省略上限或下限，以指定開放式範圍。省略邊界時，您必須使用大括弧。
日期和時間是根據 [IETF RFC3339](http://tools.ietf.org/html/rfc3339) 以 UTC （國際標準時間） 指定：`yyyy-mm-ddTHH:mm:ss.SSSZ`。例如，在 UTC 中，1970 年 8 月 23 日下午 5：00 是：`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* 必須出現於同一個欄位內才會視為相符。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(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`和`text-array`欄位。預設中，動態欄位和 `literal` 欄位不會進行搜尋。您可以指定 `q.options``fields`選項，以指定預設要搜尋的欄位。
距離值必須是正整數。例如，若要尋找 * 欄位內 *teenage* 與 *vampire`plot` 相隔 10 個單詞以內的所有文件，則指定距離值為 10：`(near field=plot distance=10 'teenage vampire')`。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(near field=plot distance=10 'teenage vampire')
```
not
語法: `(not boost=N EXPRESSION)`
若文件符合指定的運算式即予排除 (布林值 `NOT` 運算子)。運算式可包含任何結構式查詢運算子，或是簡單的搜尋字串。搜尋字串必須用單引號括住。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(not (or actors:'Harrison Ford' year:{,2010]))
```
or
語法: `(or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)`
若文件符合任何指定的運算式即予納入 (布林值 `OR` 運算子)。運算式可包含任何結構式查詢運算子，或是簡單的搜尋字串。搜尋字串必須用單引號括住。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(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`和`text-array`欄位。預設中，動態欄位和 `literal` 欄位不會進行搜尋。您可以指定 `q.options``fields`選項，以指定預設要搜尋的欄位。
在結構式查詢中使用 `phrase` 運算子以結合片語搜尋和其他搜尋條件。例如，`q=(and (term field=title 'star') (range field=year {,2000]))` 會比對片名欄位內包含 *star* 且年份值小於或等於 2000 的所有文件。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(phrase field=plot 'teenage girl')
```
prefix
語法: `(prefix field=FIELD boost=N 'STRING')`
搜尋指定字首的 `text`、`literal`、 `text-array`或 `literal-array` 欄位，後面加上零個或多個字元。如果您省略 `field`選項，Amazon CloudSearch 預設會搜尋所有靜態設定`text`和`text-array`欄位。預設中，動態欄位和 `literal` 欄位不會進行搜尋。您可以指定 `q.options``fields`選項，以指定預設要搜尋的欄位。
在結構式查詢中使用 `prefix` 運算子以結合字首搜尋和其他搜尋條件。例如，`q=(and (prefix field=title 'sta') (range field=year {,2000]))` 會比對片名欄位內包含字首 *sta* 且年份值小於或等於 2000 的所有文件。
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
若要實作搜尋建議，您應設定並查詢建議者，而非進行字首搜尋。如需更多資訊，請參閱[建議請求](#suggest-request)。
範例：
```
(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 的所有文件。
若要指定值的範圍，請使用逗號 (,) 來區隔上下限，並以括號將範圍括住。方括號 【 或 】 表示邊界包含在範圍中，大括號 \$1 或 \$1 排除邊界。您可以省略上限或下限，以指定開放式範圍。省略邊界時，您必須使用大括弧。
日期和時間是根據 [IETF RFC3339](http://tools.ietf.org/html/rfc3339) 以 UTC （國際標準時間） 指定：`yyyy-mm-ddTHH:mm:ss.SSSZ`。例如，在 UTC 中，1970 年 8 月 23 日下午 5：00 是：`1970-08-23T17:00:00Z`。請注意，在 UTC 中指定時間時，您也可以指定小數秒。例如 `1967-01-31T23:20:50.650Z.`
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(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`和`text-array`欄位。預設中，動態欄位和 `literal` 欄位不會進行搜尋。您可以指定 `q.options``fields`選項，以指定預設要搜尋的欄位。
在結構式查詢中使用 `term` 運算子以結合字詞搜尋和其他搜尋條件。例如，`q=(and (term field=title 'star') (range field=year {,2000]))` 會比對片名欄位內包含 *star* 且年份值小於或等於 2000 的所有文件。
字串和日期必須用單引號括住。字串中的任何單引號或反斜線都必須用反斜線逸出。
日期和時間是根據 [IETF RFC3339](http://tools.ietf.org/html/rfc3339) 以 UTC （國際標準時間） 指定：`yyyy-mm-ddTHH:mm:ss.SSSZ`。例如，在 UTC 中，1970 年 8 月 23 日下午 5：00 是：`1970-08-23T17:00:00Z`。請注意，在 UTC 中指定時間時，您也可以指定小數秒。例如 `1967-01-31T23:20:50.650Z.`
提升值是正數值，會增加此部分搜尋查詢相對於其他部分的重要性。
範例：
```
(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 查詢剖析器的詳細資訊，請參閱[在 Amazon CloudSearch 中搜尋文字](searching-text.md)。
\$1 (and)
語法: `+TERM`
需要指定的字詞。文件必須包含指定的字詞才算符合條件。
範例：\$1star
\$1 (escape)
語法: `\CHAR`
逸出欲搜尋的特殊字元。若您希望查詢列入以下字元，即必須將其逸出：\$1 - & \$1 \$1 ( ) \$1 \$1 [ ] ^ " \$1 \$1 ? : \$1 /.
範例：`M\*A\*S\*H`
\$1 (fuzzy)
語法: `TERM~N`
進行模糊搜尋。於字詞後面附加 \$1 運算子和一個值，以表示容許各字詞差別到什麼程度下仍會視為相符。
範例：`stor~1`
\$1 (near)
語法: `"PHRASE"~N`
進行鬆散片語搜尋。於片語後面附加 \$1 運算子和一個值，以表示各字詞在相隔多遠的情況下仍會視為與該片語相符。
範例：`"star wars"~4`
- (not)
語法: `-TERM`
禁止指定的字詞。文件必須不含該字詞才算符合條件。
範例：star -wars
\$1 (or)
語法: `|TERM`
將指定的字詞視為選擇性。
範例：star \$1wars
"..." (phrase)
語法: `"PHRASE"`
進行整段片語搜尋。可結合 `~` 運算子以進行鬆散片語搜尋。
範例："star wars"
(...) (precedence)
語法: `(...)`
控制對查詢限制條件進行評估的順序。最內側括號的內容最先評估。
範例：`+(war|trek)+star`
\$1 (prefix)
語法: `CHARS*`
比對其所包含的字詞具有指定之字首的文件。
範例：`sta*`
### 搜尋回應
成功完成請求後，回應內文將包含搜尋結果。預設會以 JSON 格式傳回搜尋結果。如果 `format` 參數設為 `xml`，則會以 XML 傳回搜尋結果。
除非您明確指定 `return` 參數，否則將附上每份相符文件 (命中項目) 的文件 ID 及所有可傳回的欄位。回應也會顯示找到的命中總數 (`found`) 以及所列第一份文件的索引 (`start`)。預設情況下，回應會包含前 10 個命中項目。您可在請求中指定 `size` 參數，以控制每次回應所要納入的命中數。若要翻頁瀏覽命中項目，您可以使用 `start` 或 `cursor` 參數。如需詳細資訊，請參閱[對結果進行分頁](paginating-results.md)。
典型的 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 回應如以下範例所示。
```
6.9
Animation
Comedy
Family
Horror
Sci-Fi
Young Victor conducts a science experiment to
bring his beloved dog Sparky back to life, only
to face unintended, sometimes monstrous,
consequences.
2012-09-20T00:00:00Z
Frankenweenie
1462
5220
Tim Burton
http://ia.media-imdb.com/images/M/MV5BMjI
xODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@.
_V1_SX400_.jpg
2012
Winona Ryder
Catherine O'Hara
Martin Short
.
.
.
```
回應格式的設定僅會影響到對於成功請求的回應。錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。由於伺服器逾時和其他請求路由問題而導致的 5xx 錯誤會以 XML 傳回。當請求傳回錯誤代碼時，回應的內文會包含所發生錯誤的相關資訊。如果在剖析和驗證請求內文時發生錯誤，錯誤碼會設為 400，回應內文會包含錯誤清單及其發生位置。
#### 搜尋回應標頭
Content-Type
描述物件資料格式的標準 MIME 類型。如需詳細資訊，請參閱 [W3C RFC 2616 第 14 節](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17)。
有效值：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` 提交建議請求。如需如何控制建議服務存取權的相關資訊，請參閱[設定 Amazon CloudSearch 的存取](configuring-access.md)。
所有建議請求皆必須指定 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 請求傳送至網域搜尋端點的方法，直接在 Web 瀏覽器中輸入請求 URL、使用 cURL 提交請求，或使用您偏好的 HTTP 程式庫產生 HTTP 呼叫。您也可以在 Amazon CloudSearch 主控台中使用 Search Tester 來取得建議。如需詳細資訊，請參閱[使用搜尋測試器進行搜尋](getting-started-search.md#searching-console)。
**重要**
網域的文件和搜尋端點在網域生命週期當中會保持不變。應當對端點進行快取處理，而非在每次上傳或搜尋請求之前擷取端點。在每次請求可能導致您的請求受到調節`DescribeDomains`之前，透過呼叫 `aws cloudsearch describe-domains`或 查詢 Amazon CloudSearch 組態服務。
根據預設，Amazon CloudSearch 會以 JSON 傳回回應。您可藉由指定 `format` 參數 `format=xml` 取得 XML 格式的結果。回應格式的設定僅會影響到對於成功請求的回應。錯誤回應的格式取決於錯誤的源頭。搜尋服務傳回的錯誤一律會以 JSON 傳回。由於伺服器逾時和其他請求路由問題而導致的 5xx 錯誤會以 XML 傳回。
## 建議
### 建議請求
#### 在 Amazon CloudSearch 中建議語法
```
GET /2013-01-01/suggest
```
#### 建議 Amazon CloudSearch 中的請求標頭
HOST
您所查詢的網域其搜尋請求端點。您可以使用 [DescribeDomains](API_DescribeDomains.md) 擷取網域的搜尋請求端點。
必要：是
#### 在 Amazon CloudSearch 中建議請求參數
q
您要取得其建議的字串。
類型：字串
必要：是
suggester
用於尋找所建議相符項目的建議者的名稱。
類型：字串
必要：是
size
欲傳回的建議數目上限。
類型：正整數
預設：10
必要：否
format
指定回應的內容類型。
類型：字串
有效值：json \$1 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 回應如以下範例所示：
```