金鑰

/keys 路由允許您建立、管理和刪除 API 金鑰。若要使用這些端點，您必須先設定主金鑰。設定主金鑰後，您可以在請求的標頭中提供該金鑰，或者使用有權限執行 keys.get、keys.create、keys.update 或 keys.delete 操作的 API 金鑰來存取這些端點。

警告

存取 /keys 路由時，若未設定主金鑰，將會拋出 missing_master_key 錯誤。

金鑰物件

json

{
  "name": "Default Search API Key",
  "description": "Use it to search from the frontend code",
  "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
  "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
  "actions": [
    "search"
  ],
  "indexes": [
    "*"
  ],
  "expiresAt": null,
  "createdAt": "2021-08-11T10:00:00Z",
  "updatedAt": "2021-08-11T10:00:00Z"
}

`name`

類型: 字串
預設值: null
描述: 金鑰的人工可讀名稱

`description`

類型: 字串
預設值: null
描述: 金鑰的描述。您可以在此新增關於金鑰的任何重要資訊

`uid`

類型: 字串
預設值: 不適用
描述: 用於識別 API 金鑰的 uuid v4。若未指定，Meilisearch 會自動產生

`key`

類型: 字串
預設值: 不適用
描述: 由 Meilisearch 在建立 API 金鑰時，透過雜湊 uid 和主金鑰所產生的字母數字金鑰值。當呼叫受保護的 Meilisearch 實例時，用於授權

此值也用作 {key} 路徑變數，以更新、刪除或取得特定的金鑰。

如果主金鑰變更，所有 key 值都會自動變更。

在不同實例之間重複使用 API 金鑰

自訂 API 金鑰是確定性的：key 是 uid 和主金鑰的 SHA256 雜湊值。若要重複使用自訂 API 金鑰，請使用相同的主金鑰啟動新實例，並使用相同的 uid 重新建立您的 API 金鑰。

您無法在不同實例之間重複使用預設的 API 金鑰。 Meilisearch 會在您首次啟動實例時自動產生其 uid。

`actions`

類型: 陣列
預設值: 不適用
描述: 金鑰允許的 API 操作陣列，以字串表示。API 操作僅在授權的 indexes 上才有可能。["*"] 代表所有操作。

您可以使用 * 作為萬用字元，以存取 documents、indexes、tasks、settings、stats 和 dumps 操作的所有端點。例如，documents.* 可存取所有文件操作。

警告

基於安全考量，我們不建議建立可執行所有操作的金鑰。

名稱	描述
`search`	提供存取 `POST` 和 `GET` 搜尋端點的權限
`documents.add`	提供存取新增文件和更新文件端點的權限
`documents.get`	提供存取取得單一文件、使用 POST 取得文件和使用 GET 取得文件端點的權限
`documents.delete`	提供存取刪除單一文件、刪除所有文件、批次刪除和依篩選條件刪除端點的權限
`indexes.create`	提供存取建立索引端點的權限
`indexes.get`	提供存取取得單一索引和列出所有索引端點的權限。回應中會省略未授權的 `indexes`
`indexes.update`	提供存取更新索引端點的權限
`indexes.delete`	提供存取刪除索引端點的權限
`indexes.swap`	提供存取交換索引端點的權限。不會交換未授權的 `indexes`
`tasks.get`	提供存取取得單一任務和取得任務端點的權限。回應中會省略來自未授權 `indexes` 的任務
`tasks.cancel`	提供存取取消任務端點的權限。不會取消來自未授權 `indexes` 的任務
`tasks.delete`	提供存取刪除任務端點的權限。不會刪除來自未授權 `indexes` 的任務
`settings.get`	提供存取取得設定端點以及所有子路由的等效端點的權限
`settings.update`	提供存取更新設定和重設設定端點以及所有子路由的等效端點的權限
`stats.get`	提供存取取得索引統計資料端點和取得所有索引統計資料端點的權限。對於後者，回應中會省略未授權的 `indexes`
`dumps.create`	提供存取建立傾印端點的權限。不受 `indexes` 限制
`snapshots.create`	提供存取建立快照端點的權限。不受 `indexes` 限制
`version`	提供存取取得 Meilisearch 版本端點的權限
`keys.get`	提供存取取得所有金鑰端點的權限
`keys.create`	提供存取建立金鑰端點的權限
`keys.update`	提供存取更新金鑰端點的權限
`keys.delete`	提供存取刪除金鑰端點的權限

