REST Resource: indexing.datasources.items

資源：Item

代表搜尋索引內某個項目的單一物件，例如檔案、資料夾或資料庫記錄。

JSON 表示法 
{
  "name": string,
  "acl": {
    object (ItemAcl)
  },
  "metadata": {
    object (ItemMetadata)
  },
  "structuredData": {
    object (ItemStructuredData)
  },
  "content": {
    object (ItemContent)
  },
  "version": string,
  "status": {
    object (ItemStatus)
  },
  "queue": string,
  "payload": string,
  "itemType": enum (Item.ItemType)
}
欄位
name

string

商品名稱。格式：datasources/{sourceId}/items/{itemId}

這是必填欄位。長度上限為 1536 個字元。
acl

object (ItemAcl)

這個項目的存取控制清單 (ACL)。
metadata

object (ItemMetadata)

中繼資料資訊。
structuredData

object (ItemStructuredData)

項目的結構化資料，必須符合資料來源結構定義中已註冊的物件定義。
content

object (ItemContent)

要建立索引的項目內容，並讓文字可供搜尋。
version

string (bytes format)

必要欄位。索引系統會將資料來源的版本儲存為位元組字串，並將索引中的項目版本與使用詞序排列的佇列項目版本進行比較。

如果已排入佇列的項目版本值小於或等於目前已建立索引的項目版本，Cloud Search Indexing API 就不會將其編入索引或刪除。這個欄位的長度上限為 1,024 個位元組。

如要瞭解項目版本對刪除程序的影響，請參閱「手動刪除後處理修訂版本」。

Base64 編碼的字串。
status

object (ItemStatus)

項目狀態。僅限輸出的欄位。
queue

string

加入這個項目的佇列。長度上限為 100 個半形字元。
payload

string (bytes format)

可儲存這個項目的其他狀態連接器。長度上限為 10,000 個位元組。

Base64 編碼的字串。
itemType

enum (Item.ItemType)

這個項目的類型。

ItemAcl

項目的存取控制清單 (ACL)。詳情請參閱地圖 ACL。

JSON 表示法 
{
  "inheritAclFrom": string,
  "aclInheritanceType": enum (ItemAcl.AclInheritanceType),
  "readers": [
    {
      object (Principal)
    }
  ],
  "deniedReaders": [
    {
      object (Principal)
    }
  ],
  "owners": [
    {
      object (Principal)
    }
  ]
}
欄位
inheritAclFrom

string

沿用權限清單 (ACL) 的項目名稱。注意：ACL 繼承「只」提供子項項目的存取權限，不會定義結構關係，也不會提供刪除大量項目的簡便方法。從索引刪除 ACL 父項只會修改 inheritAclFrom 欄位中參照父項的子項項目存取權限。該項目仍在索引中，但可能不會顯示在搜尋結果中。相反地，刪除容器項目時，也會一併刪除透過 containerName 欄位參照該容器的所有項目。這個欄位的長度上限為 1536 個字元。
aclInheritanceType

enum (ItemAcl.AclInheritanceType)

設定當項目繼承父項的 ACL 時要套用的存取權規則類型。這個欄位應一律與 inheritAclFrom 欄位一起設定。此外，如果已設定 inheritAclFrom 欄位，這個欄位應設為有效的 AclInheritanceType。
readers[]

object (Principal)

可以在搜尋結果中查看項目的主體清單。如果項目沿用了其他項目的權限，或不想顯示該項目 (例如 virtual containers)，則為選用屬性。元素數量上限為 1000 個。
deniedReaders[]

object (Principal)

明確拒絕存取搜尋結果中項目的主體清單。雖然主體的存取權預設為遭拒，但請使用遭拒的讀取器處理例外狀況並覆寫允許的讀取者清單。元素數量上限為 100 個。
owners[]

object (Principal)

選用設定。項目擁有者清單。這個欄位不會對文件存取權限造成任何影響。不過，如果查詢使用者是擁有者，則會稍微提升排名。元素數量上限為 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 principal can be only one of the following:
  "gsuitePrincipal": {
    object (GSuitePrincipal)
  },
  "userResourceName": string,
  "groupResourceName": string
  // End of list of possible types for union field principal.
}
欄位

