v2 API
v2 API 是一种现代化的自文档 API 接口,涵盖了大多数当前的 Solr API。预计一旦 v2 API 达到全面覆盖,并且像 SolrJ 和管理 UI 这样的 Solr 内部 API 用法已从旧 API 转换为 v2 API,旧 API 最终将被淘汰。今天,两种 API 样式共存,所有旧 API 将继续工作而不会发生任何变化。如果需要,您可以通过使用此系统属性启动服务器来禁用所有 v2 API 端点:-Ddisable.v2.api=true
。
v2 API 被归类为“实验性”。随着它发展到涵盖更多功能,它可能会以不向后兼容的方式发生更改。 |
旧 API 和 v2 API 在三个主要方面有所不同
-
命令格式:旧 API 命令和相关参数通过 HTTP GET 请求上的 URL 请求参数提供,而在 v2 API 中,大多数 API 命令通过 POST 到 v2 API 端点的 JSON 正文提供。v2 API 还支持 HTTP 方法 GET 和 DELETE(在适当的情况下)。
-
端点结构:v2 API 端点结构已合理化和规范化。
-
文档:v2 API 是自文档化的:将
/_introspect
附加到任何有效的 v2 API 路径,API 规范将以 JSON 格式返回。
v2 API 路径前缀
以下是一些 v2 API URL 路径和路径前缀,以及在这些路径及其子路径上支持的一些操作。
路径前缀 | 一些支持的操作 |
---|---|
|
创建、别名、备份和恢复集合。 |
|
更新请求。 |
|
配置请求。 |
|
Schema 请求。 |
|
特定于处理程序的请求。 |
|
拆分分片、创建分片、添加副本。 |
|
删除分片、强制主节点选举 |
|
删除副本。 |
|
创建 core。 |
|
重新加载、重命名、删除和卸载 core。 |
|
执行监督者操作、重新加入主节点选举。 |
|
添加角色、删除角色、设置集群属性。 |
|
上传和下载 blob 和元数据。 |
自检
将 /_introspect
附加到任何有效的 v2 API 路径,API 规范将以 JSON 格式返回。
https://127.0.0.1:8983/api/c/_introspect
要限制自检输出仅包含一个特定的 HTTP 方法,请添加请求参数 method
,值为 GET
、POST
或 DELETE
。
https://127.0.0.1:8983/api/c/_introspect?method=POST
大多数端点都支持通过 POST 发送的正文中提供的命令。要将自检输出限制为仅一个命令,请添加请求参数 command=command-name
。
https://127.0.0.1:8983/api/c/gettingstarted/_introspect?method=POST&command=modify
解释自检输出
示例:https://127.0.0.1:8983/api/c/gettingstarted/get/_introspect
{
"spec":[{
"documentation":"https://solr.apache.org/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 的自检示例:https://127.0.0.1:8983/api/c/gettingstarted/_introspect?method=POST&command=modify
{
"spec":[{
"documentation":"https://solr.apache.org/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.apache.org/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 schema 描述命令结构(有关描述,请参见 https://json-schema.fullstack.org.cn/)。
调用示例
对于 "gettingstarted" 集合,设置复制因子以及是否自动添加副本 (请参阅上面的 `“modify”` 命令的 introspect 输出,该命令在此处使用)
$ curl https://127.0.0.1:8983/api/c/gettingstarted -H 'Content-type:application/json' -d '
{ modify: { replicationFactor: "3" } }'
{"responseHeader":{"status":0,"QTime":842}}
查看集群的状态
$ curl https://127.0.0.1:8983/api/cluster
{"responseHeader":{"status":0,"QTime":0},"collections":["gettingstarted",".system"]}
设置集群属性
$ curl https://127.0.0.1:8983/api/cluster -H 'Content-type: application/json' -d '
{ set-property: { name: maxCoresPerNode, val: "100" } }'
{"responseHeader":{"status":0,"QTime":4}}