受管理的資源

受管理的資源公開 REST API 端點，以便對 Solr 物件執行建立-讀取-更新-刪除 (CRUD) 作業。

任何具有組態設定和/或資料的長期 Solr 物件都是受管理資源的良好候選者。受管理資源補充了 Solr 中其他可以透過程式方式管理的元件，例如 RESTful 結構描述 API，以將欄位新增至受管理的結構描述。

考慮一個提供 Solr 即服務的 Web 型 UI，其中使用者需要設定一組停止字詞和同義字對應，作為其搜尋應用程式初始設定流程的一部分。這種類型的使用案例可以透過 Solr 提供的受管理停止篩選器和受管理同義字圖形篩選器工廠，透過受管理資源 REST API 輕鬆支援。

使用者也可以編寫自己的自訂外掛程式，利用相同的內部掛鉤來讓其他資源透過 REST 管理。

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

bin/solr start -e techproducts

受管理資源概述

讓我們開始學習受管理資源，首先看看 Solr 提供的幾個範例，使用 REST API 管理停止字詞和同義字。閱讀本節後，您將準備好深入了解如何在 Solr 中實作受管理資源的詳細資訊，以便您可以開始建立自己的實作。

管理停止字詞

首先，您需要定義一個使用 ManagedStopFilterFactory 的欄位類型，例如

<fieldType name="managed_en" positionIncrementGap="100">
  <analyzer>
    <tokenizer class="solr.StandardTokenizerFactory"/>
    <filter class="solr.ManagedStopFilterFactory" (1)
            managed="english" /> (2)
  </analyzer>
</fieldType>

關於此欄位類型定義，有兩件事需要注意

1 篩選器實作類別是 solr.ManagedStopFilterFactory。這是 StopFilterFactory 的特殊實作，它使用一組透過 REST API 管理的停止字詞。
2 managed="english" 屬性為該組受管理的停止字詞命名，在此例中表示停止字詞用於英文文字。

用於管理 techproducts 集合中英文停止字詞的 REST 端點是：/solr/techproducts/schema/analysis/stopwords/english。

範例資源路徑應該是不言自明的。應該注意的是，ManagedStopFilterFactory 實作決定了路徑的 /schema/analysis/stopwords 部分，這是有道理的，因為這是由結構描述定義的分析元件。

因此，使用下列篩選器的欄位類型

<filter class="solr.ManagedStopFilterFactory"
        managed="french" />

會解析為路徑：/solr/techproducts/schema/analysis/stopwords/french。

所以現在讓我們看看這個 API 的實際運作，從一個簡單的 GET 請求開始

curl "https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/english"

假設您將此請求傳送至 Solr，回應主體是 JSON 文件

{
  "responseHeader":{
    "status":0,
    "QTime":1
  },
  "wordSet":{
    "initArgs":{"ignoreCase":true},
    "initializedOn":"2014-03-28T20:53:53.058Z",
    "managedList":[
      "a",
      "an",
      "and",
      "are",
       ]
  }
}

sample_techproducts_configs configset 隨附一組預先建置的受管理停用詞，但您應僅使用 API 與此檔案互動，而不應直接編輯。

在此回應中，您應該注意到一件事，那就是它包含一個單字 managedList 以及 initArgs。這是此框架中的一個重要概念 — 受管理資源通常具有組態和資料。對於停用詞，唯一的組態參數是一個布林值，它決定在停用詞篩選期間是否忽略符記的大小寫 (ignoreCase=true|false)。資料是一個單字列表，在回應中以名為 managedList 的 JSON 陣列表示。

現在，讓我們使用 HTTP PUT 將一個新單字新增至英文停用詞清單

curl -X PUT -H 'Content-type:application/json' --data-binary '["foo"]' "https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/english"

在這裡，我們使用 curl 將包含單字「foo」的 JSON 清單 PUT 到受管理的英文停用詞集。如果請求成功，Solr 將傳回 200。您也可以在單個 PUT 請求中放入多個單字。

