建立及註冊結構定義

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Google Cloud Search 結構定義是 JSON 結構,可定義用於建立索引和查詢資料的物件、屬性和選項。 內容連接器會從存放區讀取資料,並根據已註冊的結構定義建立資料結構和建立索引。

向 API 提供 JSON 結構定義物件並註冊,即可建立結構定義。您必須為各個存放區註冊一個結構定義物件,才能為資料建立索引。

本文件涵蓋建立結構定義的基本概念。如要瞭解如何調整結構定義來改善搜尋體驗,請參閱改善搜尋品質

建立架構

下列是建立 Cloud Search 結構定義的步驟:

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

識別使用者可能的行為

預測使用者進行的查詢類型,有助於擬定結構定義的策略。

舉例來說,對電影資料庫發出查詢時,您可能會預期使用者會輸入「我要看所有由羅伯特紅福德主演的電影」這類查詢。 因此,您的結構定義必須支援以「所有有特定演員的電影」為查詢結果。

如要定義結構定義以反映使用者的行為模式,請考慮執行以下工作:

  1. 評估不同使用者期望的各式查詢。
  2. 找出可用於查詢的物件。物件是相關資料的邏輯組合,例如電影資料庫中的電影。
  3. 找出撰寫該物件的屬性,以及可用於查詢中的屬性值。 「屬性」是物件的可建立索引屬性,可包含原始值或其他物件。舉例來說,電影物件可能會以電影名目和發布日期等屬性做為原始值,電影物件也可以包含其他具有其屬性的物件,例如名稱或角色。
  4. 識別屬性的有效值範例。「值」是為資源建立索引的實際資料。舉例來說,資料庫中有一部電影可能會是「失落症的襲擊者」。
  5. 決定使用者需要的排序和排序選項。例如,查詢電影時,使用者可能會按時間順序排序,並依目標對象評分排序,因此不需要依字母順序排列。
  6. (選用) 請考慮您的其中一項屬性代表了可能執行搜尋的具體結構定義 (例如使用者' 職務或部門),以便根據背景資訊提供自動完成建議。舉例來說,如果是搜尋電影資料庫的使用者,可能只會對特定類型的電影感興趣。使用者可以定義要搜尋的內容類型,可能在使用者設定檔中提供。這樣一來,當使用者開始輸入電影查詢時,系統只會建議使用者偏好的類型 (例如「動作電影」) 中的電影。
  7. 列出可用於搜尋的物件、屬性和範例值。(如要進一步瞭解這個清單的使用方式,請參閱「定義運算子選項」一節)。

初始化資料來源

「資料來源」代表來自 Google Cloud 且已建立索引並儲存在 Google Cloud 存放區中的資料。如需初始化資料來源的操作說明,請參閱「管理第三方資料來源」一文。

使用者的資料來源傳回搜尋結果。當使用者點選搜尋結果時,Cloud Search 會使用建立索引要求中提供的網址,將使用者導向實際項目。

定義物件

結構定義的基本資料單位為「物件」,也稱為「結構定義物件」,也就是邏輯的資料結構。在電影資料庫中,一個邏輯資料結構為「電影」。另一個物體可能就是「人物」,代表電影中的演員和工作人員。

結構定義中的每個物件都有一系列用於說明物件的屬性或屬性,例如電影的名稱和持續時間,或個人的名稱和出生日期。物件的屬性可包含原始值或其他物件。

圖 1 顯示電影和人物物件及相關屬性。

實體之間的結構定義連線圖
圖 1. 顯示兩個物件和子物件的範例結構定義。

Cloud Search 結構定義基本上是 objectDefinitions 標記中定義的物件定義陳述式清單。以下結構定義程式碼片段顯示電影和人物結構定義物件的 objectDefinitions 陳述式。

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

定義結構定義物件時,您為物件在結構定義中與其他物件的所有物件必須提供的 name。您通常會使用說明物件的 name 值,例如電影物件的 movie。結構定義服務會使用 name 欄位做為可建立索引物件的鍵 ID。如要進一步瞭解 name 欄位,請參閱「物件定義」一文。

定義物件屬性

ObjectDefinition 的參照所示,物件名稱後面接著一組 optionspropertyDefinitions 清單。options 可以進一步包含 freshnessOptionsdisplayOptions。並根據項目更新程度調整 freshnessOptions 排名。displayOptions 是用於定義物件搜尋結果中是否要顯示特定標籤和屬性。

propertyDefinitions 區段可讓您定義物件的屬性,例如電影名稱和推出日期。

下列程式碼片段顯示包含兩個屬性的 movie 物件:movieTitlereleaseDate

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isWildcardSearchable": 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"
            }
          },
          "displayOptions": {
            "displayLabel": "Release date"
          }
      ...
      ]
    }
  ]
}

