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 索引就不會為這些項目建立索引或刪除。這個欄位的長度上限為 1,024 個位元組。

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

Base64 編碼字串。
status

object (ItemStatus)

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

string

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

string (bytes format)

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

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

這個主體是透過外部身分識別的使用者。名稱欄位必須以下列格式指定使用者資源名稱：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 結果的顯示標題。長度上限為 2048 個半形字元。
sourceRepositoryUrl

string

連結至提供資料的原始碼存放區。搜尋結果會將這個連結套用到標題。空白字元或特殊字元可能會導致 Cloud Seach 結果連結觸發重新導向通知。要避免這種情況，請對網址進行編碼長度上限為 2048 個半形字元。
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 方法搭配使用，計算修改狀態。長度上限為 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」的時間戳記格式，解析度為奈秒，且最多 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 方法搭配使用，計算修改狀態。長度上限為 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」的時間戳記格式，解析度為奈秒，且最多 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

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

NamedProperty.HtmlValues

HTML 值清單。

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

string

HTML 值的長度上限為 2048 個字元。

ItemContent

由 Cloud Search 建立索引及顯示的項目內容。只允許使用 UTF-8 編碼字串做為 inlineContent。如果內容上傳並非二進位，則必須採用 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)

因項目處於「錯誤」狀態時的錯誤詳情。
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 違規事項包含問題所在的詳細資訊。
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

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