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)

此項目的存取控制清單。
metadata

object (ItemMetadata)

中繼資料資訊。
structuredData

object (ItemStructuredData)

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

object (ItemContent)

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

string (bytes format)

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

Cloud Search 索引服務不會為任何已排入佇列的項目建立索引，或刪除這些項目，除非這些項目的版本值小於或等於目前已建立索引的項目的版本。這個欄位的長度上限為 1024 位元組。

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

Base64 編碼字串。
status

object (ItemStatus)

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

string

項目所屬的佇列。長度上限為 100 個半形字元。
payload

string (bytes format)

其他狀態連接器可以為此項目儲存狀態。長度上限為 10000 個位元組。

Base64 編碼字串。
itemType

enum (Item.ItemType)

此項目的類型。

ItemAcl

項目的存取控制清單資訊。詳情請參閱「地圖 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

這個主要對象是使用外部身分識別的使用者。name 欄位必須使用以下格式指定使用者資源名稱：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

項目的標題。如果提供此值，系統會將其設為查詢結果的顯示標題。長度上限為 2048 個半形字元。
sourceRepositoryUrl

string

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

string

此項目的容器名稱。刪除容器項目後，系統會自動刪除該項目。注意：ACL 不會從容器項目繼承。如要為項目提供 ACL 繼承功能，請使用 inheritAclFrom 欄位。長度上限為 1536 個半形字元。
objectType

string

商品類型。這個值應與資料來源註冊的結構定義中物件定義的名稱相符。舉例來說，如果資料來源的結構定義包含名稱為「document」的物件定義，則該類型物件的項目索引要求應將 objectType 設為「document」。長度上限為 256 個半形字元。
createTime

string (Timestamp format)

在來源存放區中建立項目的時間。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

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

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："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 個。長度上限為 8192 個半形字元。
hash

string

API 呼叫端提供的雜湊值。您可以搭配 items.push 方法使用此方法，藉此計算修改狀態。長度上限為 2048 個半形字元。
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」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："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 方法使用此方法，藉此計算修改狀態。長度上限為 2048 個半形字元。

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」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。例如："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

文字值的長度上限為 2048 個半形字元。

NamedProperty.HtmlValues

html 值清單。

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

string

html 值的長度上限為 2048 個半形字元。

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 方法使用，用於計算修改後的狀態。長度上限為 2048 個半形字元。

聯集欄位 content。

content 只能是下列其中一個：
inlineContent

string (bytes format)

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

Base64 編碼字串。
contentDataRef

object (UploadItemRef)

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

ItemContent.ContentFormat

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

列舉
UNSPECIFIED 無效的值。
HTML contentFormat 為 HTML。
TEXT contentFormat 是自由文字。
RAW contentFormat 是原始位元組。

UploadItemRef

代表上傳工作階段參照。這個參照是透過 upload method 建立。這個參照資料的有效期限為建立後的 30 天。更新項目內容時，可能會透過 contentDataRef 參照這項上傳的內容。

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

string

內容參考資料的名稱。長度上限為 2048 個半形字元。

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、中繼資料或內容格式錯誤或處於無效狀態。FieldViolations 包含問題所在位置的詳細資料。
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

說明錯誤的訊息。訊息的長度上限為 8192 個半形字元。

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

 建立上傳工作階段，用於上傳項目內容。