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 欄位做為可建立索引的物件的主要識別碼。如要進一步瞭解 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- 表示屬性可用於產生「facet」。商情項目可用於縮小搜尋結果範圍，使用者可先查看初始結果，然後新增條件或商情項目，進一步縮小結果範圍。如果屬性類型為物件，則無法將此選項設為 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，查詢字串必須與整個屬性值相符，而非僅在文字中找到。在運算子搜尋與 Facet 比對中，文字值會視為一個不可分割的值。
舉例來說，建議您使用類型屬性為 Book 或 Movie 物件建立索引。類型可包括「科幻」和「科學」等。將 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" 字詞並按下 Return 鍵，針對電影資料來源執行一般查詢。搜尋結果應會傳回所有含有「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 個層級。
- 物件中的欄位總數上限為 1,000 個，其中包括原始欄位數量，再加上每個巢狀物件中的欄位數量總和。
後續步驟
以下是您可以採取的後續步驟：
建立搜尋介面來測試結構定義。
調整結構定義，提升搜尋品質。
瞭解如何利用
_dictionaryEntry結構定義，定義公司常用字詞的同義詞。如要使用_dictionaryEntry結構定義，請參閱「定義同義詞」。建立連接器。