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.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 这种互动表示用户修改了项目。

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、元数据或内容格式不正确或处于无效状态。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

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