聯集欄位 principal。

principal 只能採用下列其中一種設定：
gsuitePrincipal

object (GSuitePrincipal)

這個主體是 Google Workspace 使用者、群組或網域。
userResourceName

string

這個主體是使用外部身分識別的使用者。名稱欄位必須以下列格式指定使用者資源名稱：Identitysources/{sourceId}/users/{ID}
groupResourceName

string

這個主體是使用外部身分識別的群組。名稱欄位必須以下列格式指定群組資源名稱：Identitysources/{sourceId}/groups/{ID}

ItemMetadata

項目可用的中繼資料欄位。

JSON 表示法 
{
  "title": string,
  "sourceRepositoryUrl": string,
  "containerName": string,
  "objectType": string,
  "createTime": string,
  "updateTime": string,
  "interactions": [
    {
      object (Interaction)
    }
  ],
  "contentLanguage": string,
  "mimeType": string,
  "searchQualityMetadata": {
    object (SearchQualityMetadata)
  },
  "keywords": [
    string
  ],
  "hash": string,
  "contextAttributes": [
    {
      object (ContextAttribute)
    }
  ]
}
欄位
title

string

商品名稱。如有指定，則會是 query.search 結果的顯示標題。長度上限為 2,048 個半形字元。
sourceRepositoryUrl

string

提供資料的來源存放區連結。搜尋搜尋結果會將這個連結套用至標題。空白字元或特殊字元可能會導致 Cloud Search 搜尋結果連結觸發重新導向通知。如要避免這種情況，請將網址編碼。長度上限為 2,048 個半形字元。
containerName

string

此項目的容器名稱。系統刪除容器項目後，就會自動刪除這個項目。注意：容器項目不會沿用 ACL。如要提供項目的 ACL 沿用機制，請使用 inheritAclFrom 欄位。長度上限為 1536 個字元。
objectType

string

項目類型。這個編號必須與為資料來源登錄的結構定義中的物件定義名稱相對應。舉例來說，如果資料來源的結構定義中含有名稱為「document」的物件定義，則該類型物件的項目索引要求應將 objectType 設為「document」。長度上限為 256 個半形字元。
createTime

string (Timestamp format)

項目在原始碼存放區中建立的時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

來源存放區中項目上次修改的時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
interactions[]

object (Interaction)

項目的互動清單。互動會用於改善 query.search 的品質，但不會向使用者顯示。元素數量上限為 1000 個。
contentLanguage

string

商品的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。長度上限為 32 個字元。
mimeType

string

原始碼存放區中 ItemContent.content 的原始 MIME 類型。長度上限為 256 個半形字元。
searchQualityMetadata

object (SearchQualityMetadata)

商品的其他搜尋品質中繼資料
keywords[]

string

應符合商品的其他關鍵字或詞組。會在內部用於使用者產生的內容。元素數量上限為 100 個。長度上限為 8,192 個字元。
hash

string

API 呼叫端提供的雜湊值。這可與 items.push 方法搭配使用，計算修改後的狀態。長度上限為 2,048 個半形字元。
contextAttributes[]

object (ContextAttribute)

一組與項目相關聯的已命名屬性。這可用於根據要求中的情境影響商品排名。元素數量上限為 10 個。

互動技術

代表使用者和項目之間的互動。

JSON 表示法 
{
  "type": enum (Interaction.InteractionType),
  "principal": {
    object (Principal)
  },
  "interactionTime": string
}
欄位
type

enum (Interaction.InteractionType)
principal

object (Principal)

對項目執行動作的使用者。
interactionTime

string (Timestamp format)

使用者處理項目的時間。如果單一使用者執行了同一類型的多項動作，系統只會記錄最近的動作。

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

Interaction.InteractionType

使用者對項目進行的活動類型。

列舉
UNSPECIFIED 無效的值。
VIEW 此互動代表使用者檢視了項目。
EDIT 這項互動表示使用者已編輯項目。

SearchQualityMetadata

項目的其他搜尋品質中繼資料。

JSON 表示法 
{
  "quality": number
}
欄位
quality

number