PropertyDefinition 由下列項目組成:

  • name 字串。
  • 型別選項選項清單,例如前一個程式碼片段中的 isReturnable
  • 類型及其相關聯的類型專屬選項,例如前一個程式碼片段中的 textPropertyOptionsretrievalImportance
  • 說明如何將屬性做為搜尋運算子的 operatorOptions
  • 一或多個 displayOptions,例如前一個程式碼片段中的 displayLabel

屬性中的 name 不得重複,但可用於其他物件和子物件中可以使用相同的名稱。在圖 1 中,電影的標題和發布日期已定義兩次:一次在 movie 物件中,並在 person 物件的 filmography 子物件中再次定義。這個結構定義會重複使用 movieTitle 欄位,讓結構定義支援兩種搜尋行為:

  • 當使用者搜尋電影名稱時,系統會顯示電影搜尋結果
  • 當使用者搜尋演員演員電影的電影時,顯示人物搜尋結果

同樣地,結構定義重複使用 releaseDate 欄位,因為兩個 movieTitle 欄位的意義相同。

規劃自己的結構定義時,請考慮存放區中可能包含的相關欄位,其中包含您在結構定義中多次宣告的資料。

新增各類型選項

PropertyDefinition 列出了所有屬性的一般搜尋功能選項,無論資料類型為何。

  • isReturnable - 指出這項屬性是否應透過 Query API 傳回應傳回搜尋結果中的資料。所有範例電影屬性都可傳回。不可傳回屬性可用於搜尋或排序結果,而不必傳回使用者。
  • isRepeatable - 指出該屬性是否允許多個值。舉例來說,一部電影只有一個上映日期,但可以有多位演員。
  • isSortable - 表示該屬性可用於排序。針對可重複使用的屬性,則無法如此。舉例來說,電影搜尋結果可依發布日期或觀眾評分排序。
  • isFacetable - 表示這個屬性可用於產生商情項目。 商情項目可用來修正搜尋結果,方便使用者查看初始結果,然後新增條件 (或商情項目) 來進一步修正這些結果。如果類型為物件,而且 isReturnable 必須設為 true,才能設定這個選項。最後,這個選項僅支援列舉、布林值和文字屬性。 舉例來說,我們可能會在範例結構定義中建立 genreactorNameuserRatingmpaaRating 錶面,以便用於互動式的互動式搜尋結果。
  • isWildcardSearchable 表示使用者可以對這項資源執行萬用字元搜尋。這個選項僅適用於文字屬性。文字欄位在搜尋文字欄位中的運作方式,取決於 exactMatchWithOperator 欄位設定的值。如果 exactMatchWithOperator 設為 true,文字值會權杖化為單一不可部分值,並對其執行萬用字元搜尋。舉例來說,如果文字值為 science-fiction,則萬用字元查詢 science-* 會符合該文字。如果 exactMatchWithOperator 設為 false,文字值會權杖化,系統會對每個權杖執行萬用字元搜尋。舉例來說,如果文字值是「ics-科幻」,表示萬用字元「sci*」或「fi*」與項目相符,但「science-*」並不相符。

這些一般搜尋功能參數都是布林值,它們的預設值都是 false,且必須設為 true 才能使用。

下表列出了 movie 物件所有屬性的 true 布林值參數:

屬性 isReturnable isRepeatable isSortable isFacetable isWildcardSearchable
movieTitle true true
releaseDate true true
genre true true true
duration true
actorName true true true true
userRating true true
mpaaRating true true

genreactorName 都將 isRepeatable 設為 true,因為電影可以屬於多個類型,且通常具有多位演員。屬性不可重複或包含在可重複子物件中,因此無法排序。

定義類型

PropertyDefinition 參考資料區段會列出數個 xxPropertyOptions,其中 xx 是特定類型的,例如 boolean。如要設定屬性的資料類型,您必須定義適當的資料類型物件。為屬性定義資料類型物件時,系統會建立該屬性的資料類型。例如,在 movieTitle 屬性中定義 textPropertyOptions 代表電影名稱屬於類型文字。下列程式碼片段顯示包含設定 textPropertyOptionsmovieTitle 屬性。

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    ...
  },
  ...
},

每項資源只能有一個關聯的資料類型。例如,在電影結構定義中,releaseDate 只能為日期 (例如2016-01-13) 或字串 (例如:January 13, 2016),但兩者只能擇一。

