REST Resource: indexing.datasources.items

Resource: Item

Represents a single object that is an item in the search index, such as a file, folder, or a database record.

JSON representation 
{
  "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)
}
Fields
name

string

The name of the Item. Format: datasources/{sourceId}/items/{itemId}

This is a required field. The maximum length is 1536 characters.
acl

object (ItemAcl)

Access control list for this item.
metadata

object (ItemMetadata)

The metadata information.
structuredData

object (ItemStructuredData)

The structured data for the item that should conform to a registered object definition in the schema for the data source.
content

object (ItemContent)

Item content to be indexed and made text searchable.
version

string (bytes format)

Required. The indexing system stores the version from the datasource as a byte string and compares the Item version in the index to the version of the queued Item using lexical ordering.

Cloud Search Indexing won't index or delete any queued item with a version value that is less than or equal to the version of the currently indexed item. The maximum length for this field is 1024 bytes.

For information on how item version affects the deletion process, refer to Handle revisions after manual deletes.

A base64-encoded string.
status

object (ItemStatus)

Status of the item. Output only field.
queue

string

Queue this item belongs to. The maximum length is 100 characters.
payload

string (bytes format)

Additional state connector can store for this item. The maximum length is 10000 bytes.

A base64-encoded string.
itemType

enum (Item.ItemType)

The type for this item.

ItemAcl

Access control list information for the item. For more information see Map ACLs.

JSON representation 
{
  "inheritAclFrom": string,
  "aclInheritanceType": enum (ItemAcl.AclInheritanceType),
  "readers": [
    {
      object (Principal)
    }
  ],
  "deniedReaders": [
    {
      object (Principal)
    }
  ],
  "owners": [
    {
      object (Principal)
    }
  ]
}
Fields
inheritAclFrom

string

The name of the item to inherit the Access Permission List (ACL) from. Note: ACL inheritance only provides access permissions to child items and does not define structural relationships, nor does it provide convenient ways to delete large groups of items. Deleting an ACL parent from the index only alters the access permissions of child items that reference the parent in the inheritAclFrom field. The item is still in the index, but may not visible in search results. By contrast, deletion of a container item also deletes all items that reference the container via the containerName field. The maximum length for this field is 1536 characters.
aclInheritanceType

enum (ItemAcl.AclInheritanceType)

Sets the type of access rules to apply when an item inherits its ACL from a parent. This should always be set in tandem with the inheritAclFrom field. Also, when the inheritAclFrom field is set, this field should be set to a valid AclInheritanceType.
readers[]

object (Principal)

List of principals who are allowed to see the item in search results. Optional if inheriting permissions from another item or if the item is not intended to be visible, such as virtual containers. The maximum number of elements is 1000.
deniedReaders[]

object (Principal)

List of principals who are explicitly denied access to the item in search results. While principals are denied access by default, use denied readers to handle exceptions and override the list allowed readers. The maximum number of elements is 100.
owners[]

object (Principal)

Optional. List of owners for the item. This field has no bearing on document access permissions. It does, however, offer a slight ranking boosts items where the querying user is an owner. The maximum number of elements is 5.

ItemAcl.AclInheritanceType

The types of ACL inheritance.

Enums
NOT_APPLICABLE The default value when this item does not inherit an ACL. Use NOT_APPLICABLE when inheritAclFrom is empty. An item without ACL inheritance can still have ACLs supplied by its own readers and deniedReaders fields.
CHILD_OVERRIDE During an authorization conflict, the ACL of the child item determines its read access.
PARENT_OVERRIDE During an authorization conflict, the ACL of the parent item specified in the inheritAclFrom field determines read access.
BOTH_PERMIT Access is granted only if this item and the parent item specified in the inheritAclFrom field both permit read access.

Principal

Reference to a user, group, or domain.

JSON representation 
{

  // 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.
}
Fields

Union field principal.

principal can be only one of the following:
gsuitePrincipal

object (GSuitePrincipal)

This principal is a Google Workspace user, group or domain.
userResourceName

string

This principal is a user identified using an external identity. The name field must specify the user resource name with this format: identitysources/{sourceId}/users/{ID}
groupResourceName

string

This principal is a group identified using an external identity. The name field must specify the group resource name with this format: identitysources/{sourceId}/groups/{ID}

ItemMetadata

Available metadata fields for the item.

JSON representation 
{
  "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)
    }
  ]
}
Fields
title

string

The title of the item. If given, this will be the displayed title of the query.search result. The maximum length is 2048 characters.
sourceRepositoryUrl

string

Link to the source repository serving the data. Seach results apply this link to the title. Whitespace or special characters may cause Cloud Seach result links to trigger a redirect notice; to avoid this, encode the URL. The maximum length is 2048 characters.
containerName

string

The name of the container for this item. Deletion of the container item leads to automatic deletion of this item. Note: ACLs are not inherited from a container item. To provide ACL inheritance for an item, use the inheritAclFrom field. The maximum length is 1536 characters.
objectType

string

The type of the item. This should correspond to the name of an object definition in the schema registered for the data source. For example, if the schema for the data source contains an object definition with name 'document', then item indexing requests for objects of that type should set objectType to 'document'. The maximum length is 256 characters.
createTime

