CoreAdmin API

Core Admin API 主要在執行 SolrCloud 叢集時，由 Collections API 在底層使用。

SolrCloud 使用者通常不應直接使用 CoreAdmin API，但對於使用者管理叢集或單節點安裝進行核心維護操作的使用者而言，此 API 可能很有用。

CoreAdmin API 由 CoreAdminHandler 實作，這是一個用於管理 Solr 核心的特殊用途請求處理器。與其他請求處理器不同，CoreAdminHandler 並未附加到單一核心。相反地，每個 Solr 節點中都有一個 CoreAdminHandler 的實例，用於管理該節點中執行的所有核心，並且可透過 /solr/admin/cores 路徑存取。

CoreAdmin 動作可透過 HTTP 請求執行，該請求指定 action 請求參數，其他特定動作引數則以其他參數形式提供。

所有動作名稱皆為大寫，並在以下章節中深入定義。

本節中的所有範例皆假設您正在執行「techproducts」Solr 範例

bin/solr start -DconfigSetBaseDir=./server/solr/configsets -e techproducts

我們正在傳遞 configSetBaseDir 的明確相對路徑，以便能夠使用以下範例中的 sample_techproducts_configs 設定集建立新的核心。

STATUS

STATUS 動作會傳回所有正在執行的 Solr 核心的狀態，或僅傳回具名核心的狀態。

V1 API
V2 API

https://127.0.0.1:8983/solr/admin/cores?action=STATUS&core=techproducts

curl -X GET https://127.0.0.1:8983/api/cores/

取得單一核心的狀態

curl -X GET https://127.0.0.1:8983/api/cores/techproducts

略過傳回索引的相關資訊

curl -X GET https://127.0.0.1:8983/api/cores?indexInfo=false

STATUS 參數

core

選用

預設：無

核心的名稱，如 solr.xml 中 <core> 元素的「name」屬性中所列。如果省略此參數，則會傳回所有正在執行的核心的狀態。

indexInfo

選用

預設：true

如果為 false，則不會在核心 STATUS 請求中傳回索引的相關資訊。在具有大量核心 (即數百個以上) 的 Solr 實作中，擷取每個核心的索引資訊可能會花費大量時間，而且並非總是必要。

CREATE

CREATE 動作會建立新的核心並註冊。

如果已存在具有指定名稱的 Solr 核心，它將在新的核心初始化時繼續處理請求。當新的核心準備就緒時，它將接收新的請求，而舊的核心將被卸載。

admin/cores?action=CREATE&name=核心名稱&instanceDir=路徑/至/目錄&config=solrconfig.xml&dataDir=data

V1 API
V2 API

假設您正在使用現有的設定集來建立新的核心

https://127.0.0.1:8983/solr/admin/cores?action=CREATE&&name=techproducts_v2&configSet=sample_techproducts_configs

如果您已在磁碟上部署現有的核心檔案，而且只需要從這些檔案建立 Solr 核心，則 URL 看起來會像這樣

https://127.0.0.1:8983/solr/admin/cores?action=CREATE&name=_core-name_&instanceDir=_path/to/dir_&config=solrconfig.xml&dataDir=data

curl -X POST https://127.0.0.1:8983/api/cores -H 'Content-Type: application/json' -d '
  {
    "create": {
      "name": "techproducts_v2",
      "configSet": "sample_techproducts_configs"
    }
  }
'

請注意，此命令是 Core Admin API 命令中唯一不支援 core 參數的命令。相反地，必須使用 name 參數，如下所示。

請注意，CREATE 必須能夠找到設定，否則將不會成功。

當您執行 SolrCloud 並為集合建立新核心時，設定將從集合繼承。每個集合都會連結到儲存在 ZooKeeper 中的 configName。這符合設定要求。也就是說，如果您正在執行 SolrCloud，則完全不應使用 CoreAdmin API。相反地，請使用 Collections API。

若您使用使用者管理的叢集，且已定義設定檔集 (Configsets)，則可以使用如下所述的 configSet 參數。如果沒有設定檔集，那麼在 CREATE 呼叫中指定的 instanceDir 必須已存在，且必須包含一個 conf 目錄，該目錄又必須包含 solrconfig.xml、您的 schema (通常命名為 managed-schema.xml 或 schema.xml) 以及這些設定檔所引用的任何檔案。

設定和 schema 檔案名稱可以使用 config 和 schema 參數指定，但這些是專家選項。您可以透過使用指向絕對路徑的 config 和 schema 參數來避免建立 conf 目錄，但除非您完全了解自己在做什麼，否則這可能會導致混亂的設定。