以下是用於指定電影結構定義範例中資料類型的資料類型:

屬性 資料類型物件
movieTitle textPropertyOptions
releaseDate datePropertyOptions
genre enumPropertyOptions
duration textPropertyOptions
actorName textPropertyOptions
userRating integerPropertyOptions
mpaaRating textPropertyOptions

您為資源選擇的資料類型取決於預期的用途。在這種電影架構的想像情境中,使用者希望依時間先後排序結果,因此 releaseDate 是日期物件。例如,如果比較 12 月與 1 月的發布版本在不同情況下的版本,則字串格式可能很實用。

設定特定類型選項

PropertyDefinition 參考資料區段會連結至各個類型的選項。除了 enumPropertyOptions 中的 possibleValues 清單外,大多數類型專屬選項都是選用項目。此外,orderedRanking 選項可讓您決定相關值的排名。下列程式碼片段顯示包含設定 textPropertyOptionsmovieTitle 屬性,以及使用 retrievalImportance 類型的專用選項。

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    ...
  },
  ...
}

以下是範例結構定義中使用的其他特定類型選項:

屬性 類型 特定類型選項
movieTitle textPropertyOptions retrievalImportance
releaseDate datePropertyOptions
genre enumPropertyOptions
duration textPropertyOptions
actorName textPropertyOptions
userRating integerPropertyOptions orderedRankingmaximumValue
mpaaRating textPropertyOptions

定義運算子選項

除了特定類型選項之外,每種類型都有一組選用 operatorOptions 選項,用於說明屬性如何做為搜尋運算子。下列程式碼片段顯示 movieTitle 屬性,其中 textPropertyOptions 設定資料類型,以及 retrievalImportanceoperatorOptions 類型專屬選項。

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
      "operatorName": "title"
    }
  },
  ...
}

每個 operatorOptions 都有 operatorName,例如 movieTitletitle。運算子名稱是屬性的搜尋運算子。搜尋運算子是使用者縮小搜尋範圍時要使用的實際參數。舉例來說,如要根據標題搜尋電影,使用者必須輸入 title:movieName,其中 movieName 是電影名稱。

運算子名稱不必與屬性名稱相同。請改用運算子名稱,反映貴機構使用者最常使用的字詞。舉例來說,如果使用者偏好「性的」字詞,而不是「標題」運算子,那麼運算子名稱應設為「名稱」。

只要所有屬性解析為相同類型,即可針對多個屬性使用相同的運算子名稱。在查詢中使用共用運算子名稱時,系統會擷取使用該運算子名稱的所有屬性。舉例來說,假設電影物件擁有 plotSummaryplotSynopsis 屬性,而且每個屬性都有 operatorNameplot。只要這兩個屬性都是文字 (textPropertyOptions),則使用 plot 搜尋運算子的單一查詢會擷取這兩項屬性。

除了 operatorName 以外,可排序的屬性也可以在 operatorOptions 中加入 lessThanOperatorNamegreaterThanOperatorName 欄位。使用者可以透過這些選項,與提交值的比較建立查詢。

最後,textOperatorOptionsoperatorOptions 欄位含有 exactMatchWithOperator。如果將 exactMatchWithOperator 設為 true,查詢字串必須與整個屬性值相符,而不能只從文字中找到。在運算子搜尋和商情項目比對中,系統會將文字值視為一個不可部分的值。

舉例來說,您可以對具有類型屬性的「書籍」或「電影」物件建立索引。 類型可能包括「科學迷」、「科學」和「小說」。將 exactMatchWithOperator 設為 false 或省略時,搜尋類型或選取「科學」或「指紋」商情項目也會傳回「Science-Fiction」;同時也是「權杖」和「科學」符記。當 exactMatchWithOperatortrue 時,文字會視為單一符記,因此並非「科學」和「科學 F」的配對。

(選用) 新增 displayOptions 區段

任何 propertyDefinition 區段結尾都有選用的 displayOptions 區段。這個部分包含一個 displayLabel 字串。 displayLabel 是建議屬性的好屬性文字標籤。如果屬性使用 ObjectDisplayOptions 設為顯示,這個標籤會顯示在屬性前面。如果屬性設定為顯示且未定義 displayLabel,則只會顯示屬性值。

下列程式碼片段顯示 displayLabel 設為 'Title' 的 movieTitle 屬性。

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
       "operatorName": "title"
    }
},
  "displayOptions": {
    "displayLabel": "Title"
  }
},