您可以透過將 GET 請求傳送給該單字作為該集合的子資源來測試特定單字是否存在，例如

curl "https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/english/foo"

如果子資源 (foo) 存在，此請求將傳回狀態碼 200；如果受管理清單中不存在，則傳回 404。

若要刪除停用詞，您應執行

curl -X DELETE "https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/english/foo"
PUT/POST 用於將詞彙新增至現有清單，而不是完全取代清單。這是因為將詞彙新增至現有清單比完全取代清單更常見，因此 API 傾向於使用更常見的增量新增詞彙的方法，尤其是也支援刪除個別詞彙。

管理同義詞

在大多數情況下，用於管理同義詞的 API 行為與用於停用詞的 API 類似，只是它不是使用單字列表，而是使用映射，其中映射中每個條目的值都是詞彙的一組同義詞。與停用詞一樣，sample_techproducts_configs configset 包括一組預先建置的同義詞對應，適用於由以下欄位類型定義啟用的範例資料

<fieldType name="managed_en" positionIncrementGap="100">
  <analyzer type="index">
    <tokenizer class="solr.StandardTokenizerFactory"/>
    <filter class="solr.ManagedStopFilterFactory" managed="english" />
    <filter class="solr.ManagedSynonymGraphFilterFactory" managed="english" />
    <filter class="solr.FlattenGraphFilterFactory"/> <!-- required on index analyzers after graph filters -->
  </analyzer>
  <analyzer type="query">
    <tokenizer class="solr.StandardTokenizerFactory"/>
    <filter class="solr.ManagedStopFilterFactory" managed="english" />
    <filter class="solr.ManagedSynonymGraphFilterFactory" managed="english" />
  </analyzer>
</fieldType>

若要取得受管理同義詞的映射，請將 GET 請求傳送至

curl "https://127.0.0.1:8983/solr/techproducts/schema/analysis/synonyms/english"

此請求將傳回類似於以下的響應

{
  "responseHeader":{
    "status":0,
    "QTime":3},
  "synonymMappings":{
    "initArgs":{
      "ignoreCase":true,
      "format":"solr"},
    "initializedOn":"2014-12-16T22:44:05.33Z",
    "managedMap":{
      "GB":
        ["GiB",
         "Gigabyte"],
      "TV":
        ["Television"],
      "happy":
        ["glad",
         "joyful"]}}}

受管理的同義詞在 managedMap 屬性下傳回，其中包含一個 JSON 映射，其中每個條目的值都是詞彙的一組同義詞，例如上例中「happy」具有同義詞「glad」和「joyful」。

若要新增新的同義詞對應，您可以 PUT/POST 單個對應，例如

curl -X PUT -H 'Content-type:application/json' --data-binary '{"mad":["angry","upset"]}' "https://127.0.0.1:8983/solr/techproducts/schema/analysis/synonyms/english"

如果 PUT 請求成功，API 將傳回狀態碼 200。若要確定特定詞彙的同義詞，請為子資源傳送 GET 請求，例如 /schema/analysis/synonyms/english/mad 將傳回 ["angry","upset"]。

您也可以 PUT 對稱同義詞列表，這將展開為列表中每個詞彙的對應。例如，您可以使用 JSON 清單語法而不是映射來 PUT 以下對稱同義詞列表

curl -X PUT -H 'Content-type:application/json' --data-binary '["funny", "entertaining", "whimiscal", "jocular"]' "https://127.0.0.1:8983/solr/techproducts/schema/analysis/synonyms/english"

請注意，展開是在處理 PUT 請求時執行的，因此底層持久狀態仍然是受管理的映射。因此，如果在傳送上一個 PUT 請求之後，您對 /schema/analysis/synonyms/english/jocular 執行 GET，那麼您將收到一個包含 ["funny", "entertaining", "whimiscal"] 的列表。使用列表建立同義詞對應後，必須單獨管理每個詞彙。