CREATE 和 core.properties 檔案

core.properties 檔案是作為 CREATE 命令的一部分建立的。如果您自己在核心目錄中建立一個 core.properties 檔案，然後嘗試使用 CREATE 將該核心新增到 Solr，您會收到一個錯誤訊息，告知您那裡已經定義了另一個核心。在呼叫具有 CREATE 命令的 CoreAdmin API 之前，core.properties 檔案不得存在。

CREATE 核心參數

name

必要

預設：無

新核心的名稱。與 <core> 元素上的 name 相同。

instanceDir

選用	預設值：請參閱說明

應該儲存此核心檔案的目錄。與 <core> 元素上的 instanceDir 相同。預設值是如果未提供，則為 name 參數指定的值。此目錄必須在 SOLR_HOME、SOLR_DATA_HOME 或系統屬性 solr.allowPaths 指定的路徑之一內。

config

選用	預設值：`solrconfig.xml`

相對於 instanceDir 的設定檔名稱 (即 solrconfig.xml)。

schema

選用	預設值：請參閱說明

要用於核心的 schema 檔案名稱。請注意，如果您正在使用「受管理 schema」(預設行為)，則任何與實際 managedSchemaResourceName 不符的此屬性值都會被讀取一次、備份，並轉換為受管理 schema 使用。詳細資訊請參閱Schema Factory 設定。

dataDir

選用	預設值：`data`

相對於 instanceDir 的資料目錄名稱。如果使用絕對值，則必須在 SOLR_HOME、SOLR_DATA_HOME 或系統屬性 solr.allowPaths 指定的路徑之一內。

configSet

選用

預設：無

要用於此核心的設定檔集名稱。有關更多資訊，請參閱設定檔集章節。

collection

選用	預設值：請參閱說明

此核心所屬的集合名稱。預設值為核心的名稱。如果正在建立新集合，則 collection.param=value 會導致設定 param=value 的屬性。使用 collection.configName=config-name 來指向新集合的設定。

雖然可以為不存在的集合建立核心，但不支援且不建議使用此方法。在直接為集合建立核心之前，請務必先使用Collections API建立集合。

shard

選用

預設：無

此核心代表的分片 ID。這應該僅在特殊情況下才需要；通常您會希望自動分配分片 ID。

property.name=value

選用

預設：無

將核心屬性 name 設定為 value。請參閱定義core.properties 檔案內容的章節。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

使用 collection.configName=configname 來指向新集合的設定。

CREATE 範例

https://127.0.0.1:8983/solr/admin/cores?action=CREATE&name=my_core&collection=my_collection&shard=shard2

RELOAD

RELOAD 動作會從現有、已註冊的 Solr 核心的設定載入一個新的核心。當新核心正在初始化時，現有的核心將繼續處理請求。當新的 Solr 核心準備就緒時，它會接管並卸載舊核心。

V1 API
V2 API

https://127.0.0.1:8983/solr/admin/cores?action=RELOAD&core=techproducts

curl -X POST https://127.0.0.1:8983/api/cores/techproducts/reload

當您在磁碟上對 Solr 核心的設定進行變更時，例如新增新的欄位定義時，這非常有用。呼叫 RELOAD 動作可讓您套用新的設定，而無需重新啟動 Solr。

RELOAD 會執行 SolrCore 的「即時」重新載入，並重複使用一些現有物件。某些設定選項，例如 dataDir 位置和 solrconfig.xml 中的 IndexWriter 相關設定，無法透過簡單的 RELOAD 動作變更並啟用。

RELOAD 核心參數

core

選用

預設：無

核心的名稱，如 solr.xml 中 <core> 元素的 "name" 屬性中所列。此參數在 v1 中是必要參數，並且是 v2 API 中 URL 的一部分。

RENAME

RENAME 動作會變更 Solr 核心的名稱。

V1 API
V2 API

curl -X GET "https://127.0.0.1:8983/solr/admin/cores?action=RENAME&core=currentCoreName&other=newCoreName"

curl -X POST https://127.0.0.1:8983/api/cores/currentCoreName/rename -H 'Content-Type: application/json' -d '
  {
    "to": "newCoreName"
  }
'

RENAME 參數

core

必要

預設：無

要重新命名的現有 Solr 核心的名稱。如果發出 v1 請求，則指定為查詢參數，如果使用 v2 API，則指定為路徑參數。

other (v1)，to (v2)

必要

預設：無

