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)

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

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 继承功能的内容仍然可以通过自己的 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)

此主帐号是 G Suite 用户、群组或网域。

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

商品的名称。如果提供,则会显示查询的搜索结果的标题。长度上限为 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)

该项的互动列表。互动次数可用于提高查询质量,但不会向最终用户显示。元素数量上限为 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。

已命名属性

结构化数据的类型化名称-值对。值的类型应与 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 个字符。

内容内容

要编入索引并由 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 是原始字节。

上传商品引用

表示上传会话参考。此引用通过 upload method 创建。此参考文件的有效期为 30 天。商品内容更新时,可能会通过 contentDataRef 引用这项上传的内容。

JSON 表示法
{
  "name": string
}
字段
name

string

内容引用的名称。长度上限为 2048 个字符。

商品状态

其中包含内容的状态和任何错误。

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

创建上传项内容的上传会话。