最後，您可以透過向受管理端點傳送 DELETE 請求來刪除對應。

套用受管理資源變更

透過此 REST API 對受管理資源所做的變更不會套用至作用中的 Solr 元件，直到重新載入 Solr 集合（或單伺服器模式下的 Solr 核心）為止。

例如：在新增或刪除停用詞之後，您必須重新載入核心/集合，變更才會生效；相關的 API：CoreAdmin API 和 Collections API。

在分散式模式下執行時，必須採用這種方法，以確保變更同時套用至集合中的所有核心，從而使行為一致且可預測。不用說，您不希望其中一個複本使用與其他複本不同的一組停用詞或同義詞。

這種「在重新載入時套用變更」方法的一個細微結果是，一旦您使用 API 進行變更，就無法讀取作用中的資料。換句話說，API 從 API 的角度傳回最新的資料，這可能與 Solr 元件目前正在使用的資料不同。

但是，此 API 實作的目的是在進行變更後短時間內使用重新載入來套用變更，因此 API 傳回的資料與伺服器中作用中的資料不同的時間應可忽略不計。

如果由索引時分析器使用，則變更停用詞和同義詞對應等內容通常需要為現有文件重新建立索引。RestManager 框架不會阻止您這樣做，它只是可以透過程式設計方式建立一組停用詞、同義詞等。有關為文件重新建立索引的更多資訊，請參閱重新建立索引章節。

RestManager 端點

可以使用每個集合的 /schema/managed 端點來取得有關已註冊 ManagedResources 的中繼資料。

假設您在結構描述中定義了上面顯示的 managed_en 欄位類型，則將 GET 請求傳送至以下資源將傳回有關哪些與結構描述相關的資源正由 RestManager 管理的中繼資料

curl "https://127.0.0.1:8983/solr/techproducts/schema/managed"

回應本文是一個 JSON 文件，其中包含 /schema 根目錄下受管理資源的中繼資料

{
  "responseHeader":{
    "status":0,
    "QTime":3
  },
  "managedResources":[
    {
      "resourceId":"/schema/analysis/stopwords/english",
      "class":"org.apache.solr.rest.schema.analysis.ManagedWordSetResource",
      "numObservers":"1"
    },
    {
      "resourceId":"/schema/analysis/synonyms/english",
      "class":"org.apache.solr.rest.schema.analysis.ManagedSynonymGraphFilterFactory$SynonymManager",
      "numObservers":"1"
    }
  ]
}

您也可以使用 PUT/POST 將新的受管理資源建立到適當的 URL — 甚至在設定任何使用這些資源的內容之前。

例如，假設我們想要建立一組德文停用詞。在開始新增停用詞之前，我們需要建立端點

/solr/techproducts/schema/analysis/stopwords/german

若要建立此端點，請將以下 PUT/POST 請求傳送至我們希望建立的端點

curl -X PUT -H 'Content-type:application/json' --data-binary \
'{"class":"org.apache.solr.rest.schema.analysis.ManagedWordSetResource"}' \
"https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/german"

如果請求成功，Solr 將以狀態碼 200 回應。實際上，此動作會在 RestManager 中註冊受管理資源的新端點。從這裡，您可以開始新增德文停用詞，如我們在上面看到的那樣

curl -X PUT -H 'Content-type:application/json' --data-binary '["die"]' \
"https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/german"

對於大多數使用者來說，以這種方式建立資源永遠是不必要的，因為受管理資源會在設定時自動建立。

但是，如果 Solr 元件不再使用受管理資源，您可能需要明確刪除它們。

例如，我們在上面建立的德文受管理資源可以刪除，因為沒有 Solr 元件在使用它，而英文停用詞的受管理資源則無法刪除，因為結構描述中宣告了一個正在使用它的符記篩選器。

curl -X DELETE "https://127.0.0.1:8983/solr/techproducts/schema/analysis/stopwords/german"