Solr 核心的新名稱。如果發出 v1 請求，則指定為查詢參數，如果使用 v2 API，則指定為請求正文中的屬性。如果 <solr> 的 persistent 屬性為 true，則新名稱將以 <core> 屬性的 name 屬性寫入 solr.xml。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

SWAP

SWAP 會以原子方式交換用於存取兩個現有 Solr 核心的名稱。這可以用於將新內容交換到生產環境中。之前的核心仍然可用，並且可以在必要時交換回去。交換後，每個核心將以另一個核心的名稱為人所知。

V1 API
V2 API

`admin/cores?action=SWAP&core=_core-name_&other=_other-core-name_`

curl -X POST https://127.0.0.1:8983/api/cores/_core-name_/swap -H 'Content-Type: application/json' -d '
  {
    "with": "_other-core-name_"
  }
'

請勿在 SolrCloud 節點上使用 SWAP。它不受支援，可能會導致核心無法使用。

SWAP 參數

core

必要

預設：無

要交換的核心之一的名稱。

other

必要

預設：無

要交換的另一個核心的名稱。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

UNLOAD

UNLOAD 動作會從 Solr 中移除核心。現有的活動請求將繼續處理，但不會將新的請求傳送至指定的核心。如果核心以多個名稱註冊，則只會移除給定的名稱。

V1 API
V2 API

https://127.0.0.1:8983/solr/admin/cores?actionUNLOAD&core=techproducts

curl -X POST https://127.0.0.1:8983/api/cores/techproducts/unload -H 'Content-Type: application/json' -d '
  {}
'

UNLOAD 動作需要一個參數 (core)，以識別要移除的核心。如果 <solr> 的 persistent 屬性設定為 true，則具有此 name 屬性的 <core> 元素將會從 solr.xml 中移除。

卸載 SolrCloud 集合中的所有核心會導致從 ZooKeeper 中移除該集合的中繼資料。

UNLOAD 參數

core

必要

預設：無

要移除的核心的名稱。此參數為必要參數。

deleteIndex

選用	預設值：`false`

如果為 true，則在卸載核心時將移除索引。

deleteDataDir

選用	預設值：`false`

如果為 true，則移除 data 目錄及其所有子目錄。

deleteInstanceDir

選用	預設值：`false`

如果為 true，則移除與核心相關的所有內容，包括索引目錄、設定檔和其他相關檔案。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

MERGEINDEXES

MERGEINDEXES 動作會將一個或多個索引合併到另一個索引。索引必須已完成提交，且應鎖定寫入，直到合併完成，否則產生的合併索引可能會損壞。目標核心索引必須已經存在，並且具有與將合併到其中的一個或多個索引相容的 schema。在合併完成後，也應該對目標核心執行另一次提交。

V1 API
V2 API

curl -X GET "https://127.0.0.1:8983/solr/admin/cores?action=MERGEINDEXES&core=targetCoreName&indexDir=path/to/core1/data/index&indexDir=path/to/core2/data/index"

curl -X POST https://127.0.0.1:8983/api/cores/targetCoreName/merge-indices -H 'Content-Type: application/json' -d '
{
  "indexDirs": ["path/to/core1/data/index","path/to/core2/data/index"]
}
'

在此範例中，我們使用 indexDir 參數 (v2 API 中的 indexDirs) 來定義來源核心的索引位置。core 參數定義目標索引。這種方法的好處是我們可以合併任何可能未與 Solr 核心相關聯的 Lucene 索引。

或者，我們可以改用 srcCore 參數 (v2 API 中的 srcCores)，如下例所示

V1 API
V2 API

curl -X GET "https://127.0.0.1:8983/solr/admin/cores?action=mergeindexes&core=targetCoreName&srcCore=core1&srcCore=core2"

curl -X POST https://127.0.0.1:8983/api/cores/targetCoreName/merge-indices -H 'Content-Type: application/json' -d '
{
  "srcCores": ["core1","core2"]
}
'

這種方法允許我們定義可能沒有與目標核心在同一實體伺服器上的索引路徑的核心。但是，我們只能使用 Solr 核心作為來源索引。這種方法的另一個好處是，如果在寫入與來源索引並行發生時，我們不會有很高的損壞風險。

我們可以透過指定 async 參數並傳遞請求 ID 來使此呼叫非同步執行。然後，可以使用此 ID，透過 REQUESTSTATUS API 檢查已提交任務的狀態。

MERGEINDEXES 參數

core

必要

預設：無

目標核心/索引的名稱。

indexDir

選用

預設：無

多值，將要合併的目錄。

srcCore

選用

預設：無

多值，將要合併的來源核心。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

SPLIT