`indexes`

類型: 陣列
預設值: 不適用
描述: 金鑰授權可操作的索引陣列。使用 ["*"] 表示所有索引。只有金鑰的允許操作才能在這些索引上使用。

您也可以在字串結尾新增 * 字元作為萬用字元。這允許 API 金鑰存取所有以該字串開頭的索引名稱。例如，使用 "indexes": ["movie*"] 將允許 API 金鑰存取 movies 和 movie_ratings 索引。

`expiresAt`

類型: 字串
預設值: 不適用
描述: 金鑰過期的日期和時間，以 RFC 3339 格式表示。null 表示金鑰永不過期

注意

一旦金鑰超過其 expiresAt 日期，使用它進行 API 授權將會傳回錯誤。

查詢參數	預設值	描述
`offset`	`0`	要跳過的金鑰數量
`limit`	`20`	要傳回的金鑰數量

回應

名稱	類型	描述
`results`	陣列	金鑰物件的陣列
`offset`	Integer	已跳過的金鑰數量
`limit`	Integer	傳回的金鑰數量
`total`	Integer	API 金鑰總數

範例

curl \
  -X GET 'https://127.0.0.1:7700/keys?limit=3' \
  -H 'Authorization: Bearer MASTER_KEY'

回應: `200 Ok`

json

{
  "results": [
    {
      "name": null,
      "description": "Manage documents: Products/Reviews API key",
      "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
      "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
      "actions": [
        "documents.add",
        "documents.delete"
      ],
      "indexes": [
        "prod*",
        "reviews"
      ],
      "expiresAt": "2021-12-31T23:59:59Z",
      "createdAt": "2021-10-12T00:00:00Z",
      "updatedAt": "2021-10-13T15:00:00Z"
    },
    {
      "name": "Default Search API Key",
      "description": "Use it to search from the frontend code",
      "key": "0a6e572506c52ab0bd6195921575d23092b7f0c284ab4ac86d12346c33057f99",
      "uid": "74c9c733-3368-4738-bbe5-1d18a5fecb37",
      "actions": [
        "search"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    },
    {
      "name": "Default Admin API Key",
      "description": "Use it for anything that is not a search operation. Caution! Do not expose it on a public frontend",
      "key": "380689dd379232519a54d15935750cc7625620a2ea2fc06907cb40ba5b421b6f",
      "uid": "20f7e4c4-612c-4dd1-b783-7934cc038213",
      "actions": [
        "*"
      ],
      "indexes": [
        "*"
      ],
      "expiresAt": null,
      "createdAt": "2021-08-11T10:00:00Z",
      "updatedAt": "2021-08-11T10:00:00Z"
    }
  ],
  "offset":0,
  "limit":3,
  "total":7
}

注意

API 金鑰會根據其 createdAt 日期以遞減順序顯示。這表示最近建立的金鑰會先出現。

取得單一金鑰

GET/keys/{key_or_uid}

取得指定金鑰的資訊。若嘗試使用此端點來存取不存在或已刪除的金鑰，將會導致錯誤。

路徑參數

需要一個有效的 API key 或 uid。

名稱	類型	描述
`key` *	字串	請求的 API 金鑰的 `key` 值
`uid` *	字串	請求的 API 金鑰的 `uid`

範例

curl \
  -X GET 'https://127.0.0.1:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

回應: `200 Ok`

json

{
  "name": null,
  "description": "Add documents: Products API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

關於這些欄位的說明，請參閱金鑰物件。

建立金鑰

POST/keys

使用提供的描述、權限和到期日建立 API 金鑰。

請求主體

名稱	類型	預設值	描述
`actions` *	陣列	不適用	金鑰允許執行的 API 操作列表。`["*"]` 代表所有操作
`indexes` *	陣列	不適用	金鑰被授權可操作的索引陣列。`["*"]` 代表所有索引
`expiresAt` *	字串	不適用	金鑰到期的日期和時間，以 RFC 3339 格式表示。如果金鑰永不到期，則為 `null`
`name`	字串	`null`	金鑰的人類可讀名稱
`uid`	字串	不適用	用於識別 API 金鑰的 uuid v4。如果未指定，則由 Meilisearch 產生
`description`	字串	`null`	金鑰的可選描述

範例

curl \
  -X POST 'https://127.0.0.1:7700/keys' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Add documents: Products API key",
    "actions": ["documents.add"],
    "indexes": ["products"],
    "expiresAt": "2042-04-02T00:42:42Z"
  }'

回應：`201 Created`

json

{
  "name": null,
  "description": "Manage documents: Products/Reviews API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add"
  ],
  "indexes": [
    "products"
  ],
  "expiresAt": "2021-11-13T00:00:00Z",
  "createdAt": "2021-11-12T10:00:00Z",
  "updatedAt": "2021-11-12T10:00:00Z"
}