以下是範例結構定義中 movie 物件所有屬性的 displayLabel 值:

屬性 displayLabel
movieTitle Title
releaseDate Release date
genre Genre
duration Run length
actorName Actor
userRating Audience score
mpaaRating MPAA rating

(選用) 新增 suggestionFilteringOperators[] 區段

任何 propertyDefinition 區段結尾都有選用的 suggestionFilteringOperators[] 區段。在本節中,您可以定義用來篩選自動完成建議的屬性。例如,您可以定義 genre 的運算子,以便根據使用者偏好的電影類型篩選建議。這樣一來,當使用者輸入搜尋查詢時,系統只會在自動完成建議中顯示與其偏好類型相符的電影。

註冊結構定義

如要從 Cloud Search 查詢傳回結構化資料,請向 Cloud Search 結構定義服務註冊結構定義。註冊結構定義時,需要您在初始化資料來源步驟中取得的資料來源 ID。

使用資料來源 ID 發出 UpdateSchema 要求,以註冊結構定義。

UpdateSchema 參考資料頁面所述,請發出以下 HTTP 要求來註冊結構定義:

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

要求的內容應包含以下內容:

{
  "validateOnly": // true or false,
  "schema": {
    // ... Your complete schema object ...
  }
}

使用 validateOnly 選項來測試結構定義的有效性,而不必實際註冊。

為資料建立索引

結構定義註冊完成後,請使用索引呼叫填入資料來源。一般來說,您可以透過內容連接器完成建立索引。