SPLIT 動作會將索引分割成兩個或多個索引。被分割的索引可以繼續處理請求。分割的部分可以放置在伺服器檔案系統上的指定目錄中，或者可以合併到正在執行的 Solr 核心中。

SPLIT 動作支援五個參數，如下表所述。

SPLIT 參數

core

必要

預設：無

要分割的核心的名稱。

path

選用

預設：無

多值，將在其中寫入索引片段的目錄路徑。必須指定此參數或 targetCore。如果指定此參數，則不得使用 targetCore 參數。

targetCore

選用

預設：無

多值，將在其中合併索引片段的目標 Solr 核心。必須指定此參數或 path。如果指定此參數，則不得使用 path 參數。

ranges

選用

預設：無

以十六進位格式表示的雜湊範圍的逗號分隔清單。如果使用此參數，則不應使用 split.key。請參閱下方的SPLIT 範例，了解如何使用此參數的範例。

split.key

選用

預設：無

用於分割索引的鍵。如果使用此參數，則不應使用 ranges。請參閱下方的SPLIT 範例，了解如何使用此參數的範例。

async

選用

預設：無

用於追蹤此動作的請求 ID，該動作將非同步處理。

SPLIT 範例

core 索引將分割成與 path 或 targetCore 參數數量一樣多的片段。

與兩個 targetCore 參數一起使用:

https://127.0.0.1:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2

在此範例中，core 索引將分割成兩個片段，並合併到兩個 targetCore 索引中。

使用兩個路徑參數:

https://127.0.0.1:8983/solr/admin/cores?action=SPLIT&core=core0&path=/path/to/index/1&path=/path/to/index/2

core 索引將被分割成兩部分，並寫入指定的兩個目錄路徑。

使用 split.key 參數:

https://127.0.0.1:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&split.key=A!

這裡所有具有與 split.key 相同的路由鍵，即 A! 的文件，將會從 core 索引中分割出來，並寫入 targetCore。

使用 ranges 參數:

https://127.0.0.1:8983/solr/admin/cores?action=SPLIT&core=core0&targetCore=core1&targetCore=core2&targetCore=core3&ranges=0-1f4,1f5-3e8,3e9-5dc

這個範例使用 ranges 參數，並以十六進制指定了雜湊範圍 0-500、501-1000 和 1001-1500。這裡索引將被分割成三部分，每個 targetCore 將接收符合指定雜湊範圍的文件，例如 core1 將獲得雜湊範圍為 0-500 的文件，core2 將接收雜湊範圍為 501-1000 的文件，最後 core3 將接收雜湊範圍為 1001-1500 的文件。至少必須指定一個雜湊範圍。請注意，使用與路由鍵的雜湊範圍相同的單一雜湊範圍，並不等同於使用 split.key 參數，因為多個路由鍵可能雜湊到相同的範圍。

targetCore 必須已存在，且必須與 core 索引具有相容的 schema。在分割之前，會自動在 core 索引上呼叫 commit 操作。

此命令在 SolrCloud 的 SPLITSHARD 命令中作為一部分使用，但它也可以用於使用者管理的叢集中的核心。當針對使用者管理叢集中的核心使用，且未指定 split.key 參數時，此動作會分割來源索引並交替分配其文件，以使每個分割部分都包含相同數量的文件。如果指定了 split.key 參數，則只會從來源索引分割出具有相同路由鍵的文件。

REQUESTSTATUS

請求已提交的非同步 CoreAdmin API 呼叫的狀態。

V1 API
V2 API

https://127.0.0.1:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=id

curl -X GET https://127.0.0.1:8983/api/node/commands/id

Core REQUESTSTATUS 參數

REQUESTSTATUS 命令只有一個參數。

requestid

必要

預設：無

非同步請求的使用者定義請求 ID。

以下呼叫將返回已提交的非同步 CoreAdmin 呼叫的狀態。

https://127.0.0.1:8983/solr/admin/cores?action=REQUESTSTATUS&requestid=1

REQUESTRECOVERY

REQUESTRECOVERY 動作會手動要求核心透過與領導者同步來復原。這應該被視為「專家」級命令，並且應該在節點（SolrCloud 複本）無法自動啟動的情況下使用。

admin/cores?action=REQUESTRECOVERY&core=核心名稱

REQUESTRECOVERY 參數

core

必要

預設：無

要重新同步的核心名稱。

REQUESTRECOVERY 範例

https://127.0.0.1:8981/solr/admin/cores?action=REQUESTRECOVERY&core=gettingstarted_shard1_replica1

可以透過管理 UI 展開適當的 ZooKeeper 節點來找到要指定的核心。