REST Resource: indexing.datasources.items

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

リソース: アイテム

検索インデックス内の 1 つのアイテム(ファイル、フォルダ、データベース レコードなど)を表します。

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}

これは必須項目です。最大長は 1,536 文字です。

acl

object (ItemAcl)

このアイテムのアクセス制御リスト。

metadata

object (ItemMetadata)

メタデータ情報。

structuredData

object (ItemStructuredData)

データソースのスキーマに登録されているオブジェクト定義に準拠するアイテムの構造化データ。

content

object (ItemContent)

インデックス登録してテキスト検索を可能にするアイテムのコンテンツ。

version

string (bytes format)

必須。インデックス登録システムは、データソースのバージョンをバイト文字列として保存し、インデックス内のアイテム バージョンとキューに登録されたアイテムのバージョンを、語彙の順序付けを使用して比較します。

Cloud Search Indexing は、現在インデックス登録されているアイテムのバージョン以下のバージョン値を持つキューに登録されたアイテムはインデックス登録または削除しません。このフィールドの最大長は 1,024 バイトです。

アイテムのバージョンが削除プロセスに与える影響については、手動削除後のリビジョンの処理をご覧ください。

Base64 でエンコードされた文字列。

status

object (ItemStatus)

商品アイテムのステータス。出力のみのフィールド。

queue

string

このアイテムが属するキュー。最大長は 100 文字です。

payload

string (bytes format)

このアイテムの追加の状態コネクタを格納できます。最大長は 10,000 バイトです。

Base64 でエンコードされた文字列。

itemType

enum (Item.ItemType)

このアイテムのタイプ。

商品アイテム ACL

アイテムのアクセス制御リスト情報。詳しくは、地図の ACL をご覧ください。

JSON 表現
{
  "inheritAclFrom": string,
  "aclInheritanceType": enum (ItemAcl.AclInheritanceType),
  "readers": [
    {
      object (Principal)
    }
  ],
  "deniedReaders": [
    {
      object (Principal)
    }
  ],
  "owners": [
    {
      object (Principal)
    }
  ]
}
フィールド
inheritAclFrom

string

アクセス権限リスト(ACL)を継承するアイテムの名前。注: ACL の継承は子アイテムへのアクセス権のみを提供し、構造関係は定義しません。また、大規模なアイテム グループを削除するための便利な方法も提供しません。ACL の親をインデックスから削除すると、inheritAclFrom フィールドの親を参照する子アイテムのアクセス権限のみが変更されます。アイテムはまだインデックスに登録されていますが、検索結果に表示されません。一方、コンテナ アイテムを削除すると、containerName フィールドを介してコンテナを参照するすべてのアイテムも削除されます。このフィールドの最大長は 1,536 文字です。

aclInheritanceType

enum (ItemAcl.AclInheritanceType)

アイテムが親から ACL を継承する際に適用されるアクセスルールのタイプを設定します。これは、常に inheritAclFrom フィールドと連動して設定する必要があります。また、inheritAclFrom フィールドが設定されている場合、このフィールドは有効な AclInheritanceType に設定する必要があります。

readers[]

object (Principal)

検索結果でアイテムの表示が許可されているプリンシパルのリスト。別のアイテム(virtual containers など)から権限を継承する場合や、アイテムを表示することが想定されていない場合。要素の最大数は 1,000 です。

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

このプリンシパルは、外部 ID を使用して識別されるユーザーです。名前フィールドでは、ユーザー リソース名を次の形式で指定する必要があります。identitysources/{source_id}/users/{ID}

groupResourceName

string

このプリンシパルは、外部 ID を使用して識別されるグループです。名前フィールドには、グループ リソース名を次の形式で指定する必要があります。identitysources/{source_id}/groups/{ID}

アイテムのメタデータ

アイテムで利用可能なメタデータ フィールド。

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 結果の表示タイトルになります。最大長は 2,048 文字です。

sourceRepositoryUrl

string

データを提供するソース リポジトリへのリンク。検索結果はすべて、このリンクをタイトルに適用します。空白文字や特殊文字を使用すると、Cloud Seach の結果リンクによってリダイレクト通知がトリガーされることがあります。この問題を回避するには、URL をエンコードします。最大長は 2,048 文字です。

