API 參考

此參考文件描述 Meilisearch RESTful API 的一般行為。

如果您是 Meilisearch 的新手，請查看入門指南。

您可以在此處取得 Meilisearch OpenAPI 規格。

此 API 文件使用以下慣例

• API 路徑中的大括號 ({}) 代表路徑參數，例如，GET /indexes/{index_uid}
• 必填欄位以星號 (*) 標記
• 佔位符文字採用大寫字元並使用底線分隔，例如，MASTER_KEY

在啟動時為 Meilisearch 提供主金鑰，您可以保護您的實例免受未經授權的請求。所提供的主金鑰必須至少 16 個位元組。從那時起，您必須包含 Authorization 標頭以及有效的 API 金鑰，才能存取受保護的路由（除了/health 以外的所有路由）。

# replace the MASTER_KEY placeholder with your master key
curl \
  -X GET 'https://127.0.0.1:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY'

只有使用主金鑰才能存取/keys路由。基於安全考量，我們建議所有其他路由都使用一般的 API 金鑰。

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'

若要瞭解更多關於金鑰和安全性的資訊，請參閱我們的安全性教學。

Meilisearch 會將所有回傳多個資源的 GET 路由進行分頁，例如 GET /indexes、GET /documents、GET /keys 等。這讓您可以使用可管理的小型資料塊。所有這些路由預設會回傳每頁 20 筆結果，但您可以使用 limit 查詢參數進行設定。您可以使用 offset 在頁面之間移動。

所有分頁的回應都包含以下欄位

由於 /tasks 端點使用不同類型的分頁，因此回應包含不同的欄位。您可以在任務 API 參考中閱讀更多相關資訊。

參數是您可以傳遞給 API 端點以修改其回應的選項。Meilisearch API 中有三種主要的參數類型：請求主體參數、路徑參數和查詢參數。

這些參數是 POST、PUT 和 PATCH 請求的必要部分。它們接受各種值和資料類型，具體取決於您要修改的資源。您必須將這些參數新增至您請求的資料承載。

這些是您在端點路徑中傳遞給 API 的參數。它們用於唯一識別資源。您可以有多個路徑參數，例如，/indexes/{index_uid}/documents/{document_id}。

如果端點不採用任何路徑參數，則該端點的文件中不會顯示此區段。

這些可選參數是一系列的鍵值對，並出現在端點中的問號 (?) 後面。您可以使用連字號 (&) 分隔列出多個查詢參數。查詢參數的順序無關緊要。它們主要與 GET 端點一起使用。

如果端點不採用任何查詢參數，則該端點的文件中不會顯示此區段。

任何帶有承載 (--data-binary) 的 API 請求都需要 Content-Type 標頭。內容類型標頭會指示資源的媒體類型，協助客戶端正確處理回應主體。

Meilisearch 目前支援下列格式

• Content-Type: application/json，適用於 JSON
• Content-Type: application/x-ndjson，適用於 NDJSON
• Content-Type: text/csv，適用於 CSV

只有新增文件和更新文件端點接受 NDJSON 和 CSV。對於其他所有端點，請使用 Content-Type: application/json。

Content-Encoding 標頭會指示媒體類型由指定的演算法壓縮。壓縮可藉由傳送和接收較小的承載來提高傳輸速度並降低頻寬消耗。Accept-Encoding 標頭則會指示客戶端可以理解的壓縮演算法。

Meilisearch 支援下列壓縮方法

• br：使用Brotli演算法
• deflate：使用zlib結構以及deflate壓縮演算法
• gzip：使用gzip演算法

以下程式碼範例使用 Content-Encoding: gzip 標頭，表示請求主體使用 gzip 演算法壓縮

 cat ~/movies.json | gzip | curl -X POST 'https://127.0.0.1:7700/indexes/movies/documents' --data-binary @- -H 'Content-Type: application/json' -H 'Content-Encoding: gzip'

如果請求包含 Accept-Encoding 標頭，Meilisearch 就會壓縮回應。以下程式碼範例使用 gzip 演算法

curl -sH 'Accept-encoding: gzip' 'https://127.0.0.1:7700/indexes/movies/search' | gzip -

請求主體是傳送至 API 的資料。它與 PUT、POST 和 PATCH 方法搭配使用，以建立或更新資源。您必須以 JSON 格式提供請求主體。

Meilisearch 是一個非同步 API。這表示，在回應大多數寫入請求時，您會收到 task 物件的摘要版本

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "indexUpdate",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得關於任務狀態的更多詳細資訊。

請參閱關於非同步操作的更多資訊。

Meilisearch API 支援JSON 資料類型。