更新金鑰

PATCH/keys/{key_or_uid}

更新 API 金鑰的 name 和 description。

金鑰的更新是部分的。這表示您應該只提供您要更新的欄位，因為任何未出現在 Payload 中的欄位將保持不變。

路徑參數

需要一個有效的 API key 或 uid。

名稱	類型	描述
`key` *	字串	請求的 API 金鑰的 `key` 值
`uid` *	字串	請求的 API 金鑰的 `uid`

請求主體

名稱	類型	預設值	描述
`name`	字串	`null`	金鑰的人類可讀名稱
`description`	字串	`null`	金鑰的可選描述

範例

curl \
  -X PATCH 'https://127.0.0.1:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "name": "Products/Reviews API key",
    "description": "Manage documents: Products/Reviews API key"
  }'

回應: `200 Ok`

json

{
  "name": "Products/Reviews API key",
  "description": "Manage documents: Products/Reviews API key",
  "key": "d0552b41536279a0ad88bd595327b96f01176a60c2243e906c52ac02375f9bc4",
  "uid": "6062abda-a5aa-4414-ac91-ecd7944c0f8d",
  "actions": [
    "documents.add",
    "documents.delete"
  ],
  "indexes": [
    "products",
    "reviews"
  ],
  "expiresAt": "2021-12-31T23:59:59Z",
  "createdAt": "2021-10-12T00:00:00Z",
  "updatedAt": "2021-10-13T15:00:00Z"
}

刪除金鑰

DELETE/keys/{key_or_uid}

刪除指定的 API 金鑰。

路徑參數

需要一個有效的 API key 或 uid。

名稱	類型	描述
`key` *	字串	請求的 API 金鑰的 `key` 值
`uid` *	字串	請求的 API 金鑰的 `uid`

範例

curl \
  -X DELETE 'https://127.0.0.1:7700/keys/6062abda-a5aa-4414-ac91-ecd7944c0f8d' \
  -H 'Authorization: Bearer MASTER_KEY'

回應：`204 No Content`

編輯此頁面

這有幫助嗎？

想加入更多細節嗎？提出問題在我們的公開文件儲存庫中。

金鑰

警告

金鑰物件

`name`

`description`

`uid`

`key`

在不同實例之間重複使用 API 金鑰

`actions`

警告

`indexes`

`expiresAt`

注意

`createdAt`

`updatedAt`

取得所有金鑰

查詢參數

回應

範例

回應: `200 Ok`

注意

取得單一金鑰

路徑參數

範例

回應: `200 Ok`

建立金鑰

請求主體

範例

回應：`201 Created`

更新金鑰

路徑參數

請求主體

範例

回應: `200 Ok`

刪除金鑰

路徑參數

範例

回應：`204 No Content`

這有幫助嗎？

金鑰

警告

金鑰物件

name

description

uid

key

在不同實例之間重複使用 API 金鑰

actions

警告

indexes

expiresAt

注意

createdAt

updatedAt

取得所有金鑰

查詢參數

回應

範例

回應: 200 Ok

注意

取得單一金鑰

路徑參數

範例

回應: 200 Ok

建立金鑰

請求主體

範例

回應：201 Created

更新金鑰

路徑參數

請求主體

範例

回應: 200 Ok

刪除金鑰

路徑參數

範例

回應：204 No Content

這有幫助嗎？

`name`

`description`

`uid`

`key`

`actions`

`indexes`

`expiresAt`

`createdAt`

`updatedAt`

回應: `200 Ok`

回應: `200 Ok`

回應：`201 Created`

回應: `200 Ok`

回應：`204 No Content`