v2 API

v2 API 是一种现代化的自文档 API 接口,涵盖大多数当前的 Solr API。预计 v2 API 一旦达到全面覆盖,并且 Solr 内部 API 使用(如 SolrJ 和管理 UI)已从旧 API 转换为 v2 API,旧 API 最终将被废弃。如今,两种 API 样式共存,并且所有旧 API 都将继续工作,无需任何更改。如果需要,可以通过使用此系统属性启动服务器来禁用所有 v2 API 端点:-Ddisable.v2.api=true

v2 API 被归类为“实验性”。它可能会以向后不兼容的方式进行更改,因为它会演变以涵盖其他功能。

旧 API 和 v2 API 在三个原则方面有所不同

  1. 命令格式:旧 API 命令和关联参数通过 HTTP GET 请求上的 URL 请求参数提供,而在 v2 API 中,大多数 API 命令通过 POST 到 v2 API 端点的 JSON 正文提供。v2 API 还支持 HTTP 方法 GET 和 DELETE(如果适用)。

  2. 端点结构:v2 API 端点结构已经合理化和规范化。

  3. 文档:v2 API 是自文档的:将 /_introspect 追加到任何有效的 v2 API 路径,API 规范将以 JSON 格式返回。

v2 API 路径前缀

以下是某些 v2 API URL 路径和路径前缀,以及在这些路径及其子路径上支持的一些操作。

路径前缀 一些受支持的操作

/api/collections

创建、别名、备份和还原集合。

/api/c/collection-name/update

更新请求。

/api/c/collection-name/config

配置请求。

/api/c/collection-name/schema

模式请求。

/api/c/集合名称/处理程序名称

特定于处理程序的请求。

/api/c/集合名称/shards

拆分分片、创建分片、添加副本。

/api/c/集合名称/shards/分片名称

删除分片、强制领导者选举

/api/c/集合名称/shards/分片名称/副本名称

删除副本。

/api/cores

创建内核。

/api/cores/内核名称

重新加载、重命名、删除和卸载内核。

/api/node

执行监督程序操作、重新加入领导者选举。

/api/cluster

添加角色、删除角色、设置集群属性。

/api/c/.system/blob

上传和下载 Blob 及元数据。

内省

/_introspect 附加到任何有效的 v2 API 路径,API 规范将以 JSON 格式返回。

http://localhost:8983/api/c/_introspect

要将内省输出限制为仅包含一种特定 HTTP 方法,请添加请求参数 method,其值为 GETPOSTDELETE

http://localhost:8983/api/c/_introspect?method=POST

大多数端点都支持通过 POST 发送的正文中提供的命令。要将内省输出限制为仅一个命令,请添加请求参数 command=command-name

http://localhost:8983/api/c/gettingstarted/_introspect?method=POST&command=modify

解释内省输出

示例:http://localhost:8983/api/c/gettingstarted/get/_introspect

{
  "spec":[{
      "documentation":"https://solr.net.cn/guide/solr/latest/configuration-guide/realtime-get.html",
      "description":"RealTime Get allows retrieving documents by ID before the documents have been committed to the index. It is useful when you need access to documents as soon as they are indexed but your commit times are high for other reasons.",
      "methods":["GET"],
      "url":{
        "paths":["/c/gettingstarted/get"],
        "params":{
          "id":{
            "type":"string",
            "description":"A single document ID to retrieve."},
          "ids":{
            "type":"string",
            "description":"One or more document IDs to retrieve. Separate by commas if more than one ID is specified."},
          "fq":{
            "type":"string",
            "description":"An optional filter query to add to the query. One use case for this is security filtering, in case users or groups should not be able to retrieve the document ID requested."}}}}],
  "WARNING":"This response format is experimental.  It is likely to change in the future.",
  "availableSubPaths":{}
}

上述示例中一些键的说明

  • documentation:此 API 的联机 Solr 参考指南部分的 URL

  • description:功能/变量/命令等的文本说明。

  • spec/methods:此 API 支持的 HTTP 方法

  • spec/url/paths:此 API 支持的 URL 路径

  • spec/url/params:支持的 URL 请求参数列表

  • availableSubPaths:有效的 URL 子路径列表以及每个子路径支持的 HTTP 方法

POST API 的内省示例:http://localhost:8983/api/c/gettingstarted/_introspect?method=POST&command=modify

{
  "spec":[{
      "documentation":"https://solr.net.cn/guide/solr/latest/configuration-guide/collections-api.html",
      "description":"Several collection-level operations are supported with this endpoint: modify collection attributes; reload a collection; migrate documents to a different collection; rebalance collection leaders; balance properties across shards; and add or delete a replica property.",
      "methods":["POST"],
      "url":{"paths":["/collections/{collection}",
          "/c/{collection}"]},
      "commands":{"modify":{
          "documentation":"https://solr.net.cn/guide/solr/latest/deployment-guide/collection-management.html#modifycollection",
          "description":"Modifies specific attributes of a collection. Multiple attributes can be changed at one time.",
          "type":"object",
          "properties":{
            "replicationFactor":{
              "type":"string",
              "description":"The number of replicas to be created for each shard. Replicas are physical copies of each shard, acting as failover for the shard. Note that changing this value on an existing collection does not automatically add more replicas to the collection. However, it will allow add-replica commands to succeed."}}}}}],
  "WARNING":"This response format is experimental.  It is likely to change in the future.",
  "availableSubPaths":{
    "/c/gettingstarted/select":["POST", "GET"],
    "/c/gettingstarted/config":["POST", "GET"],
    "/c/gettingstarted/schema":["POST", "GET"],
    "/c/gettingstarted/export":["POST", "GET"],
    "/c/gettingstarted/admin/ping":["POST", "GET"],
    "/c/gettingstarted/update":["POST"]}
}

上述示例中的 "commands" 部分针对此端点支持的每个命令有一个条目。键是命令名称,值是使用 JSON 模式描述命令结构的 JSON 对象(有关说明,请参见 http://json-schema.org/)。

调用示例

对于“gettingstarted”集合,设置复制因子以及是否自动添加副本(有关此处使用的 "modify" 命令的内省输出,请参见上文)

$ curl http://localhost:8983/api/c/gettingstarted -H 'Content-type:application/json' -d '
{ modify: { replicationFactor: "3" } }'

{"responseHeader":{"status":0,"QTime":842}}

查看集群状态

$ curl http://localhost:8983/api/cluster

{"responseHeader":{"status":0,"QTime":0},"collections":["gettingstarted",".system"]}

设置集群属性

$ curl http://localhost:8983/api/cluster -H 'Content-type: application/json' -d '
{ set-property: { name: maxCoresPerNode, val: "100" } }'

{"responseHeader":{"status":0,"QTime":4}}