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)

在源代码库中创建相应内容的时间。

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

内容在源代码库中的上次修改时间。

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
interactions[]

object (Interaction)

商品的互动列表。互动数据用于提高搜索质量，但不会向最终用户显示。元素数量上限为 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)

用户对相应项执行操作的时间。如果单个用户存在多项相同类型的操作，系统只会记录最近一次的操作。

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

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)

采用 RFC 3339 标准，生成的输出将始终在末尾带 Z，并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

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)

如果商品处于 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 仅输入值。在“Items”中使用此值。
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

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