Aloha！又是我少女人妻 Uerica！明天就要收假拉，大家有沒有多做點收心操阿，想到以前連假根本沒在收心，搞得我連假都放得比別人久阿哈哈哈哈！

前面我們講的都是 App Search 搭配 Search UI 套件的用法， App Search 其實有提供很多 API 可以使用，而我們之前用的 @elastic/react-search-ui 中已經有很多 Search UI 接好的 API 寫成 Components 可直接使用。

不過不管有沒有要搭配Search UI使用，還是得了解 App Search 有提供哪些 API ，以及須注意的限制有哪些，所以接下來會開始介紹 App Search 提供的 API 有哪些拉～

API Reference

在介紹App Search 提供的 API 之前，有幾個需要注意的細節，在下列一一概述。

資料庫設計、欄位型態

在進行資料庫設計時，須注意以下幾點 :

• 新的欄位資料與現有的文件欄位資料型態需一致
• 不支持巢狀的物件架構
• 可以使用 Array
• 欄位創建後就無法刪除

欄位型態有 Text 、 Number 、 Date 、 Geolocation 四種 :

text 型態

所有希望被搜尋的資料型態都應該用text，text是被搜尋的核心，所以默認的資料型態都是text。text可使用多種語言，且有配置的 Engine language 的智能

Number 型態

使用有限的雙精度浮點值 : 3.14 或 42 。Number 型態欄位可排序、過濾、篩選以及提升。

Date 型態

日期必須為 ISO 8601 格式，例如: " 2020-09-24T19:00:00+08:00 "。

Geolocation 型態

地理位置座標的欄位型態，可以按照指定點的距離進行過濾。資料中需包含經度和緯度，例如 : " 24.97738,121.5372 "。

欄位型態支援的功能

Queries

Boosts

Filters, Facets, Grouping, Sorting

參數編碼

所有 App Search 的接都接受 JSON-encoded 的參數，以下是推薦的方法，且App Search的範例文件都會用此方法

Example - JSON request body

curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx' \
-d '{
  "page": {
    "current": 2,
    "size": 15
  }
}'

但也可以使用查詢參數的編碼方式
Example - Rails-style query parameters

curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/documents/list?page[size]=15&page[current]=2' \
-H 'Authorization: Bearer private-xxxxxxxxxxxxxxxxxxxx'

兩種方法返回的結果都相同

查詢語法

支援字串 "+"或"-" 以及 AND OR NOT 語法
Example - Performing a single query search using Lucene Query Syntax.

curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "wyoming AND montana OR california NOT washington"
}'

壓縮 gzip

API 支援 gzip ，API請求中可寫入包含Accept-Encoding 的標頭，使用此標頭來通知API，可接受gzip壓縮的檔案回傳

curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/national-parks-demo/search' \
-H 'Content-Type: application/json' \
-H 'Accept-Encoding: gzip' \
-H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \
-d '{
  "query": "everglade"
}'

錯誤處理

創建API請求時可能會以下幾種錯誤

無效Keys

如果使用不正確會收到以下錯誤訊息

{
  "error": "Invalid authentication token."
}

程式碼錯誤、請求異常

如果格式有誤，會收到以下錯誤訊息

{
  "errors": [
    "There was a decoding error. Please ensure your request is valid."
  ]
}

要解決此問題，請確保以正確的方式格式化所有 JSON 物件或 URL 參數。

特定端點錯誤

有可能狀態碼為200還是無法成功發出請求，這時可以試著從端點末端查找錯誤的部分，以下為錯誤釋例

{
  "errors": [
    "Missing required parameter: filters[date][from]"
  ]
}

{
  "errors": [
    "curation must include either promoted or hidden"
  ]
}

限度

App Search API 最多回傳 100 頁，每頁最多回傳 1000 個結果，所以每個查詢最多回傳 10,000 筆資料結果，這是 Elasticsearch 預設限制限制。

今天就先獎到這邊拉！感謝閱讀～明天見摟，祝福大家明天上班一切順利哈哈哈，晚安掰掰