containerName

string

このアイテムのコンテナの名前。コンテナ アイテムを削除すると、このアイテムは自動的に削除されます。注: ACL はコンテナ アイテムから継承されません。アイテムに対して ACL の継承を指定するには、inheritAclFrom フィールドを使用します。最大長は 1,536 文字です。

objectType

string

商品アイテムのタイプ。これは、データソースに登録されたスキーマ内のオブジェクト定義の名前に対応している必要があります。たとえば、データソースのスキーマに 'document' という名前のオブジェクト定義が含まれている場合、そのタイプのオブジェクトのアイテム インデックス リクエストは、objectType を 'document' に設定します。最大長は 256 文字です。

createTime

string (Timestamp format)

ソース リポジトリでアイテムが作成された時刻。

RFC3339 UTC の Zulu 形式のタイムスタンプ。ナノ秒単位で、小数点以下は 9 桁までとなります。(例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z")。

updateTime

string (Timestamp format)

ソース リポジトリ内のアイテムの最終更新日時。

RFC3339 UTC の Zulu 形式のタイムスタンプ。ナノ秒単位で、小数点以下は 9 桁までとなります。(例: "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z")。

interactions[]

object (Interaction)

アイテムのインタラクションのリスト。操作は query.search の品質向上に活用されますが、エンドユーザーには表示されません。要素の最大数は 1,000 です。

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 です。最大長は 8,192 文字です。

hash

string

API 呼び出し元から提供されるハッシュ値。これを items.push メソッドで使用して、変更状態を計算できます。最大長は 2,048 文字です。

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 の Zulu 形式のタイムスタンプ。ナノ秒単位で、小数点以下は 9 桁までとなります。(例: "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 です。

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 メソッドで使用して、変更状態を計算できます。最大長は 2,048 文字です。

構造化データ オブジェクト

名前付きプロパティで構成される構造化データ オブジェクト。

JSON 表現
{
  "properties": [
    {
      object (NamedProperty)
    }
  ]
}
フィールド
properties[]

object (NamedProperty)

オブジェクトのプロパティ。要素の最大数は 1,000 です。

名前付きプロパティ

構造化データのタイプと値のペア。値の型は、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。名前付きプロパティの値。プロパティには、1 つの型の値のみを含めることができます。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

double 値のリスト。

JSON 表現
{
  "values": [
    number
  ]
}
フィールド
values[]

number

NamedProperty.TimestampValues

タイムスタンプ値のリスト。

JSON 表現
{
  "values": [
    string
  ]
}
フィールド
values[]

string (Timestamp format)

RFC3339 UTC の Zulu 形式のタイムスタンプ。ナノ秒単位で、小数点以下は 9 桁までとなります。(例: "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

テキスト値の最大長は 2,048 文字です。

NamedProperty.HTMLValues

HTML 値のリスト。

JSON 表現
{
  "values": [
    string
  ]
}
フィールド
values[]

string

HTML 値の最大長は 2,048 文字です。

アイテム コンテンツ

Cloud Search でインデックス登録されて検索結果に表示されるアイテムのコンテンツ。inlineContent として使用できるのは、UTF-8 でエンコードされた文字列のみです。コンテンツがアップロードされていて、バイナリでない場合は、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 メソッドで使用して、変更された状態を計算できます。最大長は 2,048 文字です。

共用体フィールド content

content は次のいずれかになります。

inlineContent

string (bytes format)

update メソッド内でインラインで提供されるコンテンツ。最大長は 102,400 バイト(100 KiB)です。

Base64 でエンコードされた文字列。

contentDataRef

object (UploadItemRef)

書き込みメソッドを使用して、以前にアップロードしたコンテンツの参照 ID をアップロードします。

ItemContent.ContentFormat

コンテンツの形式。RAW 形式の場合、mimeType で指定した形式にする必要があります。

列挙型
UNSPECIFIED 値が無効です。
HTML contentFormat は HTML です。
TEXT contentFormat は自由形式のテキストです。
RAW contentFormat は RAW バイトです。

UploadItemRef

アップロード セッション参照を表します。この参照は upload method を介して作成されています。この参照は、作成後 30 日間有効です。アイテム コンテンツの更新は、contentDataRef を介してアップロードされたコンテンツを参照する場合があります。

JSON 表現
{
  "name": string
}
フィールド
name

string

コンテンツ参照の名前。最大長は 2,048 文字です。

アイテム ステータス

これには、アイテムのステータスとエラーが含まれます。

JSON 表現
{
  "code": enum (ItemStatus.Code),
  "processingErrors": [
    {
      object (ProcessingError)
    }
  ],
  "repositoryErrors": [
    {
      object (RepositoryError)
    }
  ]
}
フィールド
code

enum (ItemStatus.Code)

ステータス コード。

processingErrors[]

object (ProcessingError)

項目がエラー状態の場合のエラーの詳細。

repositoryErrors[]

object (RepositoryError)

コネクタによって報告されたリポジトリ エラー。

処理エラー

JSON 表現
{
  "code": enum (ProcessingErrorCode),
  "errorMessage": string,
  "fieldViolations": [
    {
      object (FieldViolation)
    }
  ]
}
フィールド
code

enum (ProcessingErrorCode)

エラーの性質を示すエラーコード。

errorMessage

string

エラーの説明。

fieldViolations[]

object (FieldViolation)

アイテム フィールドが無効である場合、このフィールドには検証エラーについての詳細が含まれます。

ProcessingErrorCode

Cloud Search サーバーでアイテムの処理中に発生したエラーを示すコード。1 つの商品アイテムに複数の処理エラーが含まれることがあります。

列挙型
PROCESSING_ERROR_CODE_UNSPECIFIED 入力専用の値です。この値は商品アイテムで使用してください。
MALFORMED_REQUEST アイテムの ACL、メタデータ、コンテンツの形式が正しくないか、無効です。Field 違反には、問題のある場所の詳細が記載されています。
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

エラーを説明するメッセージ。メッセージの最大長は 8,192 文字です。

RepositoryError.Type

リポジトリとの通信に関する問題のエラーコードのリスト。

列挙型
UNKNOWN 不明なエラーです。
NETWORK_ERROR 不明なホストまたはアクセスできないホストです。
DNS_ERROR DNS の問題(DNS サーバーが応答しないなど)。
CONNECTION_ERROR リポジトリ サーバーに接続できません。
AUTHENTICATION_ERROR 認証情報が正しくないため認証できませんでした。
AUTHORIZATION_ERROR サービス アカウントは、このリポジトリに対して承認されていません。
SERVER_ERROR リポジトリ サーバーエラー。
QUOTA_EXCEEDED 割り当てを超過しています。
SERVICE_UNAVAILABLE サーバーが一時的に利用できなくなっています。
CLIENT_ERROR クライアント関連のエラー(コネクタからリポジトリ サーバーへの無効なリクエストなど)。

アイテムタイプ

列挙型
UNSPECIFIED
CONTENT_ITEM 情報提供のみを目的としてインデックスに登録されたアイテム。これらの項目は containerNameinheritAclFrom フィールドで参照できません。
CONTAINER_ITEM インデックス登録され、他のアイテムを ACL で提供したり、他のアイテムを格納したりすることを意図したアイテム。
VIRTUAL_CONTAINER_ITEM インデックス登録されていないが、CONTAINER_ITEM と同じ用途のアイテム。

Methods

delete

指定されたリソース名の Item resource を削除します。

deleteQueueItems

キュー内のすべてのアイテムを削除します。

get

アイテム名別に Item resource を取得します。

index

Item ACL、メタデータ、コンテンツを更新します。

list

Item resources のすべてまたはサブセットを一覧表示します。

poll

インデックス キューの予約されていないアイテムをポーリングし、セットを予約済みとしてマークします。優先度が最も高い ItemStatus から最も古いタイムスタンプを持つアイテムから始めます。

push

後でポーリングと更新を行うために、アイテムをキューに push します。

unreserve

すべてのアイテムをキューから予約解除します。これらすべてのアイテムはポーリングの対象になります。

upload

アイテム コンテンツをアップロードするためのアップロード セッションを作成します。