Google Cloud Search 結構定義是 JSON 結構，可定義在編入索引和查詢資料時要使用的物件、屬性和選項。內容連接器會讀取存放區中的資料，並根據註冊的結構定義，為資料建立結構和索引。
您可以將 JSON 結構定義物件提供給 API，然後註冊該物件，藉此建立結構定義。您必須為每個存放區註冊架構物件，才能為資料建立索引。
本文將說明建立結構定義的基本概念。如要瞭解如何調整結構定義以改善搜尋體驗，請參閱「改善搜尋品質」一文。
建立結構定義
以下是建立 Cloud Search 結構定義的步驟清單：
找出預期的使用者行為
預先瞭解使用者會提出哪些查詢類型，有助於您擬定建立結構定義的策略。
舉例來說，針對電影資料庫發出查詢時，您可能會預期使用者會提出類似「請顯示所有由 Robert Redford 主演的電影」的查詢。因此，您的結構定義必須支援根據「所有含有特定演員的電影」查詢結果。
如要定義結構定義，以反映使用者的行為模式，請考慮執行下列任務：
- 評估不同使用者所需的各種查詢。
- 找出可能用於查詢的物件。物件是相關資料的邏輯集合，例如電影資料庫中的電影。
- 找出組成物件的屬性和值，這些屬性和值可能會用於查詢。屬性是物件的可索引屬性，可包含基本值或其他物件。舉例來說，電影物件可能會包含電影名稱和上映日期等屬性，做為原始值。電影物件也可能包含其他物件，例如演員，這些物件具有自己的屬性，例如名稱或角色。
- 指出屬性有效值的範例。值是屬性索引的實際資料。舉例來說，資料庫中某部電影的名稱可能為「Raiders of the Lost Ark」。
- 決定使用者想要的排序和排名選項。舉例來說，在查詢電影時，使用者可能會想依時間排序並依觀眾評分排名，而不需要依字母順序排序。
- (選用) 請考慮是否有某個屬性可代表更具體的執行搜尋的情況，例如使用者的職務或部門，以便根據情況提供自動完成建議。舉例來說，如果使用者搜尋電影資料庫，可能只對特定類型的電影感興趣。使用者可定義搜尋結果應返回哪些類型，這可能會是使用者個人資料的一部分。接著，當使用者開始輸入電影查詢時，系統會在自動完成建議中，只建議他們偏好的類型 (例如「動作片」) 的電影。
- 列出這些物件、屬性和可用於搜尋的範例值。(如要進一步瞭解這個清單的使用方式，請參閱「定義運算子選項」一節)。
初始化資料來源
資料來源代表已編入索引並儲存在 Google Cloud 中的存放區資料。如要瞭解如何初始化資料來源，請參閱「管理第三方資料來源」。
系統會從資料來源傳回使用者的搜尋結果。使用者點選搜尋結果時，Cloud Search 會使用索引要求中提供的網址，將使用者導向實際項目。
定義物件
結構定義中資料的基本單位是物件，也稱為「結構定義物件」，是資料的邏輯結構。在電影資料庫中，資料的一個邏輯結構是「movie」。另一個物件可能是「person」，用來代表電影中的演員和工作人員。
架構中的每個物件都包含一系列屬性或描述物件的屬性，例如電影的名稱和片長，或人物的名稱和出生日期。物件的屬性可包含基本值或其他物件。
圖 1 顯示電影和人物物件以及相關屬性。
Cloud Search 結構定義基本上是 objectDefinitions 標記中定義的物件定義陳述式清單。下列結構定義程式碼片段顯示電影和人物結構定義物件的 objectDefinitions 陳述式。
{
"objectDefinitions": [
{
"name": "movie",
...
},
{
"name": "person",
...
}
]
}
定義結構定義物件時，您會為物件提供 name，且該物件必須在結構定義中的所有其他物件中保持不重複。通常您會使用 name 值來描述物件，例如電影物件的 movie。結構定義服務會使用 name 欄位做為可建立索引的物件的主要 ID。如要進一步瞭解 name 欄位，請參閱「物件定義」。
定義物件屬性
如 ObjectDefinition 參考資料所述，物件名稱後面會接著一組 options 和 propertyDefinitions 清單。options 可進一步包含 freshnessOptions 和 displayOptions。freshnessOptions 可用於根據商品的新鮮度調整搜尋排名。displayOptions 用於定義是否要在物件的搜尋結果中顯示特定標籤和屬性。
propertyDefinitions 部分可用於定義物件的屬性，例如電影名稱和發行日期。
以下程式碼片段顯示具有兩個屬性的 movie 物件：movieTitle 和 releaseDate。
{
"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。 - 類型及其相關的類型專屬選項，例如前述程式碼片段中的
textPropertyOptions和retrievalImportance。 operatorOptions，說明如何將屬性用作搜尋運算子。- 一或多個
displayOptions，例如先前程式碼片段中的displayLabel。
屬性的 name 在包含物件內必須是唯一的，但其他物件和子物件中可以使用相同的名稱。在圖 1 中，電影的標題和上映日期已定義兩次：一次在 movie 物件中，另一次則在 person 物件的 filmography 子物件中。這個結構定義會重複使用 movieTitle 欄位，以便支援兩種搜尋行為：
- 當使用者搜尋電影名稱時，顯示電影結果。
- 當使用者搜尋演員演出的電影名稱時，顯示人物搜尋結果。
同樣地，結構定義會重複使用 releaseDate 欄位，因為它對兩個 movieTitle 欄位具有相同的含義。
在開發自己的結構化定義時，請考量存放區可能會如何提供相關欄位，其中包含您想在結構化定義中宣告多次的資料。
新增類型無關的選項
PropertyDefinition 會列出所有屬性 (不論資料類型為何) 的一般搜尋功能選項。
isReturnable：指出屬性是否可識別應透過查詢 API 在搜尋結果中傳回的資料。所有示例電影屬性皆可退還。非可傳回屬性可用於搜尋或排名結果，但不會傳回給使用者。isRepeatable：指出屬性是否允許多個值。舉例來說，一部電影只有一個上映日期，但可能有許多演員。isSortable：表示可用於排序的屬性。但對於可重複使用的資源，這項條件就無法成立。舉例來說，電影結果可能會依據上映日期或觀眾評分排序。isFacetable：表示這項屬性可用於產生商情項目。商情項目可用於縮小搜尋結果範圍，使用者可先查看初始結果，然後新增條件或商情項目，進一步縮小結果範圍。如果屬性類型為物件，則無法將此選項設為 true，且isReturnable必須設為 true 才能設定此選項。最後，這個選項僅支援列舉、布林值和文字屬性。舉例來說，在範例結構定義中，我們可以將genre、actorName、userRating和mpaaRating設為可面向資料表，以便用於互動式精進搜尋結果。isWildcardSearchable表示使用者可以針對此屬性執行萬用字元搜尋。這個選項僅適用於文字資源。萬用字元搜尋在文字欄位中運作的方式，取決於您在 exactMatchWithOperator 欄位中設定的值。如果exactMatchWithOperator設為true，系統會將文字值切割為一個原子值，並針對該值執行萬用字元搜尋。舉例來說，如果文字值是science-fiction，萬用字元查詢science-*就會與其相符。如果exactMatchWithOperator設為false，系統會將文字值切割成符記，並針對每個符記執行萬用字元搜尋。舉例來說，如果文字值是「科幻小說」，萬用字元查詢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 |
genre 和 actorName 的 isRepeatable 都設為 true，因為電影可能屬於多種類型，且通常有超過一個演員。如果屬性可重複或包含在可重複的子物件中，就無法排序。
定義類型
「PropertyDefinition」參考資料會列出幾個 xxPropertyOptions，其中 xx 是特定類型，例如 boolean。如要設定屬性的資料類型，您必須定義適當的資料類型物件。為屬性定義資料類型物件，即可建立該屬性的資料類型。舉例來說，為 movieTitle 屬性定義 textPropertyOptions，表示電影名稱為文字類型。以下程式碼片段顯示 movieTitle 屬性，其中 textPropertyOptions 會設定資料類型。
{
"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」PropertyDefinition參考資料部分會連結至各類型的選項。除了 enumPropertyOptions 中的 possibleValues 清單外，大多數類型專屬選項皆為選用選項。此外，您可以使用 orderedRanking 選項，將值依相對關係排序。下列程式碼片段顯示 movieTitle 屬性，其中 textPropertyOptions 會設定資料類型，並使用 retrievalImportance 類型專屬選項。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
...
},
...
}
以下是範例結構定義中使用的其他類型專屬選項：
| 屬性 | 類型 | 類型專屬選項 |
|---|---|---|
movieTitle |
textPropertyOptions |
retrievalImportance |
releaseDate |
datePropertyOptions |
|
genre |
enumPropertyOptions |
|
duration |
textPropertyOptions |
|
actorName |
textPropertyOptions |
|
userRating |
integerPropertyOptions |
orderedRanking、maximumValue |
mpaaRating |
textPropertyOptions |
定義運算子選項
除了類型專屬選項外，每個類型都有一組選用 operatorOptions 這些選項會說明如何將屬性用於搜尋運算子。以下程式碼片段顯示 movieTitle 屬性，其中 textPropertyOptions 會設定資料類型，並使用 retrievalImportance 和 operatorOptions 類型專屬選項。
{
"name": "movieTitle",
"isReturnable": true,
"isWildcardSearchable": true,
"textPropertyOptions": {
"retrievalImportance": { "importance": "HIGHEST" },
"operatorOptions": {
"operatorName": "title"
}
},
...
}
每個 operatorOptions 都有 operatorName，例如 title 是 movieTitle 的 operatorName。運算子名稱是資源的搜尋運算子。搜尋運算子是指您希望使用者在縮小搜尋範圍時使用的實際參數。舉例來說，如果想根據電影名稱搜尋電影，使用者可以輸入 title:movieName，其中 movieName 是電影名稱。
運算子名稱不必與屬性名稱相同。相反地，您應使用反映貴機構使用者最常使用的字詞的運算子名稱。舉例來說，如果使用者偏好使用「name」而非「title」做為電影名稱，則運算子名稱應設為「name」。
只要所有屬性都能解析為相同類型，您就可以為多個屬性使用相同的運算子名稱。在查詢中使用共用運算子名稱時，系統會擷取使用該運算子名稱的所有資源。舉例來說，假設電影物件有 plotSummary 和 plotSynopsis 屬性，且每個屬性都有 operatorName 的 plot。只要這兩個屬性都是文字 (textPropertyOptions)，使用 plot 搜尋運算子的單一查詢就能同時擷取這兩個屬性。
除了 operatorName 之外，可排序的屬性也可在 operatorOptions 中包含 lessThanOperatorName 和 greaterThanOperatorName 欄位。使用者可以使用這些選項，根據提交值的比較結果建立查詢。
最後，textOperatorOptions 在 operatorOptions 中含有 exactMatchWithOperator 欄位。如果您將 exactMatchWithOperator 設為 true，查詢字串必須與整個屬性值相符，而非僅在文字中找到。在運算子搜尋和面向搜尋的情況下，文字值會視為單一原子值。
舉例來說，建議您為書籍或電影物件建立類型屬性索引。類型可包括「科幻」和「科學」等。將 exactMatchWithOperator 設為 false 或省略時，搜尋類型或選取「科學」或「小說」面向也會傳回「科幻小說」的結果，因為文字會經過剖析，且「科學」和「小說」符記會出現在「科幻小說」中。當 exactMatchWithOperator 為 true 時，系統會將文字視為單一符記，因此「科學」和「小說」都不會與「科幻小說」相符。
(選用) 新增 displayOptions 區段
任何 propertyDefinition 區段的結尾都有一個選用的 displayOptions 區段。這個部分包含一個 displayLabel 字串。displayLabel 是屬性建議的使用者友好文字標籤。如果使用 ObjectDisplayOptions 設定屬性顯示方式，系統會在屬性前方顯示這個標籤。如果屬性已設定為顯示，且未定義 displayLabel，則只會顯示屬性值。
以下程式碼片段顯示 movieTitle 屬性，其中 displayLabel 已設為「Title」。
{
"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 選項，即可測試結構定義的有效性，而無須實際註冊。
為資料建立索引
架構註冊完成後，請使用 Index 呼叫填入資料來源。索引通常會在內容連接器中完成。
使用電影結構定義時，單一電影的 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 的索引是如何使用 year、month 和 day 的子屬性，因為該屬性是透過 datePropertyOptions 定義為 date 資料類型。不過，由於 year、month 和 day 並未在結構定義中定義，因此您無法針對其中一個屬性 (例如 year) 個別執行。
請注意，可重複使用屬性 actorName 會透過使用值清單編入索引。
找出可能的索引問題
與結構定義和索引相關的兩個最常見問題如下：
你的索引要求包含未向結構定義服務註冊的結構定義物件或屬性名稱。這個問題會導致系統忽略屬性或物件。
你的索引要求含有屬性，其類型值與結構定義中註冊的類型不同。這會導致 Cloud Search 在建立索引時傳回錯誤。
使用多種查詢類型測試結構定義
為大型實際資料存放區註冊結構定義前，建議您先使用較小的測試資料存放區進行測試。使用較小的測試存放區進行測試，可讓您快速調整結構定義，並刪除已編入索引的資料，而不影響較大的索引或現有實際工作環境索引。針對測試資料存放區，請建立只授權測試使用者的 ACL，這樣其他使用者就不會在搜尋結果中看到這項資料。
如要建立搜尋介面來驗證搜尋查詢，請參閱「搜尋介面」一文。
本節包含幾個可用於測試電影結構定義的查詢範例。
使用一般查詢進行測試
一般查詢會傳回資料來源中含有特定字串的所有項目。使用搜尋介面時，您可以輸入「titanic」一詞，然後按下「Enter」鍵，對電影資料來源執行一般查詢。搜尋結果應會傳回所有含有「titanic」一詞的電影。
使用運算子進行測試
在查詢中加入運算子，可將結果限制為與該運算子值相符的項目。舉例來說，您可以使用 actor 運算子，找出所有由特定演員主演的電影。使用搜尋介面時，只要輸入 運算子=值組合 (例如 "actor:Zane")，然後按下 Enter 鍵，即可執行這項運算子查詢。搜尋結果應會傳回所有由 Zane 擔綱的電影。
調整結構定義
結構定義和資料開始使用後，請持續監控使用者能否順利使用這些項目。在下列情況下，建議調整結構定義：
- 為先前未編入索引的欄位建立索引。舉例來說，使用者可能會重複搜尋導演名稱的電影，因此您可以調整結構定義，讓導演名稱做為運算子。
- 根據使用者意見回饋變更搜尋運算子名稱。運算子名稱應以使用者友好為準。如果使用者一再「記得」錯誤的運算子名稱，您可以考慮變更。
結構定義變更後重新建立索引
變更結構定義中的下列任何值不需要重新為資料建立索引。只要提交新的 UpdateSchema 要求，索引就會繼續運作：
- 運算子名稱。
- 整數最小值和最大值。
- 整數和枚舉項目的排序排名。
- 新鮮度選項。
- 顯示選項。
針對下列變更，先前已編入索引的資料會繼續依照先前註冊的架構運作。不過，如果更新後的結構定義有下列變更，您必須重新為現有項目建立索引，才能查看變更：
- 新增或移除新資源或物件
- 將
isReturnable、isFacetable或isSortable從false變更為true。
只有在您有明確的用途和需求時，才應將 isFacetable 或 isSortable 設為 true。
最後，當您透過標記屬性 isSuggestable 更新結構定義時，必須重新為資料建立索引，這會導致該屬性使用自動完成功能時出現延遲。
不允許的屬性變更
即使重新為資料建立索引，某些結構定義變更仍不允許，因為這些變更會破壞索引，或產生不良或不一致的搜尋結果。包括以下變更：
- 資源資料類型。
- 房源名稱。
exactMatchWithOperator設定。retrievalImportance設定。
不過，我們有辦法解決這項限制。
進行複雜的結構定義變更
為避免變更導致搜尋結果不佳或搜尋索引無效，Cloud Search 會在索引庫建立索引後，禁止UpdateSchema要求中的特定類型變更。舉例來說，屬性設定後，就無法變更資料類型或名稱。即使重新為資料建立索引，也無法透過簡單的 UpdateSchema 要求完成這些變更。
如果您必須對結構定義進行不允許的變更，通常可以進行一系列允許的變更來達到相同的效果。一般來說，這包括先將已編入索引的資源從舊物件定義遷移至新定義，然後傳送只使用新資源的索引要求。
下列步驟說明如何變更資源的資料類型或名稱：
- 在結構定義中的物件定義中新增屬性。使用與要變更的屬性不同的名稱。
- 發出含有新定義的 UpdateSchema 要求。請記得在要求中傳送整個結構定義，包括新舊屬性。
從資料存放區回填索引。如要回填索引，請使用新屬性傳送所有索引要求，但不要使用舊屬性，因為這會導致查詢比對次數計算兩次。
- 在索引回填期間，請檢查新屬性，並預設為舊屬性，以免行為不一致。
- 回填完成後，請執行測試查詢來驗證。
刪除舊的資源。請發出另一個不含舊版資源名稱的 UpdateSchema 要求，並在日後索引要求中停止使用舊版資源名稱。
將舊資源的所有用途遷移至新資源。舉例來說，如果您將資源名稱從創作者變更為作者，就必須更新查詢程式碼，在先前參照創作者的地方使用作者。
Cloud Search 會保留任何已刪除的屬性或物件的記錄 30 天，以防任何重複使用導致意外的索引結果。請在 30 天內，移除所有已刪除物件或資源的用途，包括從日後的索引要求中省略這些項目。這樣一來，如果您日後決定重新啟用該屬性或物件，就能以維持索引正確性的做法進行。
瞭解大小限制
Cloud Search 對結構化資料物件和結構定義的大小設有限制。這些限制如下：
- 頂層物件的數量上限為 10 個。
- 結構化資料階層的深度上限為 10 個層級。
- 物件中的欄位總數上限為 1000，其中包括基本欄位數量，加上每個巢狀物件中的欄位數量總和。
後續步驟
以下是您可以採取的後續步驟：
建立搜尋介面來測試結構定義。
調整結構定義，提升搜尋品質。
瞭解如何利用
_dictionaryEntry結構定義公司常用的同義詞。如要使用_dictionaryEntry結構定義，請參閱「定義同義詞」。建立連接器。