string (Timestamp format)

The time when the item was created in the source repository.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

The time when the item was last modified in the source repository.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
interactions[]

object (Interaction)

A list of interactions for the item. Interactions are used to improve query.search quality, but are not exposed to end users. The maximum number of elements is 1000.
contentLanguage

string

The BCP-47 language code for the item, such as "en-US" or "sr-Latn". For more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. The maximum length is 32 characters.
mimeType

string

The original mime-type of ItemContent.content in the source repository. The maximum length is 256 characters.
searchQualityMetadata

object (SearchQualityMetadata)

Additional search quality metadata of the item
keywords[]

string

Additional keywords or phrases that should match the item. Used internally for user generated content. The maximum number of elements is 100. The maximum length is 8192 characters.
hash

string

Hashing value provided by the API caller. This can be used with the items.push method to calculate modified state. The maximum length is 2048 characters.
contextAttributes[]

object (ContextAttribute)

A set of named attributes associated with the item. This can be used for influencing the ranking of the item based on the context in the request. The maximum number of elements is 10.

Interaction

Represents an interaction between a user and an item.

JSON representation 
{
  "type": enum (Interaction.InteractionType),
  "principal": {
    object (Principal)
  },
  "interactionTime": string
}
Fields
type

enum (Interaction.InteractionType)
principal

object (Principal)

The user that acted on the item.
interactionTime

string (Timestamp format)

The time when the user acted on the item. If multiple actions of the same type exist for a single user, only the most recent action is recorded.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Interaction.InteractionType

The type of activity the user performed on the item.

Enums
UNSPECIFIED Invalid value.
VIEW This interaction indicates the user viewed the item.
EDIT This interaction indicates the user edited the item.

SearchQualityMetadata

Additional search quality metadata of the item.

JSON representation 
{
  "quality": number
}
Fields
quality

number

An indication of the quality of the item, used to influence search quality. value should be between 0.0 (lowest quality) and 1.0 (highest quality). The default value is 0.0.

ContextAttribute

A named attribute associated with an item which can be used for influencing the ranking of the item based on the context in the request.

JSON representation 
{
  "name": string,
  "values": [
    string
  ]
}
Fields
name

string

The name of the attribute. It should not be empty. The maximum length is 32 characters. The name must start with a letter and can only contain letters (A-Z, a-z) or numbers (0-9). The name will be normalized (lower-cased) before being matched.
values[]

string

Text values of the attribute. The maximum number of elements is 10. The maximum length of an element in the array is 32 characters. The value will be normalized (lower-cased) before being matched.

ItemStructuredData

Available structured data fields for the item.

JSON representation 
{
  "object": {
    object (StructuredDataObject)
  },
  "hash": string
}
Fields
object

object (StructuredDataObject)

The structured data object that should conform to a registered object definition in the schema for the data source.
hash

string

Hashing value provided by the API caller. This can be used with the items.push method to calculate modified state. The maximum length is 2048 characters.

StructuredDataObject

A structured data object consisting of named properties.

JSON representation 
{
  "properties": [
    {
      object (NamedProperty)
    }
  ]
}
Fields
properties[]

object (NamedProperty)

The properties for the object. The maximum number of elements is 1000.

NamedProperty

A typed name-value pair for structured data. The type of the value should be the same as the registered type for the name property in the object definition of objectType.

JSON representation 
{
  "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.
}
Fields
name

string

The name of the property. This name should correspond to the name of the property that was registered for object definition in the schema. The maximum allowable length for this property is 256 characters.
Union field value. The value(s) of the named property. Note that a property can only hold values of one type. 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)

NamedProperty.IntegerValues

List of integer values.

JSON representation 
{
  "values": [
    string
  ]
}
Fields
values[]

string (int64 format)

NamedProperty.DoubleValues

List of double values.

JSON representation 
{
  "values": [
    number
  ]
}
Fields
values[]

number

NamedProperty.TimestampValues

List of timestamp values.

JSON representation 
{
  "values": [
    string
  ]
}
Fields
values[]

string (Timestamp format)

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

NamedProperty.ObjectValues

List of object values.

JSON representation 
{
  "values": [
    {
      object (StructuredDataObject)
    }
  ]
}
Fields
values[]

object (StructuredDataObject)

NamedProperty.EnumValues

List of enum values.

JSON representation 
{
  "values": [
    string
  ]
}
Fields
values[]

string

The maximum allowable length for string values is 32 characters.

NamedProperty.DateValues

List of date values.

JSON representation 
{
  "values": [
    {
      object (Date)
    }
  ]
}
Fields
values[]

object (Date)

NamedProperty.TextValues

List of text values.

JSON representation 
{
  "values": [
    string
  ]
}
Fields
values[]

string

The maximum allowable length for text values is 2048 characters.

NamedProperty.HtmlValues

List of html values.

JSON representation 
{
  "values": [
    string
  ]
}
Fields
values[]

string

The maximum allowable length for html values is 2048 characters.

ItemContent

