Meilisearch 中文文档

/tasks 路由提供了关于异步操作进度的信息。

任务对象

{
  "uid": 4,
  "batchUids": 0,
  "indexUid": "movie",
  "status": "failed",
  "type": "indexDeletion",
  "canceledBy": null,
  "details": {
    "deletedDocuments": 0
  },
  "error": {
    "message": "Index `movie` not found.",
    "code": "index_not_found",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#index_not_found"
  },
  "duration": "PT0.001192S",
  "enqueuedAt": "2022-08-04T12:28:15.159167Z",
  "startedAt": "2022-08-04T12:28:15.161996Z",
  "finishedAt": "2022-08-04T12:28:15.163188Z"
}

`uid`

类型: 整数

描述: 任务的唯一顺序标识符。

任务 uid 在整个实例的所有索引中递增。

`batchUid`

类型: 整数

描述: 该任务所属批次的唯一顺序标识符。

批次 uid 在整个实例的所有索引中递增。

`indexUid`

类型: 字符串

描述: 目标索引的唯一标识符

对于全局任务，此值始终为 null。

`status`

类型: 字符串

描述: 任务状态。可能的值包括 enqueued（排队中）、processing（处理中）、succeeded（成功）、failed（失败）和 canceled（已取消）

`type`

类型: 字符串

描述: 任务执行的操作类型。可能的值包括 indexCreation（索引创建）、indexUpdate（索引更新）、indexDeletion（索引删除）、indexSwap（索引交换）、documentAdditionOrUpdate（文档添加或更新）、documentDeletion（文档删除）、settingsUpdate（设置更新）、dumpCreation（转储创建）、taskCancelation（任务取消）、taskDeletion（任务删除）、databaseUpgrade（数据库升级）、documentEdition（文档编辑）和 snapshotCreation（快照创建）

`canceledBy`

类型: 整数

描述：如果任务被取消，canceledBy 字段会包含一个 taskCancelation 任务的 uid。如果任务未被取消，canceledBy 始终为 null

`details`

类型: 对象

描述: 任务负载的详细信息。该对象的内容取决于任务的 type 类型

`documentAdditionOrUpdate`（文档添加或更新）

名称	描述
`receivedDocuments`	接收到的文档数量
`indexedDocuments`	已索引的文档数量。当任务状态为 `enqueued` 或 `processing` 时值为 `null`

`documentDeletion`（文档删除）

名称	描述
`providedIds`	排队等待删除的文档数量
`originalFilter`	用于删除文档的过滤器。未指定时为 `null`
`deletedDocuments`	已删除的文档数量。当任务状态为 `enqueued` 或 `processing` 时值为 `null`

`indexCreation`（索引创建）

名称	描述
`primaryKey`	索引创建时提供的 `primaryKey` 字段值。未指定时为 `null`

`indexUpdate`

名称	描述
`primaryKey`	索引更新时提供的 `primaryKey` 字段值。如果未指定则为 `null`

`indexDeletion`

名称	描述
`deletedDocuments`	已删除文档的数量。该值应等于被删除索引中的文档总数。当任务状态为 `enqueued` 或 `processing` 时为 `null`

`indexSwap`

名称	描述
`swaps`	包含 `indexSwap` 任务有效载荷的对象

`settingsUpdate`（设置更新）

名称	描述
`rankingRules`	排序规则列表
`filterableAttributes`	可筛选属性列表
`distinctAttribute`	去重属性
`searchableAttributes`	可搜索属性列表
`displayedAttributes`	展示属性列表
`sortableAttributes`	可排序属性列表
`stopWords`	停用词列表
`synonyms`	同义词列表
`typoTolerance`	`typoTolerance`（拼写容错）对象
`pagination`	`pagination`（分页）对象
`faceting`	`faceting`（分面）对象

`dumpCreation`（转储创建）

名称	描述
`dumpUid`	转储生成的唯一标识符 `uid`，同时也是生成的转储文件名。当任务状态为 `enqueued`（排队中）、`processing`（处理中）、`canceled`（已取消）或 `failed`（失败）时，该值为 `null`

`taskCancelation`

名称	描述
`matchedTasks`	匹配到的任务数量。如果请求使用的 API 密钥没有某个索引的访问权限，与该索引相关的任务将不会计入 `matchedTasks`
`canceledTasks`	成功取消的任务数量。如果任务取消失败，该值将为 `0`。当任务状态为 `enqueued` 或 `processing` 时值为 `null`
`originalFilter`	在取消任务请求中使用的过滤器

任务取消操作可能成功但依然显示 canceledTasks: 0。这种情况发生在 matchedTasks 匹配到已完成的任务时（包括 succeeded、failed 或 canceled 状态的任务）。

`taskDeletion`（任务删除）

