建立及註冊結構定義

Google Cloud Search 結構定義是 JSON 結構，用於定義物件、屬性和索引及查詢資料的選項。內容連結器會使用已註冊的結構化定義，建構存放區資料的結構並建立索引。

如要建立結構定義，請向 API 提供 JSON 結構定義物件。您必須先為每個存放區註冊結構定義，才能為資料建立索引。

注意： 非結構化資料不需要結構定義，例如沒有預先決定檔案類型的基本檔案共用系統。您也可以使用 SDK 建立結構定義物件。

本文將介紹建立結構定義的基本概念。如要提升搜尋體驗，請參閱「提升搜尋品質」。

建立結構定義

請按照下列步驟建立 Cloud Search 結構定義：

1. 找出預期使用者行為
2. 初始化資料來源
3. 定義物件
4. 定義物件屬性
5. 註冊結構定義
6. 建立資料索引
7. 測試結構定義
8. 調整結構定義

注意： 本文使用的是假設的電影資料庫結構定義。如需完整範例，請參閱「schema.json」一節。

找出預期的使用者行為

預測使用者搜尋方式有助於定義結構定義策略。如果是電影資料庫，使用者可能會搜尋「勞勃瑞福主演的電影」。你的結構定義必須支援查詢特定演員的電影。

如要讓結構定義與使用者行為保持一致，請按照下列步驟操作：

1. 評估不同使用者的各種查詢。
2. 找出邏輯資料集或「物件」，例如「電影」。
3. 找出屬性，例如名稱或發行日期。
4. 找出屬性的有效值，例如「法櫃奇兵」。
5. 判斷排序和排名需求，例如依時間順序或觀眾評分排序。
6. 找出職位等內容屬性，改善自動完成建議。
7. 列出這些物件、屬性和範例值。使用這份清單定義運算子選項。

初始化資料來源

資料來源代表儲存在 Google Cloud 中的已建立索引的存放區資料。請參閱「管理第三方資料來源」。使用者點選結果時，Cloud Search 會使用索引要求中的網址，將使用者導向該項目。

定義物件

物件是結構定義的基本單位。「電影」或「人物」等邏輯結構都是物件。每個物件都有 屬性，例如名稱、時長或名稱。

圖 1. 含有兩個物件和一個子物件的範例結構定義。

結構定義是 objectDefinitions 標記中的物件定義清單。

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

為每個物件使用專屬名稱，例如 movie。架構服務會將這些名稱做為鍵。請參閱「ObjectDefinition」。

注意： 要求已註冊的結構定義時，可以忽略傳回的 operationIds，因為這些是指待處理的作業。

定義物件屬性

在 propertyDefinitions 區段中定義屬性，例如標題和發行日期。使用 options 處理 freshnessOptions (排名) 和 displayOptions (UI 標籤)。

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

注意： 物件中的屬性名稱不得重複，大小寫不限。

PropertyDefinition 包含：

• name 字串。
• 與類型無關的選項 (例如 isReturnable)。
• 類型和類型專屬選項 (例如textPropertyOptions)。
• operatorOptions 搜尋運算子。
• UI 標籤的 displayOptions。

您可以在不同物件中重複使用屬性名稱。舉例來說，movieTitle 可能會出現在 movie 物件和 person 物件的影視作品中。

注意： Cloud Search 會在建立索引時捨棄未註冊的欄位，並拒絕含有錯誤資料類型的要求。

新增與類型無關的選項

PropertyDefinition 包含布林值選項，可為屬性設定搜尋功能，不論屬性類型為何。這些選項預設為 false，必須設為 true 才能使用。

• isReturnable：如果應使用 Query API 在搜尋結果中傳回資源資料，請設為 true。不可傳回的屬性可用於搜尋或排名，但不會顯示在結果中。
• isRepeatable：如果屬性可以有多個值，請設為 true。舉例來說，電影只有一個上映日期，但有多位演員。
• isSortable：如果屬性可用於排序，請設為 true。如果 isRepeatable 為 true，或屬性位於可重複的子物件中，則不得為 true。
• isFacetable：如果屬性可用於產生分面 (用於縮小搜尋結果範圍的屬性)，請設為 true。
  • 必須將 isReturnable 設為 true。
  • 僅支援列舉、布林值和文字屬性。