Content of an item to be indexed and surfaced by Cloud Search. Only UTF-8 encoded strings are allowed as inlineContent. If the content is uploaded and not binary, it must be UTF-8 encoded.

JSON representation 
{
  "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.
}
Fields
contentFormat

enum (ItemContent.ContentFormat)
hash

string

Hashing info calculated and provided by the API client for content. Can be used with the items.push method to calculate modified state. The maximum length is 2048 characters.

Union field content.

content can be only one of the following:
inlineContent

string (bytes format)

Content that is supplied inlined within the update method. The maximum length is 102400 bytes (100 KiB).

A base64-encoded string.
contentDataRef

object (UploadItemRef)

Upload reference ID of a previously uploaded content via write method.

ItemContent.ContentFormat

The format of the content. If the format is RAW the content should be in the format specified by mimeType.

Enums
UNSPECIFIED Invalid value.
HTML contentFormat is HTML.
TEXT contentFormat is free text.
RAW contentFormat is raw bytes.

UploadItemRef

Represents an upload session reference. This reference is created via upload method. This reference is valid for 30 days after its creation. Updating of item content may refer to this uploaded content via contentDataRef.

JSON representation 
{
  "name": string
}
Fields
name

string

The name of the content reference. The maximum length is 2048 characters.

ItemStatus

This contains item's status and any errors.

JSON representation 
{
  "code": enum (ItemStatus.Code),
  "processingErrors": [
    {
      object (ProcessingError)
    }
  ],
  "repositoryErrors": [
    {
      object (RepositoryError)
    }
  ]
}
Fields
code

enum (ItemStatus.Code)

Status code.
processingErrors[]

object (ProcessingError)

Error details in case the item is in ERROR state.
repositoryErrors[]

object (RepositoryError)

Repository error reported by connector.

ProcessingError

JSON representation 
{
  "code": enum (ProcessingErrorCode),
  "errorMessage": string,
  "fieldViolations": [
    {
      object (FieldViolation)
    }
  ]
}
Fields
code

enum (ProcessingErrorCode)

Error code indicating the nature of the error.
errorMessage

string

The description of the error.
fieldViolations[]

object (FieldViolation)

In case the item fields are invalid, this field contains the details about the validation errors.

ProcessingErrorCode

Codes for indicating the error encountered during the processing of items by the Cloud Search server. A single item may contain multiple processing errors.

Enums
PROCESSING_ERROR_CODE_UNSPECIFIED Input only value. Use this value in Items.
MALFORMED_REQUEST Item's ACL, metadata, or content is malformed or in invalid state. FieldViolations contains more details on where the problem is.
UNSUPPORTED_CONTENT_FORMAT Countent format is unsupported.
INDIRECT_BROKEN_ACL Items with incomplete ACL information due to inheriting other items with broken ACL or having groups with unmapped descendants.
ACL_CYCLE ACL inheritance graph formed a cycle.

FieldViolation

JSON representation 
{
  "field": string,
  "description": string
}
Fields
field

string

Path of field with violation.
description

string

The description of the error.

RepositoryError

Errors when the connector is communicating to the source repository.

JSON representation 
{
  "type": enum (RepositoryError.Type),
  "httpStatusCode": integer,
  "errorMessage": string
}
Fields
type

enum (RepositoryError.Type)

The type of error.
httpStatusCode

integer

Error codes. Matches the definition of HTTP status codes.
errorMessage

string

Message that describes the error. The maximum allowable length of the message is 8192 characters.

RepositoryError.Type

List of error codes for communication problems with the repository.

Enums
UNKNOWN Unknown error.
NETWORK_ERROR Unknown or unreachable host.
DNS_ERROR DNS problem, such as the DNS server is not responding.
CONNECTION_ERROR Cannot connect to the repository server.
AUTHENTICATION_ERROR Failed authentication due to incorrect credentials.
AUTHORIZATION_ERROR Service account is not authorized for the repository.
SERVER_ERROR Repository server error.
QUOTA_EXCEEDED Quota exceeded.
SERVICE_UNAVAILABLE Server temporarily unavailable.
CLIENT_ERROR Client-related error, such as an invalid request from the connector to the repository server.

Item.ItemType

Enums
UNSPECIFIED
CONTENT_ITEM An item that is indexed for the only purpose of serving information. These items cannot be referred in containerName or inheritAclFrom fields.
CONTAINER_ITEM An item that gets indexed and whose purpose is to supply other items with ACLs and/or contain other items.
VIRTUAL_CONTAINER_ITEM An item that does not get indexed, but otherwise has the same purpose as CONTAINER_ITEM.

Methods

delete

 Deletes Item resource for the specified resource name.

deleteQueueItems

 Deletes all items in a queue.

get

 Gets Item resource by item name.

index

 Updates Item ACL, metadata, and content.

list

 Lists all or a subset of Item resources.

poll

 Polls for unreserved items from the indexing queue and marks a set as reserved, starting with items that have the oldest timestamp from the highest priority ItemStatus.

push

 Pushes an item onto a queue for later polling and updating.

unreserve

 Unreserves all items from a queue, making them all eligible to be polled.

upload

 Creates an upload session for uploading item content.