表示項目品質的指標，用於影響搜尋品質。值應介於 0.0 至 1.0 (品質最高) 之間。預設值為 0.0。

ContextAttribute

與項目相關聯的具名屬性，可根據要求中的背景資訊影響商品排名。

JSON 表示法 
{
  "name": string,
  "values": [
    string
  ]
}
欄位
name

string

屬性的名稱。這個欄位不得留空。長度上限為 32 個字元。名稱開頭必須是英文字母，後面只能包含英文字母 (A 至 Z、a 至 z) 或數字 (0 到 9)。名稱會先經過正規化 (小寫)，然後再進行比對。
values[]

string

屬性的文字值。元素數量上限為 10 個。陣列中的元素長度上限為 32 個字元。系統會先對這個值進行正規化 (小寫) 比對，然後再進行比對。

ItemStructuredData

項目可用的結構化資料欄位。

JSON 表示法 
{
  "object": {
    object (StructuredDataObject)
  },
  "hash": string
}
欄位
object

object (StructuredDataObject)

結構化資料物件應符合資料來源結構定義中已註冊的物件定義。
hash

string

API 呼叫端提供的雜湊值。這可與 items.push 方法搭配使用，計算修改後的狀態。長度上限為 2,048 個半形字元。

StructuredDataObject

由具名屬性組成的結構化資料物件。

JSON 表示法 
{
  "properties": [
    {
      object (NamedProperty)
    }
  ]
}
欄位
properties[]

object (NamedProperty)

物件的屬性。元素數量上限為 1000 個。

NamedProperty

結構化資料的輸入名稱/值組合。值的類型應與 objectType 物件定義中 name 屬性的註冊類型相同。

JSON 表示法 
{
  "name": string,

  // Union field value can be only one of the following:
  "integerValues": {
    object (NamedProperty.IntegerValues)
  },
  "doubleValues": {
    object (NamedProperty.DoubleValues)
  },
  "timestampValues": {
    object (NamedProperty.TimestampValues)
  },
  "booleanValue": boolean,
  "objectValues": {
    object (NamedProperty.ObjectValues)
  },
  "enumValues": {
    object (NamedProperty.EnumValues)
  },
  "dateValues": {
    object (NamedProperty.DateValues)
  },
  "textValues": {
    object (NamedProperty.TextValues)
  },
  "htmlValues": {
    object (NamedProperty.HtmlValues)
  }
  // End of list of possible types for union field value.
}
欄位
name

string

屬性的名稱。這個名稱必須與您在結構定義中註冊物件定義的屬性名稱對應。這項屬性的長度上限為 256 個字元。
聯集欄位 value。具名屬性的值。請注意，屬性只能保留一種類型的值。value 只能是下列其中一項：
integerValues

object (NamedProperty.IntegerValues)
doubleValues

object (NamedProperty.DoubleValues)
timestampValues

object (NamedProperty.TimestampValues)
booleanValue

boolean
objectValues

object (NamedProperty.ObjectValues)
enumValues

object (NamedProperty.EnumValues)
dateValues

object (NamedProperty.DateValues)
textValues

object (NamedProperty.TextValues)
htmlValues

object (NamedProperty.HtmlValues)

NamedProperty.IntegerValues

整數值清單。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[]

string (int64 format)

NamedProperty.DoubleValues

雙值清單。

JSON 表示法 
{
  "values": [
    number
  ]
}
欄位
values[]

number

NamedProperty.TimestampValues

時間戳記值清單。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[]

string (Timestamp format)

RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

NamedProperty.ObjectValues

物件值清單。

JSON 表示法 
{
  "values": [
    {
      object (StructuredDataObject)
    }
  ]
}
欄位
values[]

object (StructuredDataObject)

NamedProperty.EnumValues

列舉值清單。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[]

string

字串值的長度上限為 32 個字元。

NamedProperty.DateValues

日期值清單。

JSON 表示法 
{
  "values": [
    {
      object (Date)
    }
  ]
}
欄位
values[]

object (Date)

NamedProperty.TextValues

文字值清單。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[]

string

文字值的長度上限為 2,048 個字元。

NamedProperty.HtmlValues