使用電影結構定義時,單一電影的 REST API 索引要求如下所示:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "sourceRepositoryUrl": "http://www.imdb.com/title/tt2234155/?ref_=nv_sr_1",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": {
            "values": [
              "Titanic"
            ]
          }
        },
        {
          "name": "releaseDate",
          "dateValues": {
            "values": [
              {
                "year": 1997,
                "month": 12,
                "day": 19
              }
            ]
          }
        },
        {
          "name": "actorName",
          "textValues": {
            "values": [
              "Leonardo DiCaprio",
              "Kate Winslet",
              "Billy Zane"
            ]
          }
        },
        {
          "name": "genre",
          "enumValues": {
            "values": [
              "Drama",
              "Action"
            ]
          }
        },
        {
          "name": "userRating",
          "integerValues": {
            "values": [
              8
            ]
          }
        },
        {
          "name": "mpaaRating",
          "textValues": {
            "values": [
              "PG-13"
            ]
          }
        },
        {
          "name": "duration",
          "textValues": {
            "values": [
              "3 h 14 min"
            ]
          }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

請注意,objectType 欄位中的 movie 值與結構定義中的物件定義名稱相符。透過比對這兩個值,Cloud Search 會在建立索引時知道要使用哪個結構定義物件。

另請注意,結構定義屬性 releaseDate 編入索引如何使用其沿用的 yearmonthday 子屬性,原因是該屬性是透過 datePropertyOptions 定義為 date 資料類型。不過,由於結構定義中並未定義 yearmonthday,因此您無法查詢其中一項屬性 (例如year)。

另請注意,如何使用值清單為可重複屬性 actorName 建立索引。

找出潛在索引問題

結構定義與索引最常見的兩個問題如下:

  • 您的索引要求含有尚未向結構定義服務註冊的結構定義物件或屬性名稱。這個問題會忽略屬性或物件。

  • 您的索引要求具有類型與結構定義中登錄類型不同的屬性。這個問題會導致 Cloud Search 在建立索引時傳回錯誤。

使用多種查詢類型來測試結構定義

在註冊大型實際工作環境資料存放區的結構定義之前,請考慮使用較小的測試資料存放區進行測試。透過較小的測試存放區進行測試,可讓您快速調整結構定義,並刪除已建立索引的資料,而不會影響較大的索引或現有的實際工作環境索引。針對測試資料存放區,請建立僅授權測試使用者建立的 ACL,讓其他使用者無法在搜尋結果中看到這項資料。

如要建立搜尋搜尋查詢以驗證搜尋查詢,請參閱搜尋介面

本節包含幾個可用於查詢電影結構定義的不同查詢範例。

使用一般查詢進行測試

一般查詢會傳回資料來源中包含特定字串的所有項目。使用搜尋介面時,您可以輸入「titanic"」字詞並按下 Return 鍵,對電影資料來源執行一般查詢。所有具有「titanic」字詞的電影都應在搜尋結果中傳回。

使用運算子進行測試

在查詢中加入運算子,將結果限制為符合特定運算子值的項目。舉例來說,建議您使用 actor 運算子找出特定演員主演的所有電影。使用搜尋介面時,您只要輸入 operator=value 組合 (例如「&quo;actor:Zane"」並按下 Return) 即可執行這個運算子查詢。所有以 Zane 為演員的電影均應在搜尋結果中傳回。

調整結構定義

完成結構定義和資料使用後,請繼續監控哪些功能有效,以及對使用者無法運作。請考慮在以下情況調整結構定義:

  • 為先前未建立索引的欄位建立索引。舉例來說,使用者可能會依據導演名稱重複搜尋電影,因此您可以調整結構定義,以支援導演名稱。
  • 根據使用者意見回饋變更搜尋運算子名稱。運算子名稱容易使用。如果您的使用者持續「記住」運算子的名稱,您可以考慮修改。

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

在結構定義中變更下列任一值,即可重新建立資料索引。您只需提交新的 UpdateSchema 要求,索引就會繼續運作:

  • 運算子名稱。
  • 整數的最小值和最大值。
  • 按整數和列舉排序的排名。
  • 即時選項。
  • 顯示選項。

針對後續變更,先前已建立索引的資料將繼續根據先前註冊的結構定義運作。不過,如果現有的項目有下列變更,您就必須重新建立索引現有的項目以檢視更新項目:

  • 新增或移除新屬性或物件
  • isReturnableisFacetableisSortablefalse 變更為 true

請「僅」僅在有明確用途和需求的情況下,將 isFacetableisSortable 設為 true

最後,當您標記屬性 isSuggestable 來更新結構定義時,您必須重新為資料建立索引,造成屬性的自動完成功能出現延遲。

不允許的屬性變更

即使您為資料重新建立索引,也不允許某些結構定義變更,因為這會導致索引中斷,或是產生不一致或不一致的搜尋結果。包括:

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

但設有限制。

變更複雜的結構定義

為避免產生搜尋結果不佳或已變更搜尋索引的變更,Cloud Search 會在存放區建立索引後,禁止某些類型的 UpdateSchema 要求異動。例如,屬性的資料類型或名稱一經設定即無法變更。即使您對資料重新建立索引,也無法透過簡單的 UpdateSchema 要求完成這些變更。

如果您必須對結構定義另外進行「不允許」變更,則您通常可以進行一系列「允許」變更的效果。一般而言,這種做法需要先將舊屬性從舊物件定義遷移至新版物件,然後傳送只使用新版屬性的索引要求。

下列步驟將說明如何變更屬性的資料類型或名稱:

  1. 在結構定義中的物件定義新增屬性。使用與您要變更的屬性不同的名稱。
  2. 使用新定義發出 UpdateSchema 要求。請務必在要求中傳送整個結構定義,包括新屬性。
  3. 從資料存放區補充索引。如要補充索引,請使用新屬性 (而非「舊」) 傳送所有索引要求,因為這可能會導致重複計算查詢。

    1. 建立索引時,請檢查新屬性並預設為舊屬性,以免行為不一致。
    2. 完成補充作業後,請執行測試查詢進行驗證。
  4. 刪除舊資源。再次發出沒有舊屬性名稱的 UpdateSchema 要求,並在日後停止建立索引的要求中繼續使用舊資源名稱。

  5. 將所有舊資源使用情形遷移至新資源。例如,如果您將屬性名稱從「creator」改為「author」;您必須更新查詢程式碼,才能使用先前參照該建立者的作者。

Cloud Search 會將已刪除屬性或物件的記錄保留 30 天,以免發生任何非預期的索引建立結果。在該 30 天內,請不要遷移已刪除物件或屬性的所有使用方式,包括在日後停止建立索引的要求時這麼做。這可確保您之後決定重新啟用該屬性或物件時,以便維持索引的正確性。

瞭解大小限制

Cloud Search 會對結構化資料物件和結構定義的大小設下限制。這些限制包括:

  • 頂層物件數量上限為 10 個物件。
  • 結構化資料階層的深度上限為 10 個層級。
  • 物件中的欄位總數上限為 1000 個,其中包括原始欄位的數量加上每個巢狀物件中的欄位總數。

後續步驟

以下是建議採取的後續步驟:

  1. 建立搜尋介面來測試結構定義。

  2. 調整結構定義以改善搜尋品質

  3. 建構出最佳查詢解讀的結構定義

  4. 瞭解如何透過 _dictionaryEntry 結構定義定義貴公司常用字詞的同義詞。如要使用 _dictionaryEntry 結構定義,請參閱定義同義詞

  5. 建立連接器