名称	描述
`matchedTasks`	匹配的任务数量。如果请求使用的 API 密钥无权访问某个索引，与该索引相关的任务将不会计入 `matchedTasks`
`deletedTasks`	成功删除的任务数量。如果任务删除失败，该值将为 `0`。当任务状态为 `enqueued` 或 `processing` 时，该值为 `null`
`originalFilter`	删除任务请求中使用的过滤器

任务删除可能成功但仍显示 deletedTasks: 0。这种情况发生在 matchedTasks 匹配到 enqueued 或 processing 状态的任务时。

`snapshotCreation`（快照创建）

对于 snapshotCreation 任务，details 对象被设为 null。

`error`（错误）

类型: 对象

描述: 如果任务处于 failed 状态，则该对象包含错误定义。否则设为 null

名称	描述
`message`	人类可读的错误描述
`code`	错误代码
`type`	错误类型
`link`	文档相关章节的链接

`duration`（持续时间）

类型: 字符串

描述：任务处于 processing（处理中）状态的总耗时，以 ISO 8601 格式表示

`enqueuedAt`

类型：字符串

描述：任务首次进入 enqueued（排队中）状态的日期和时间，以 RFC 3339 格式表示

`startedAt`

类型：字符串

描述：任务开始 processing（处理中）的日期和时间，以 RFC 3339 格式表示

`finishedAt`

类型：字符串

描述：任务完成 processing（处理中）的日期和时间，无论最终状态是 failed（失败）、succeeded（成功）还是 canceled（取消），均以 RFC 3339 格式表示

任务摘要对象

当 API 请求触发异步进程时，Meilisearch 会返回一个任务摘要对象。该对象包含以下字段：

字段	类型	描述
`taskUid`	整数	唯一顺序标识符
`indexUid`	字符串	唯一索引标识符（对于全局任务始终为 `null`）
`status`	字符串	任务状态。值为 `enqueued`
`type`	字符串	任务类型
`enqueuedAt`	字符串	表示任务进入队列时的日期和时间，格式为 RFC 3339

您可以使用这个 taskUid 来获取任务状态的更多详情。

获取任务列表

GET

/tasks

列出所有全局任务，不区分索引。task 对象包含在 results 数组中。

任务总是按照 uid 降序返回。这意味着默认情况下，最近创建的 task 对象会最先显示。

任务结果支持分页和过滤。

查询参数

查询参数	默认值	描述
`uids`	`*` (所有 uid)	按任务 `uid` 过滤。多个任务 `uid` 用逗号 (`,`) 分隔
`batchUids`	`*` (所有批次 uid)	按任务 `batchUid` 过滤。多个 `batchUids` 用逗号 (`,`) 分隔
`statuses`	`*` (所有状态)	按任务 `status` 过滤。多个任务 `statuses` 用逗号 (`,`) 分隔
`types`	`*` (所有类型)	按任务 `type` 过滤。多个任务 `types` 用逗号 (`,`) 分隔
`indexUids`	`*` (所有索引)	按任务 `indexUid` 过滤。多个任务 `indexUids` 用逗号 (`,`) 分隔。区分大小写
`limit`	`20`	返回的任务数量
`from`	最后创建任务的 `uid`	返回的第一个任务的 `uid`
`reverse`	`false`	如果为 `true`，则按相反顺序返回结果，从最旧到最新
`canceledBy`	不适用	按任务的 `canceledBy` 字段过滤。多个任务 `uid` 用逗号 (`,`) 分隔
`beforeEnqueuedAt`	`*` (所有任务)	按任务的 `enqueuedAt` 字段过滤
`beforeStartedAt`	`*` (所有任务)	按任务的 `startedAt` 字段过滤
`beforeFinishedAt`	`*` (所有任务)	按任务的 `finishedAt` 字段过滤
`afterEnqueuedAt`	`*` (所有任务)	按任务的 `enqueuedAt` 字段过滤
`afterStartedAt`	`*` (所有任务)	按任务的 `startedAt` 字段过滤
`afterFinishedAt`	`*` (所有任务)	按任务的 `finishedAt` 字段过滤

响应

名称	类型	描述
`results`	数组	包含任务对象的数组
`total`	整数	符合过滤器或查询条件的任务总数
`limit`	整数	返回的任务数量
`from`	整数	返回的第一个任务的 `uid`
`next`	整数	传递给 `from` 以查看下一页结果的值。当 `next` 的值为 `null` 时，表示没有更多任务可查看

示例

curl \
  -X GET 'MEILISEARCH_URL/tasks'

响应: `200 Ok`