HTML 值清單。

JSON 表示法 
{
  "values": [
    string
  ]
}
欄位
values[]

string

HTML 值的長度上限為 2,048 個字元。

ItemContent

要由 Cloud Search 建立索引及顯示的項目內容。inlineContent 只能使用 UTF-8 編碼字串。如果內容是上傳而非二進位格式，則必須採用 UTF-8 編碼。

JSON 表示法 
{
  "contentFormat": enum (ItemContent.ContentFormat),
  "hash": string,

  // Union field content can be only one of the following:
  "inlineContent": string,
  "contentDataRef": {
    object (UploadItemRef)
  }
  // End of list of possible types for union field content.
}
欄位
contentFormat

enum (ItemContent.ContentFormat)
hash

string

由 API 用戶端針對內容計算並提供的雜湊資訊。可與 items.push 方法搭配使用，計算修改後的狀態。長度上限為 2,048 個半形字元。

聯集欄位 content。

content 只能採用下列其中一種設定：
inlineContent

string (bytes format)

在更新方法中內嵌提供的內容。長度上限為 102400 個位元組 (100 KiB)。

Base64 編碼的字串。
contentDataRef

object (UploadItemRef)

透過寫入方法上傳先前上傳內容的參考 ID。

ItemContent.ContentFormat

內容的格式。如果採用 RAW 格式，內容應採用 mimeType 指定的格式。

列舉
UNSPECIFIED 無效的值。
HTML 內容格式為 HTML。
TEXT contentFormat 是任意文字的格式。
RAW contentFormat 是原始位元組，

UploadItemRef

代表上傳工作階段參考資料。這個參考檔案是透過 upload method 建立。這個參考檔案在建立後的 30 天內有效。更新項目內容可能會透過「contentDataRef」參照上傳的內容。

JSON 表示法 
{
  "name": string
}
欄位
name

string

內容參照的名稱。長度上限為 2,048 個半形字元。

ItemStatus

其中包含項目狀態和任何錯誤。

JSON 表示法 
{
  "code": enum (ItemStatus.Code),
  "processingErrors": [
    {
      object (ProcessingError)
    }
  ],
  "repositoryErrors": [
    {
      object (RepositoryError)
    }
  ]
}
欄位
code

enum (ItemStatus.Code)

狀態碼。
processingErrors[]

object (ProcessingError)

如果項目處於「ERROR」狀態，請提供錯誤詳細資料。
repositoryErrors[]

object (RepositoryError)

連接器回報的存放區錯誤。

ProcessingError

JSON 表示法 
{
  "code": enum (ProcessingErrorCode),
  "errorMessage": string,
  "fieldViolations": [
    {
      object (FieldViolation)
    }
  ]
}
欄位
code

enum (ProcessingErrorCode)

指出錯誤性質的錯誤代碼。
errorMessage

string

錯誤的說明。
fieldViolations[]

object (FieldViolation)

如果項目欄位無效，這個欄位會包含驗證錯誤的詳細資料。

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

string

違規欄位路徑。
description

string

錯誤的說明。

RepositoryError

連接器與來源存放區通訊時發生錯誤。

JSON 表示法 
{
  "type": enum (RepositoryError.Type),
  "httpStatusCode": integer,
  "errorMessage": string
}
欄位
type

enum (RepositoryError.Type)

錯誤類型。
httpStatusCode

integer

錯誤代碼。符合 HTTP 狀態碼的定義。
errorMessage

string

說明錯誤的訊息。訊息的長度上限為 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 相同。

方法

delete

 刪除指定資源名稱的 Item resource。

deleteQueueItems

 刪除佇列中的所有項目。

get

 依項目名稱取得 Item resource。

index

 更新 Item ACL、中繼資料和內容。

list

 列出 Item resources 的所有或子集。

poll

 針對索引佇列中的未保留項目進行輪詢，並將某項集合標示為保留，從優先順序最高的 ItemStatus 項目開始。

push

 將項目推送到佇列，以便稍後輪詢及更新。

unreserve

 取消保留佇列中的所有項目，讓所有項目都符合受輪詢的資格。

upload

 建立上傳項目內容的上傳工作階段。