• isWildcardSearchable：設為 true，允許使用者對這項屬性執行萬用字元搜尋。這個選項僅適用於文字屬性，且行為取決於 exactMatchWithOperator 設定：
  • 如果 exactMatchWithOperator 為 true：系統會將文字值視為單一權杖。例如，science-* 查詢會與 science-fiction 值相符。
  • 如果 exactMatchWithOperator 為 false：系統會將文字值權杖化。sci* 或 fi* 等查詢會與 science-fiction 相符，但 science-* 不會。

定義類型

定義適當的屬性選項物件 (例如textPropertyOptions)。如果您知道所有可能的值，請使用列舉 (enumPropertyOptions)。資源只能有一種資料類型。

定義運算子選項

operatorOptions說明屬性如何做為搜尋運算子。

警告： 除非確定屬性需要較高的等級，否則請將 retrievalImportance 設為 DEFAULT。設定後即無法變更。

每個 operatorOptions 都需要 operatorName (例如 title)。這是使用者在查詢中輸入的參數 (例如 title:titanic)。使用淺顯易懂的名稱，並向使用者公開這些名稱。

您可以跨相同類型的資源共用 operatorName。使用該名稱的查詢會從所有相符的屬性擷取結果。

可排序的屬性可以包括 lessThanOperatorName 和 greaterThanOperatorName，用於比較查詢。文字屬性可以使用 exactMatchWithOperator 將整個值視為單一權杖。

新增顯示選項

選用的 displayOptions 區段包含 displayLabel。這是顯示在搜尋結果中的易讀標籤。

新增建議篩選運算子

使用 suggestionFilteringOperators[] 定義篩選自動完成建議的屬性 (例如，依使用者偏好的類型篩選電影建議)。你只能定義一個建議篩選器。

註冊結構定義

使用資料來源 ID 向結構定義服務註冊結構定義。發出 UpdateSchema 要求：

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

使用 validateOnly: true 測試結構定義，不必註冊。

建立資料索引

註冊後，請使用 Index 呼叫填入資料來源，通常會使用連接器。

建立索引要求範例：

{
  "name": "datasource/<data_source_id>/items/titanic",
  "metadata": {
    "title": "Titanic",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [{
        "name": "movieTitle",
        "textValues": { "values": ["Titanic"] }
      }]
    }
  },
  "itemType": "CONTENT_ITEM"
}

注意： objectType 必須與結構化資料物件名稱相符。要求中的屬性名稱必須與結構定義的大小寫相符。

測試結構定義

在實際運作前，先使用小型存放區進行測試。建立 ACL，將結果限制為測試使用者。

• 一般查詢：搜尋字串 (例如 「鐵達尼號」)，即可查看所有相符項目。
• 運算子查詢：使用運算子 (例如 actor:Zane) 來限制結果。

調整結構定義

監控使用者意見回饋並調整架構。您可以為新欄位建立索引，或重新命名運算子，讓使用者更容易理解。

在結構定義變更後重新建立索引

變更下列項目時，不需要重新建立索引：

• 運算子名稱。
• 數值限制。
• 排序排名。
• 新鮮度或顯示選項。

您必須為下列項目重新建立索引：

• 新增或移除屬性或物件。
• 將 isReturnable、isFacetable 或 isSortable 變更為 true。
• 標記房源 isSuggestable。

不允許的屬性變更

不允許會破壞索引或導致結果不一致的變更，包括：

• 屬性資料類型或名稱。
• exactMatchWithOperator或retrievalImportance設定。

進行複雜的結構定義變更

如要進行不允許的變更，請將屬性從舊定義遷移至新定義：

1. 在結構定義中新增名稱不同的屬性。
2. 使用新舊屬性註冊結構定義。
3. 只使用新屬性回填索引。
4. 從結構定義中刪除舊屬性。
5. 更新查詢程式碼，改用新的屬性名稱。

Cloud Search 會將已刪除的項目保留 30 天，避免重複使用問題。

大小限制

• 最多 10 個頂層物件。
• 最多 10 個層級。
• 每個物件最多 1000 個欄位 (包括巢狀欄位)。

後續步驟

1. 建立搜尋介面。
2. 提升搜尋品質。
3. 建構結構定義，以利最佳解讀查詢。
4. 定義同義詞。