v2 API
v2 API は、現在のほとんどの Solr API をカバーする、最新の自己文書化 API インターフェースです。v2 API が完全にカバーされ、SolrJ や管理 UI などの Solr 内部 API の使用が古い API から v2 API に変換されたら、古い API は最終的に廃止される予定です。現在、2 つの API スタイルが共存しており、すべての古い API は変更なしで引き続き機能します。必要に応じて、このシステムプロパティを使用してサーバーを起動することで、すべての v2 API エンドポイントを無効にできます: -Ddisable.v2.api=true
。
v2 API は「試験的」として分類されています。追加の機能をカバーするように進化するにつれて、後方互換性のない方法で変更される可能性があります。 |
古い API と v2 API は、主に 3 つの違いがあります。
-
コマンド形式: 古い API コマンドと関連パラメータは、HTTP GET リクエストの URL リクエストパラメータを介して提供されますが、v2 API では、ほとんどの API コマンドは、v2 API エンドポイントに POST された JSON ボディを介して提供されます。v2 API は、必要に応じて HTTP メソッド GET と DELETE もサポートしています。
-
エンドポイント構造: v2 API エンドポイント構造は合理化され、正規化されています。
-
ドキュメント: v2 API は自己文書化されています。任意の有効な v2 API パスに
/_introspect
を追加すると、API 仕様が JSON 形式で返されます。
v2 API パスプレフィックス
以下は、v2 API の URL パスとパスプレフィックス、およびこれらのパスとサブパスでサポートされている操作の一部です。
パスプレフィックス | サポートされている操作 |
---|---|
|
コレクションの作成、エイリアス、バックアップ、復元。 |
|
更新リクエスト。 |
|
構成リクエスト。 |
|
スキーマのリクエスト。 |
|
ハンドラー固有のリクエスト。 |
|
シャードの分割、シャードの作成、レプリカの追加。 |
|
シャードの削除、強制リーダー選出 |
|
レプリカの削除。 |
|
コアの作成。 |
|
コアのリロード、名前変更、削除、アンロード。 |
|
監視役の操作の実行、リーダー選出への再参加。 |
|
役割の追加、役割の削除、クラスタプロパティの設定。 |
|
BLOB とメタデータのアップロードとダウンロード。 |
イントロスペクト
任意の有効な v2 API パスに /_introspect
を追加すると、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 経由で送信されたボディで提供されるコマンドをサポートしています。イントロスペクトの出力を 1 つのコマンドのみに制限するには、リクエストパラメータ command=コマンド名
を追加します。
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.dokyumento.jp/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.dokyumento.jp/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.dokyumento.jp/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"
セクションには、このエンドポイントでサポートされるコマンドごとに1つのエントリがあります。キーはコマンド名で、値はJSONスキーマを使用してコマンド構造を記述するJSONオブジェクトです(説明については、https://json-schema.dokyumento.jp/ を参照してください)。
呼び出し例
"gettingstarted" コレクションの場合、レプリケーション係数と、レプリカを自動的に追加するかどうかを設定します(ここで使用する "modify"
コマンドのイントロスペクト出力については上記を参照してください)。
$ 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}}