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 Indexing 不会将版本值小于或等于当前编入索引项的版本的任何排队项编入索引或删除。此字段的长度上限为 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

此主账号是使用外部身份标识的用户。名称字段必须按以下格式指定用户资源名称：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 世界协调时间 (UTC)（即“祖鲁时”）格式，具有纳秒级分辨率，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

该项在源代码库中最后一次修改的时间。

时间戳，采用 RFC3339 世界协调时间 (UTC)（即“祖鲁时”）格式，具有纳秒级分辨率，最多包含九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
interactions[]

object (Interaction)

该项的互动列表。互动用于提高 query.搜索质量，但不会向最终用户显示。元素数量上限为 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 世界协调时间 (UTC)（即“祖鲁时”）格式，具有纳秒级分辨率，最多包含九个小数位。示例："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 世界协调时间 (UTC)（即“祖鲁时”）格式，具有纳秒级分辨率，最多包含九个小数位。示例："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)

在 update 方法中内嵌提供的内容。最大长度为 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、元数据或内容格式不正确或无效。FieldBounds 包含有关问题所在位置的更多详细信息。
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

 创建用于上传内容内容的上传会话。