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

# 在 Amazon CloudSearch 中取得自動完成建議
<a name="getting-suggestions"></a>

本節說明如何設定建議者以讓您能夠擷取建議。未完成的搜尋查詢建議是可能的相符項目，它們可讓您在使用者完成輸入查詢之前顯示可能的相符項目。在 Amazon CloudSearch 中，建議是以特定文字欄位的內容為基礎。當您請求建議時，Amazon CloudSearch 會尋找建議者欄位中值開頭為指定查詢字串的所有文件，欄位開頭必須符合查詢字串，才能視為相符。傳回的資料包含每個相符項目的欄位值和文件 ID。您可以設定建議者尋找完全符合查詢字串的項目，或是執行近似字串比對 (模糊比對) 以更正輸入錯誤和拼字錯誤。

如需建議 API 的詳細資訊，請參閱[搜尋 API 參考](search-api.md) 中的[建議](search-api.md#suggest)。

**Topics**
+ [設定 Amazon CloudSearch 的建議程式](#configuring-suggesters)
+ [在 Amazon CloudSearch 中擷取建議](#retrieving-suggestions)

## 設定 Amazon CloudSearch 的建議程式
<a name="configuring-suggesters"></a>

設定建議者時，您必須為可能相符項目指定您要搜尋的文字欄位名稱，以及建議者的唯一名稱。用於建議的欄位必須啟用傳回。欄位內的資料僅前 512 個位元組將用於產生建議。

建議者名稱必須以字母開頭，長度至少 3 個字元且不超過 64 個字元。允許的字元為：a-z (小寫字母)、0-9 和 \$1 (底線)。建議者名稱是您在擷取建議時於查詢字串中指定，所以最好使用簡短名稱。名稱 *score* 是保留項目，不得做為建議者名稱使用。

建議者還支援以下兩個選項：
+ `FuzzyMatching`—您可以將建議字串相符項目時允許的模糊程度設定為無、低或高。設為 none 時，指定的字串將視為確切字首。設為 low 時，建議項目與指定的字串相差不得超過一個字元。設為 high 時，建議項目可相差多達兩個字元。預設為 none。
+ `SortExpression`—您可以設定此表達式來計算每個建議的分數，以控制排序方式。分數會捨入到最接近的整數，下限為 0 且上限為 2^31-1。提供建議時對文件的相關性分數不做計算，所以排序運算式不得參考 `_score` 值。若要使用數值欄位或現有運算式對建議進行排序，可直接指定該欄位或運算式的名稱。如果沒有為建議者設定任何運算式，則會按字母順序對建議進行排序。請注意，在搜尋請求或其他運算式中不得參考建議者內所定義的運算式。若您另有其他用途要使用這類運算式，請將其加入到您的網域組態並由建議者參考其名稱。如需運算式的相關資訊，請參閱[設定運算式](configuring-expressions.md)。

若您想要透過多個文字欄位取得建議，請為每個欄位各定義一個建議者，並提交個別的建議請求以經由各建議者取得相符項目。最多可以設定 10 個建議者。建議者可能消耗大量的記憶體和磁碟空間，尤其是使用含有大量文字的來源欄位和模糊比對程度設為高的情況。

**提示**  
與其設定由建議者使用取自*「所有」*文件的*「所有」*可能性，不妨考慮對最熱門的 1,000 組或 10,000 組搜尋查詢編製索引，再設定由建議者使用這些查詢。您可以將查詢存放在單獨的 Amazon CloudSearch 索引或僅用於建議的欄位。

定義建議者的最簡單方法是透過 Amazon CloudSearch 主控台中的[**建議者**頁面](#configuring-suggesters-console)。您也可以使用 AWS SDKs 或 定義建議者 AWS CLI。

**重要**  
為您的搜尋網域加入建議者之後，您必須編製索引，才能使用該建議者來擷取建議。隨著文件的添加和刪除，您必須定期重建索引以更新建議。除非您呼叫 `IndexDocuments`，建議內容一概不會反映已添加或刪除的文件。

### 透過 Amazon CloudSearch 主控台設定建議程式
<a name="configuring-suggesters-console"></a>

您可以透過 Amazon CloudSearch 主控台輕鬆新增、更新和刪除建議者。

**加入建議者**

1. 在 [https://console.aws.amazon.com/cloudsearch/home](https://console.aws.amazon.com/cloudsearch/home)：// 開啟 Amazon CloudSearch 主控台。

1. 在左側導覽窗格中選擇 **Domains** (網域)。

1. 選擇網域名稱以開啟其組態。

1. 前往**進階搜尋選項**索引標籤。

1. 在**建議者**窗格中，選擇**新增建議者**。

1. 輸入新建議者的名稱。

1. 對於**來源欄位**，指定要用於建議的文字欄位。

1. 若要包含修正次要拼寫錯誤或錯字的建議，請將**模糊比對**設定為**低**或**高**。設為低時，建議將包括與使用者的查詢字串只相差一個字元的詞彙。設為高時，建議將包括相差多達兩個字元的詞彙。

1. 若要控制建議排序的方式，請在排序表達式欄位中輸入數值**表達**式。此運算式可直接輸入您要用於對建議進行排序的數值欄位的名稱、現有運算式的名稱或任何有效的運算式。如需運算式的相關資訊，請參閱[設定運算式](configuring-expressions.md)。

1. 按一下 **Save changes** (儲存變更)。

1. 當您完成為搜尋網域設定建議者時，您必須先重新索引網域，才能使用建議者。若要執行索引，請前往網域儀表板，然後選擇**動作**、**執行索引**。

### 使用 設定建議程式 AWS CLI
<a name="configuring-suggesters-clt"></a>

您可以使用 `aws cloudsearch define-suggester` 命令，加入或更新建議者。若要移除建議者，請使用 `aws cloudsearch delete-suggester`。

**加入或更新建議者**
+ 執行 `aws cloudsearch define-suggester` 命令。您要使用 `--suggester` 選項以 JSON 格式指定建議者的組態。建議者組態必須用引號括住，而且組態內的所有引號必須用反斜線逸出。如需建議程式組態的格式，請參閱 AWS CLI 命令參考中的 [define-suggester](https://docs.aws.amazon.com/cli/latest/reference/cloudsearch/define-suggester.html)。例如，以下命令設定一個名為 `mysuggester` 的建議者以根據 `title` 欄位傳回建議。

  ```
  aws cloudsearch define-suggester --domain-name movies --suggester "{\"SuggesterName\": \"mysuggester\", \"DocumentSuggesterOptions\": {\"SourceField\":\"title\"}}" 
  {
    "Suggester": {
      "Status": {
        "PendingDeletion": false,
        "State": "RequiresIndexDocuments",
        "CreationDate": "2014-06-26T17:26:43Z",
        "UpdateVersion": 27,
        "UpdateDate": "2014-06-26T17:26:43Z"
      },
      "Options": {
        "DocumentSuggesterOptions": {
          "SourceField": "title"
        },
        "SuggesterName": "mysuggester"
      }
    }
  }
  ```

  您可以使用 `--fuzzy-matching` 選項，以包括對輕微拼字錯誤或錯別字進行更正的建議。模糊比對的有效值為 `none`、`low` 和 `high` (預設為 `none`.) 設為 `low` 時，建議將包括與使用者的查詢字串只相差一個字元的詞彙。設為 `high` 時，建議將包括相差多達兩個字元的詞彙。例如，以下命令設定 `mysuggester` 以包括與使用者的查詢字串只相差一個字元的建議：

  ```
  aws cloudsearch  --name mysuggester --source title 
    --fuzzy-matching low
  ```

  您可以使用 `--sort-expression` 選項來控制所傳回建議的排序方式。任何有效的運算式皆可用於排序 (此選項通常是直接輸入數值欄位的名稱或預先定義的運算式的名稱)。例如，若要根據 `year` 欄位內的值對 `mysuggester` 傳回的建議進行排序，請指定：

  ```
  aws cloudsearch define-suggester --name mysuggester --source title 
    --fuzzy-matching low --sort-expression year
  ```

**刪除建議者**
+ 執行 `aws cloudsearch delete-suggester` 命令並指定 `--name` 選項。例如，若要刪除 `mysuggester`：

  ```
  aws cloudsearch delete-suggester --name mysuggester --delete
  ```

### 使用 AWS 開發套件設定建議者
<a name="configuring-suggesters-sdk"></a>

AWS SDKs (Android 和 iOS SDKs除外） 支援 Amazon CloudSearch 組態 API 中定義的所有 Amazon CloudSearch 動作，包括 `DefineSuggester`。如需安裝與使用 AWS 開發套件的詳細資訊，請參閱 [AWS 軟體開發套件](https://aws.amazon.com/code)。

## 在 Amazon CloudSearch 中擷取建議
<a name="retrieving-suggestions"></a>

您可透過 HTTP GET 傳送請求至網域搜尋端點上的 `suggest` 資源以擷取建議。例如：

```
http://search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.
amazonaws.com/2013-01-01/suggest?q=oce&suggester=mysuggester
```

請求中必須指定 API 版本，且查詢字串必須採用 URL 編碼。建議請求的大小上限為 8190 位元組，包括 HTTP 方法、URI 及通訊協定版本在內。

 `suggest` 資源支援四個參數：
+ `q` - 您要取得其建議的字串。
+ `suggester` - 您要使用的建議者的名稱。
+ `size`- 要擷取的建議數目。預設會傳回前十名的建議 （建議會根據建議程式中定義的排序表達式進行排序。 如果建議者中未定義排序表達式，建議會依字母順序排序。)
+ `format`- 回應的內容類型，`json`或 `xml`。預設會以 JSON 格式傳回建議。

務必指定 `q` 和 `suggester` 參數。若您請求就空字串提供建議，則不會傳回任何建議。`size` 和 `format` 是選用參數。

以下範例將根據 `title` 欄位的內容，取得對字串 `oce` 的建議。

```
http://search-imdb2-m2brrr7ex7z6sqhgwsjdmcuvd4.us-east-1.cloudsearch.amazonaws.com/2013-01-01/suggest?q=oce&suggester=title
{
  "status": {
    "rid": "646f5s0oDAr8pVk=",
    "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"
      }
    ]
  }
}
```