{
  "results": [
    {
      "uid": 1,
      "indexUid": "movies_reviews",
      "status": "failed",
      "type": "documentAdditionOrUpdate",
      "canceledBy": null,
      "details": {
        "receivedDocuments": 100,
        "indexedDocuments": 0
      },
      "error": null,
      "duration": null,
      "enqueuedAt": "2021-08-12T10:00:00.000000Z",
      "startedAt": null,
      "finishedAt": null
    },
    {
      "uid": 0,
      "indexUid": "movies",
      "status": "succeeded",
      "type": "documentAdditionOrUpdate",
      "canceledBy": null,
      "details": {
        "receivedDocuments": 100,
        "indexedDocuments": 100
      },
      "error": null,
      "duration": "PT16S",
      "enqueuedAt": "2021-08-11T09:25:53.000000Z",
      "startedAt": "2021-08-11T10:03:00.000000Z",
      "finishedAt": "2021-08-11T10:03:16.000000Z"
    }
  ],
  "total": 50,
  "limit": 20,
  "from": 1,
  "next": null
}

获取单个任务

GET

/tasks/{task_uid}

获取单个任务的信息。

如果尝试获取一个已被删除的任务，Meilisearch 会返回 task_not_found 错误。

路径参数

名称	类型	描述
`task_uid` *	String	请求任务的 `uid` 标识符

示例

curl \
  -X GET 'MEILISEARCH_URL/tasks/1'

响应: `200 Ok`

{
  "uid": 1,
  "indexUid": "movies",
  "status": "succeeded",
  "type": "settingsUpdate",
  "canceledBy": null,
  "details": {
    "rankingRules": [
      "typo",
      "ranking:desc",
      "words",
      "proximity",
      "attribute",
      "exactness"
    ]
  },
  "error": null,
  "duration": "PT1S",
  "enqueuedAt": "2021-08-10T14:29:17.000000Z",
  "startedAt": "2021-08-10T14:29:18.000000Z",
  "finishedAt": "2021-08-10T14:29:19.000000Z"
}

取消任务

POST

/tasks/cancel?{query_parameter}

根据任务的 uid、status、type、indexUid 或它们的入队时间 (enqueuedAt) 和处理时间 (startedAt)，取消任意数量的 enqueued（已入队）或 processing（处理中）任务。

任务取消是一个原子事务：要么所有任务都成功取消，要么都不取消。

为了防止用户意外取消所有已入队和处理中的任务，当此路由在没有过滤器的情况下使用时（POST /tasks/cancel），Meilisearch 会抛出 missing_task_filters 错误。

你也可以取消处于 enqueued 或 processing 状态的 taskCancelation（任务取消）类型任务。这是可能的，因为 taskCancelation 类型的任务是按相反顺序处理的，最后入队的任务会最先被处理。

查询参数

必须提供有效的 uids、statuses、types、indexUids 或日期（beforeXAt 或 afterXAt）参数。

查询参数	描述
`uids`	根据 `uid` 取消任务。多个 `uids` 用逗号 (`,`) 分隔。使用 `uids=*` 表示所有 `uids`
`statuses`	根据 `status` 取消任务。多个 `statuses` 用逗号 (`,`) 分隔。使用 `statuses=*` 表示所有 `statuses`
`types`	根据 `type` 取消任务。多个 `types` 用逗号 (`,`) 分隔。使用 `types=*` 表示所有 `types`
`indexUids`	根据 `indexUid` 取消任务。多个 `uids` 用逗号 (`,`) 分隔。使用 `indexUids=*` 表示所有 `indexUids`。区分大小写
`beforeEnqueuedAt`	取消早于指定 `enqueuedAt` 日期的任务。使用 `beforeEnqueuedAt=*` 取消所有任务
`beforeStartedAt`	取消早于指定 `startedAt` 日期的任务。使用 `beforeStartedAt=*` 取消所有任务
`afterEnqueuedAt`	取消晚于指定 `enqueuedAt` 日期的任务。使用 `afterEnqueuedAt=*` 取消所有任务
`afterStartedAt`	取消晚于指定 `startedAt` 日期的任务。使用 `afterStartedAt=*` 取消所有任务

日期过滤器等同于 < 或 > 操作。目前无法使用日期过滤器执行 ≤ 或 ≥ 操作。

了解更多关于任务过滤的信息，请参阅我们的专用指南。

示例

curl \
  -X POST 'MEILISEARCH_URL/tasks/cancel?uids=1,2'

响应: `200 Ok`

{
  "taskUid": 3,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskCancelation",
  "enqueuedAt": "2021-08-12T10:00:00.000000Z"
}

由于 taskCancelation 是一个全局任务，它的 indexUid 始终为 null。

您可以使用这个 taskUid 来获取任务状态的更多详细信息。

取消所有任务

您可以使用以下过滤器取消所有 processing（处理中）和 enqueued（排队中）的任务：

POST

/tasks/cancel?statuses=processing,enqueued

使用的 API 密钥必须拥有所有索引的访问权限（"indexes": [*]）以及 task.cancel 操作权限。

删除任务

DELETE

