- 資源:Item
- ItemAcl
- ItemAcl.AclInheritanceType
- 主體
- ItemMetadata
- 互動
- Interaction.InteractionType
- SearchQualityMetadata
- ContextAttribute
- ItemStructuredData
- StructuredDataObject
- NamedProperty
- NamedProperty.IntegerValues
- NamedProperty.DoubleValues
- NamedProperty.TimestampValues
- NamedProperty.ObjectValues
- NamedProperty.EnumValues
- NamedProperty.DateValues
- NamedProperty.TextValues
- NamedProperty.HtmlValues
- ItemContent
- ItemContent.ContentFormat
- UploadItemRef
- ItemStatus
- ProcessingError
- ProcessingErrorCode
- FieldViolation
- RepositoryError
- RepositoryError.Type
- Item.ItemType
- 方法
資源:Item
代表搜尋索引內某個項目的單一物件,例如檔案、資料夾或資料庫記錄。
JSON 表示法 |
---|
{ "name": string, "acl": { object ( |
欄位 | |
---|---|
name |
商品名稱。格式:datasources/{sourceId}/items/{itemId} 這是必填欄位。長度上限為 1536 個字元。 |
acl |
這個項目的存取控制清單 (ACL)。 |
metadata |
中繼資料資訊。 |
structuredData |
項目的結構化資料,必須符合資料來源結構定義中已註冊的物件定義。 |
content |
要建立索引的項目內容,並讓文字可供搜尋。 |
version |
必要欄位。索引系統會將資料來源的版本儲存為位元組字串,並將索引中的項目版本與使用詞序排列的佇列項目版本進行比較。 如果已排入佇列的項目版本值小於或等於目前已建立索引的項目版本,Cloud Search Indexing API 就不會將其編入索引或刪除。這個欄位的長度上限為 1,024 個位元組。 如要瞭解項目版本對刪除程序的影響,請參閱「手動刪除後處理修訂版本」。 Base64 編碼的字串。 |
status |
項目狀態。僅限輸出的欄位。 |
queue |
加入這個項目的佇列。長度上限為 100 個半形字元。 |
payload |
可儲存這個項目的其他狀態連接器。長度上限為 10,000 個位元組。 Base64 編碼的字串。 |
itemType |
這個項目的類型。 |
ItemAcl
項目的存取控制清單 (ACL)。詳情請參閱地圖 ACL。
JSON 表示法 |
---|
{ "inheritAclFrom": string, "aclInheritanceType": enum ( |
欄位 | |
---|---|
inheritAclFrom |
沿用權限清單 (ACL) 的項目名稱。注意:ACL 繼承「只」提供子項項目的存取權限,不會定義結構關係,也不會提供刪除大量項目的簡便方法。從索引刪除 ACL 父項只會修改 |
aclInheritanceType |
設定當項目繼承父項的 ACL 時要套用的存取權規則類型。這個欄位應一律與 |
readers[] |
可以在搜尋結果中查看項目的主體清單。如果項目沿用了其他項目的權限,或不想顯示該項目 (例如 |
deniedReaders[] |
明確拒絕存取搜尋結果中項目的主體清單。雖然主體的存取權預設為遭拒,但請使用遭拒的讀取器處理例外狀況並覆寫允許的讀取者清單。元素數量上限為 100 個。 |
owners[] |
選用設定。項目擁有者清單。這個欄位不會對文件存取權限造成任何影響。不過,如果查詢使用者是擁有者,則會稍微提升排名。元素數量上限為 5 個。 |
ItemAcl.AclInheritanceType
ACL 繼承的類型。
列舉 | |
---|---|
NOT_APPLICABLE |
這個項目不會繼承 ACL 的預設值。當 inheritAclFrom 空白時,請使用 NOT_APPLICABLE。沒有 ACL 繼承的項目仍可透過本身的 readers 和 deniedReaders 欄位提供 ACL。 |
CHILD_OVERRIDE |
在授權衝突期間,子項項目的 ACL 會決定其讀取權限。 |
PARENT_OVERRIDE |
在授權衝突期間,inheritAclFrom 欄位中指定的上層項目的 ACL 決定讀取權限。 |
BOTH_PERMIT |
只有在這個項目和 inheritAclFrom 欄位中指定的上層項目同時允許讀取權限時,系統才會授予存取權。 |
主體
參照使用者、群組或網域。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
gsuitePrincipal |
這個主體是 Google Workspace 使用者、群組或網域。 |
userResourceName |
這個主體是使用外部身分識別的使用者。名稱欄位必須以下列格式指定使用者資源名稱:Identitysources/{sourceId}/users/{ID} |
groupResourceName |
這個主體是使用外部身分識別的群組。名稱欄位必須以下列格式指定群組資源名稱:Identitysources/{sourceId}/groups/{ID} |
ItemMetadata
項目可用的中繼資料欄位。
JSON 表示法 |
---|
{ "title": string, "sourceRepositoryUrl": string, "containerName": string, "objectType": string, "createTime": string, "updateTime": string, "interactions": [ { object ( |
欄位 | |
---|---|
title |
商品名稱。如有指定,則會是 query.search 結果的顯示標題。長度上限為 2,048 個半形字元。 |
sourceRepositoryUrl |
提供資料的來源存放區連結。搜尋搜尋結果會將這個連結套用至標題。空白字元或特殊字元可能會導致 Cloud Search 搜尋結果連結觸發重新導向通知。如要避免這種情況,請將網址編碼。長度上限為 2,048 個半形字元。 |
containerName |
此項目的容器名稱。系統刪除容器項目後,就會自動刪除這個項目。注意:容器項目不會沿用 ACL。如要提供項目的 ACL 沿用機制,請使用 |
objectType |
項目類型。這個編號必須與為資料來源登錄的結構定義中的物件定義名稱相對應。舉例來說,如果資料來源的結構定義中含有名稱為「document」的物件定義,則該類型物件的項目索引要求應將 objectType 設為「document」。長度上限為 256 個半形字元。 |
createTime |
項目在原始碼存放區中建立的時間。 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
updateTime |
來源存放區中項目上次修改的時間。 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
interactions[] |
項目的互動清單。互動會用於改善 query.search 的品質,但不會向使用者顯示。元素數量上限為 1000 個。 |
contentLanguage |
商品的 BCP-47 語言代碼,例如「en-US」或「sr-Latn」。詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。長度上限為 32 個字元。 |
mimeType |
原始碼存放區中 |
searchQualityMetadata |
商品的其他搜尋品質中繼資料 |
keywords[] |
應符合商品的其他關鍵字或詞組。會在內部用於使用者產生的內容。元素數量上限為 100 個。長度上限為 8,192 個字元。 |
hash |
API 呼叫端提供的雜湊值。這可與 |
contextAttributes[] |
一組與項目相關聯的已命名屬性。這可用於根據要求中的情境影響商品排名。元素數量上限為 10 個。 |
互動技術
代表使用者和項目之間的互動。
JSON 表示法 |
---|
{ "type": enum ( |
欄位 | |
---|---|
type |
|
principal |
對項目執行動作的使用者。 |
interactionTime |
使用者處理項目的時間。如果單一使用者執行了同一類型的多項動作,系統只會記錄最近的動作。 RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
Interaction.InteractionType
使用者對項目進行的活動類型。
列舉 | |
---|---|
UNSPECIFIED |
無效的值。 |
VIEW |
此互動代表使用者檢視了項目。 |
EDIT |
這項互動表示使用者已編輯項目。 |
SearchQualityMetadata
項目的其他搜尋品質中繼資料。
JSON 表示法 |
---|
{ "quality": number } |
欄位 | |
---|---|
quality |
表示項目品質的指標,用於影響搜尋品質。值應介於 0.0 至 1.0 (品質最高) 之間。預設值為 0.0。 |
ContextAttribute
與項目相關聯的具名屬性,可根據要求中的背景資訊影響商品排名。
JSON 表示法 |
---|
{ "name": string, "values": [ string ] } |
欄位 | |
---|---|
name |
屬性的名稱。這個欄位不得留空。長度上限為 32 個字元。名稱開頭必須是英文字母,後面只能包含英文字母 (A 至 Z、a 至 z) 或數字 (0 到 9)。名稱會先經過正規化 (小寫),然後再進行比對。 |
values[] |
屬性的文字值。元素數量上限為 10 個。陣列中的元素長度上限為 32 個字元。系統會先對這個值進行正規化 (小寫) 比對,然後再進行比對。 |
ItemStructuredData
項目可用的結構化資料欄位。
JSON 表示法 |
---|
{
"object": {
object ( |
欄位 | |
---|---|
object |
結構化資料物件應符合資料來源結構定義中已註冊的物件定義。 |
hash |
API 呼叫端提供的雜湊值。這可與 |
StructuredDataObject
由具名屬性組成的結構化資料物件。
JSON 表示法 |
---|
{
"properties": [
{
object ( |
欄位 | |
---|---|
properties[] |
物件的屬性。元素數量上限為 1000 個。 |
NamedProperty
結構化資料的輸入名稱/值組合。值的類型應與 objectType
物件定義中 name
屬性的註冊類型相同。
JSON 表示法 |
---|
{ "name": string, // Union field |
欄位 | |
---|---|
name |
屬性的名稱。這個名稱必須與您在結構定義中註冊物件定義的屬性名稱對應。這項屬性的長度上限為 256 個字元。 |
聯集欄位 value 。具名屬性的值。請注意,屬性只能保留一種類型的值。value 只能是下列其中一項: |
|
integerValues |
|
doubleValues |
|
timestampValues |
|
booleanValue |
|
objectValues |
|
enumValues |
|
dateValues |
|
textValues |
|
htmlValues |
|
NamedProperty.IntegerValues
整數值清單。
JSON 表示法 |
---|
{ "values": [ string ] } |
欄位 | |
---|---|
values[] |
|
NamedProperty.DoubleValues
雙值清單。
JSON 表示法 |
---|
{ "values": [ number ] } |
欄位 | |
---|---|
values[] |
|
NamedProperty.TimestampValues
時間戳記值清單。
JSON 表示法 |
---|
{ "values": [ string ] } |
欄位 | |
---|---|
values[] |
RFC3339 世界標準時間「Zulu」格式的時間戳記,採用奈秒解析度,且最多 9 個小數位數。範例: |
NamedProperty.ObjectValues
物件值清單。
JSON 表示法 |
---|
{
"values": [
{
object ( |
欄位 | |
---|---|
values[] |
|
NamedProperty.EnumValues
列舉值清單。
JSON 表示法 |
---|
{ "values": [ string ] } |
欄位 | |
---|---|
values[] |
字串值的長度上限為 32 個字元。 |
NamedProperty.DateValues
日期值清單。
JSON 表示法 |
---|
{
"values": [
{
object ( |
欄位 | |
---|---|
values[] |
|
NamedProperty.TextValues
文字值清單。
JSON 表示法 |
---|
{ "values": [ string ] } |
欄位 | |
---|---|
values[] |
文字值的長度上限為 2,048 個字元。 |
NamedProperty.HtmlValues
HTML 值清單。
JSON 表示法 |
---|
{ "values": [ string ] } |
欄位 | |
---|---|
values[] |
HTML 值的長度上限為 2,048 個字元。 |
ItemContent
要由 Cloud Search 建立索引及顯示的項目內容。inlineContent
只能使用 UTF-8 編碼字串。如果內容是上傳而非二進位格式,則必須採用 UTF-8 編碼。
JSON 表示法 |
---|
{ "contentFormat": enum ( |
欄位 | |
---|---|
contentFormat |
|
hash |
由 API 用戶端針對內容計算並提供的雜湊資訊。可與 items.push 方法搭配使用,計算修改後的狀態。長度上限為 2,048 個半形字元。 |
聯集欄位
|
|
inlineContent |
在更新方法中內嵌提供的內容。長度上限為 102400 個位元組 (100 KiB)。 Base64 編碼的字串。 |
contentDataRef |
透過寫入方法上傳先前上傳內容的參考 ID。 |
ItemContent.ContentFormat
內容的格式。如果採用 RAW 格式,內容應採用 mimeType
指定的格式。
列舉 | |
---|---|
UNSPECIFIED |
無效的值。 |
HTML |
內容格式為 HTML。 |
TEXT |
contentFormat 是任意文字的格式。 |
RAW |
contentFormat 是原始位元組, |
UploadItemRef
代表上傳工作階段參考資料。這個參考檔案是透過 upload method
建立。這個參考檔案在建立後的 30 天內有效。更新項目內容可能會透過「contentDataRef
」參照上傳的內容。
JSON 表示法 |
---|
{ "name": string } |
欄位 | |
---|---|
name |
內容參照的名稱。長度上限為 2,048 個半形字元。 |
ItemStatus
其中包含項目狀態和任何錯誤。
JSON 表示法 |
---|
{ "code": enum ( |
欄位 | |
---|---|
code |
狀態碼。 |
processingErrors[] |
如果項目處於「ERROR」狀態,請提供錯誤詳細資料。 |
repositoryErrors[] |
連接器回報的存放區錯誤。 |
ProcessingError
JSON 表示法 |
---|
{ "code": enum ( |
欄位 | |
---|---|
code |
指出錯誤性質的錯誤代碼。 |
errorMessage |
錯誤的說明。 |
fieldViolations[] |
如果項目欄位無效,這個欄位會包含驗證錯誤的詳細資料。 |
ProcessingErrorCode
這些程式碼會指出 Cloud Search 伺服器處理項目時發生的錯誤。一個項目可能包含多個處理錯誤。
列舉 | |
---|---|
PROCESSING_ERROR_CODE_UNSPECIFIED |
僅限輸入的值。請在「項目」中使用這個值。 |
MALFORMED_REQUEST |
項目的 ACL、中繼資料或內容格式錯誤或處於無效狀態。Field violations 包含問題所在的詳細資訊。 |
UNSUPPORTED_CONTENT_FORMAT |
不支援計數格式。 |
INDIRECT_BROKEN_ACL |
項目包含不完整的 ACL 資訊,可能是因為沿用其他項目已被毀損的 ACL 或包含未對應的子系群組。 |
ACL_CYCLE |
ACL 繼承圖表形成一個循環。 |
FieldViolation
JSON 表示法 |
---|
{ "field": string, "description": string } |
欄位 | |
---|---|
field |
違規欄位路徑。 |
description |
錯誤的說明。 |
RepositoryError
連接器與來源存放區通訊時發生錯誤。
JSON 表示法 |
---|
{
"type": enum ( |
欄位 | |
---|---|
type |
錯誤類型。 |
httpStatusCode |
錯誤代碼。符合 HTTP 狀態碼的定義。 |
errorMessage |
說明錯誤的訊息。訊息的長度上限為 8,192 個字元。 |
RepositoryError.Type
存放區通訊問題的錯誤代碼清單。
列舉 | |
---|---|
UNKNOWN |
發生不明錯誤。 |
NETWORK_ERROR |
主機不明或無法連上。 |
DNS_ERROR |
DNS 問題,例如 DNS 伺服器沒有回應。 |
CONNECTION_ERROR |
無法連線至存放區伺服器。 |
AUTHENTICATION_ERROR |
憑證錯誤,導致驗證失敗。 |
AUTHORIZATION_ERROR |
服務帳戶未獲得存放區的授權。 |
SERVER_ERROR |
存放區伺服器錯誤。 |
QUOTA_EXCEEDED |
超過配額。 |
SERVICE_UNAVAILABLE |
伺服器暫時無法使用。 |
CLIENT_ERROR |
用戶端相關錯誤,例如從連接器傳送至存放區伺服器的要求無效。 |
Item.ItemType
列舉 | |
---|---|
UNSPECIFIED |
|
CONTENT_ITEM |
僅用於提供資訊的索引項目。無法在「containerName 」或「inheritAclFrom 」欄位中參照這些項目。 |
CONTAINER_ITEM |
已建立索引的項目,且用途是透過 ACL 和/或包含其他項目提供其他項目。 |
VIRTUAL_CONTAINER_ITEM |
項目不會建立索引,但用途與 CONTAINER_ITEM 相同。 |
方法 |
|
---|---|
|
刪除指定資源名稱的 Item resource 。 |
|
刪除佇列中的所有項目。 |
|
依項目名稱取得 Item resource 。 |
|
更新 Item ACL、中繼資料和內容。 |
|
列出 Item resources 的所有或子集。 |
|
針對索引佇列中的未保留項目進行輪詢,並將某項集合標示為保留,從優先順序最高的 ItemStatus 項目開始。 |
|
將項目推送到佇列,以便稍後輪詢及更新。 |
|
取消保留佇列中的所有項目,讓所有項目都符合受輪詢的資格。 |
|
建立上傳項目內容的上傳工作階段。 |