租户令牌负载参考

Meilisearch 的租户令牌是 JSON Web Tokens (JWTs)。其负载由三个元素组成：搜索规则、API 密钥 UID 和可选的过期日期。

​

示例负载

{
  "exp": 1646756934,
  "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab",
  "searchRules": {
    "INDEX_NAME": {
      "filter": "attribute = value"
    }
  }
}

​

搜索规则

搜索规则对象是一组指令，定义了 Meilisearch 在使用特定租户令牌进行查询时将强制执行的搜索参数。

​

搜索规则对象

searchRules 必须是一个 JSON 对象。每个键必须对应一个或多个索引：

{
  "searchRules": {
    "*": {},
    "INDEX_*": {},
    "INDEX_NAME_A": {}
  }
}

每个搜索规则对象可以包含一个 filter 键。这个 filter 的值必须是一个过滤表达式：

{
  "*": {
    "filter": "attribute_A = value_X AND attribute_B = value_Y"
  }
}

Meilisearch 会将过滤器应用于使用该租户令牌进行的所有搜索。令牌只能访问 searchRules 对象中存在的索引。

一个令牌可以包含任意数量索引的规则。特定规则集优先并覆盖 * 规则。

搜索规则也可以是一个空对象。这种情况下，租户令牌将可以访问索引中的所有文档：

{
  "INDEX_NAME": {}
}

​

示例

​

单一过滤器

在此示例中，用户将只能获取 user_id 等于 1 的 medical_records 文档：

{
  "medical_records": {
    "filter": "user_id = 1"
  }
}

​

多重过滤器

在此示例中，用户将只能获取 user_id 等于 1 且 published 字段为 true 的 medical_records 文档：

{
  "medical_records": {
    "filter": "user_id = 1 AND published = true"
  }
}

​

授予对索引中所有文档的访问权限

在此示例中，用户可以访问 medical_records 中的所有文档：

{
  "medical_records": {}
}

​

使用部分通配符匹配多个索引

在此示例中，用户将获取任何以 medical 开头的索引中的文档。这包括诸如 medical_records 和 medical_patents 等索引：

{
  "medical*": {
    "filter": "user_id = 1"
  }
}

​

使用通配符匹配所有索引

在此示例中，用户将获取整个实例中任何索引的文档：

{
  "*": {
    "filter": "user_id = 1"
  }
}

​

手动指定多个索引

在此示例中，用户对所有索引（除一个外）中 user_id = 1 的文档都有访问权限。当查询 medical_records 时，用户只能访问已发布的文档：

{
  "*": {
    "filter": "user_id = 1"
  },
  "medical_records": {
    "filter": "user_id = 1 AND published = true",
  }
}

​

API key UID（API密钥唯一标识符）

租户令牌（tenant token）的有效载荷中必须包含用于验证请求的 API key UID。UID 是一个用于标识 API 密钥的字母数字字符串：

{
  "apiKeyUid": "at5cd97d-5a4b-4226-a868-2d0eb6d197ab"
}

可以通过查询获取单个API密钥端点来获取 API key 的 UID。

该 UID 必须指向具有搜索操作权限的 API 密钥。生成的令牌将拥有与用于创建它的 API 密钥相同的索引和路由访问权限。

由于主密钥（master key）不是 API 密钥，因此不能使用主密钥来创建租户令牌。请避免暴露 API 密钥，始终在应用程序的后端生成令牌。

​

过期时间

过期时间必须是一个 UNIX 时间戳或设为 null：

{
  "exp": 1646756934
}

令牌的过期时间不能超过其父 API 密钥的过期时间。

设置令牌过期时间是可选的，但强烈建议这样做。没有过期时间的令牌将无限期有效，可能会带来安全隐患。