/tasks?{query_parameter}

根据 uid、status、type、indexUid、canceledBy 或日期删除已完成（succeeded、failed 或 canceled）的任务。任务删除是原子操作：要么所有任务成功删除，要么都不删除。

为防止用户意外删除整个任务历史记录，如果未使用任何过滤器调用此路由（DELETE /tasks），Meilisearch 会抛出 missing_task_filters 错误。

查询参数

必须提供有效的 uids、statuses、types、indexUids、canceledBy 或日期（beforeXAt 或 afterXAt）参数。

查询参数	描述
`uids`	根据 `uid` 删除任务。多个 `uids` 用逗号（`,`）分隔。使用 `uids=*` 表示所有 `uids`
`statuses`	根据 `status` 删除任务。多个 `statuses` 用逗号（`,`）分隔。使用 `statuses=*` 表示所有 `statuses`
`types`	根据 `type` 删除任务。多个 `types` 用逗号（`,`）分隔。使用 `types=*` 表示所有 `types`
`indexUids`	根据 `indexUid` 删除任务。多个 `uids` 用逗号（`,`）分隔。使用 `indexUids=*` 表示所有 `indexUids`。区分大小写
`canceledBy`	根据 `canceledBy` 字段删除任务
`beforeEnqueuedAt`	删除指定 `enqueuedAt` 日期之前的任务。使用 `beforeEnqueuedAt=*` 删除所有任务
`beforeStartedAt`	删除指定 `startedAt` 日期之前的任务。使用 `beforeStartedAt=*` 删除所有任务
`beforeFinishedAt`	删除指定 `finishedAt` 日期之前的任务。使用 `beforeFinishedAt=*` 删除所有任务
`afterEnqueuedAt`	删除指定 `enqueuedAt` 日期之后的任务。使用 `afterEnqueuedAt=*` 删除所有任务
`afterStartedAt`	删除指定 `startedAt` 日期之后的任务。使用 `afterStartedAt=*` 删除所有任务
`afterFinishedAt`	删除指定 `finishedAt` 日期之后的任务。使用 `afterFinishedAt=*` 删除所有任务

日期过滤器等同于 < 或 > 操作。目前无法使用日期过滤器执行 ≤ 或 ≥ 操作。

要了解更多关于任务过滤的信息，请参阅我们的专用指南。

示例

curl \
  -X DELETE 'MEILISEARCH_URL/tasks?uids=1,2'

响应: `200 Ok`

{
  "taskUid": 3,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskDeletion",
  "enqueuedAt": "2021-08-12T10:00:00.000000Z"
}

由于 taskDeletion 是一个全局任务，它的 indexUid 始终为 null。

您可以使用这个 taskUid 来获取关于任务状态的更多详细信息。

删除所有任务

您可以通过以下过滤器删除所有已完成的任务：

DELETE

/tasks?statuses=failed,canceled,succeeded

使用的 API 密钥必须具有对所有索引("indexes": [*])的访问权限以及 task.delete 操作权限。

API 参考

错误

​任务对象

​uid

​batchUid

​indexUid

​status

​type

​canceledBy

​details

​documentAdditionOrUpdate（文档添加或更新）

​documentDeletion（文档删除）

​indexCreation（索引创建）

​indexUpdate

​indexDeletion

​indexSwap

​settingsUpdate（设置更新）

​dumpCreation（转储创建）

​taskCancelation

​taskDeletion（任务删除）

​snapshotCreation（快照创建）

​error（错误）

​duration（持续时间）

​enqueuedAt

​startedAt

​finishedAt

​任务摘要对象

​获取任务列表

​查询参数

​响应

​示例

​响应: 200 Ok

​获取单个任务

​路径参数

​示例

​响应: 200 Ok

​取消任务

​查询参数

​示例

​响应: 200 Ok

​取消所有任务

​删除任务

​查询参数

​示例

​响应: 200 Ok

​删除所有任务

任务对象

`uid`

`batchUid`

`indexUid`

`status`

`type`

`canceledBy`

`details`

`documentAdditionOrUpdate`（文档添加或更新）

`documentDeletion`（文档删除）

`indexCreation`（索引创建）

`indexUpdate`

`indexDeletion`

`indexSwap`

`settingsUpdate`（设置更新）

`dumpCreation`（转储创建）

`taskCancelation`

`taskDeletion`（任务删除）

`snapshotCreation`（快照创建）

`error`（错误）

`duration`（持续时间）

`enqueuedAt`

`startedAt`

`finishedAt`

任务摘要对象

获取任务列表

查询参数

响应

示例

响应: `200 Ok`

获取单个任务

路径参数

示例

响应: `200 Ok`

取消任务

查询参数

示例

响应: `200 Ok`

取消所有任务

删除任务

查询参数

示例

响应: `200 Ok`

删除所有任务