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/{source_id}/items/{itemId}

这是必填字段。长度上限为 1536 个字符。

acl

object (ItemAcl)

此项目的访问控制列表。

metadata

object (ItemMetadata)

元数据信息。

structuredData

object (ItemStructuredData)

商品的结构化数据应符合数据源架构中的注册对象定义。

content

object (ItemContent)

要编入索引并使文本可供搜索的项内容。

version

string (bytes format)

必需。索引系统会将字节版本以数据源字符串的形式存储,并使用词法排序将索引中的 Item 版本与已加入队列的项的版本进行比较。

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.Acl 继承

ACL 继承的类型。

枚举
NOT_APPLICABLE 此项不继承 ACL 时的默认值。当 inheritAclFrom 为空时,请使用 NOT_APPLICABLE。没有 ACL 继承设置的项仍然可以由其自己的 readersdeniedReaders 字段提供 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/{source_id}/users/{ID}

groupResourceName

string

此主帐号是使用外部身份识别的群组。名称字段必须使用以下格式指定群组资源名称:identitysources/{source_id}/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.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 世界协调时间 (UTC)(即“祖鲁时”)格式,分辨率为纳秒级,最多包含九个小数位。示例:"2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"

Interaction.InteractionType

用户针对相应项目执行的活动类型。

枚举
UNSPECIFIED 值无效。
VIEW 此互动表示用户查看了相应商品。
EDIT 此互动表示用户已修改相应项目。

搜索质量元数据

商品的其他搜索质量元数据。

JSON 表示法
{
  "quality": number
}
字段
quality

number

商品质量的指示,用于影响搜索质量。该值应介于 0.0(最低质量)和 1.0(最高质量)之间。默认值为 0.0。

上下文属性

与商品相关联的已命名属性,可用于根据请求中的情境影响商品的排名。

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 个字符。

结构化数据对象

由命名的属性组成的结构化数据对象。

JSON 表示法
{
  "properties": [
    {
      object (NamedProperty)
    }
  ]
}
字段
properties[]

object (NamedProperty)

对象的属性。元素数上限为 1000。

已命名属性

结构化数据的类型化值对。该值的类型应与对象定义 objectTypename 属性的注册类型相同。

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 个字符。

内容内容

由 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)

连接器报告的代码库错误。

处理错误

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

enum (ProcessingErrorCode)

指示错误性质的错误代码。

errorMessage

string

错误的说明。

fieldViolations[]

object (FieldViolation)

如果商品字段无效,此字段包含有关验证错误的详细信息。

处理中的错误代码

用于指示 Cloud Search 服务器处理内容时遇到的错误的代码。一个商品可能包含多个处理错误。

枚举
PROCESSING_ERROR_CODE_UNSPECIFIED 仅限输入值。在“项目”中使用此值。
MALFORMED_REQUEST 商品的 ACL、元数据或内容格式不正确,或处于无效状态。FieldViolations 包含问题所在位置的更多详细信息。
UNSUPPORTED_CONTENT_FORMAT 计数格式不受支持。
INDIRECT_BROKEN_ACL 由于继承 ACL 损坏的其他项或包含后代未映射的组而导致 ACL 信息不完整。
ACL_CYCLE ACL 继承图形成了一个循环。

字段违规

JSON 表示法
{
  "field": string,
  "description": string
}
字段
field

string

违规的字段路径。

description

string

错误的说明。

代码库错误

连接器与源代码库进行通信时出错。

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 仅出于提供信息的目的编入索引的内容。这些内容无法在 containerNameinheritAclFrom 字段中引用。
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

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