汎用レコメンデーション データストアを作成する

データストアを作成して汎用レコメンデーションのデータを取り込むには、使用するソースのセクションに移動します。

ウェブサイトの URL

Console

Google Cloud コンソールを使用してデータストアを作成し、ウェブサイトからデータをインデックスに登録する手順は次のとおりです。

  1. Google Cloud コンソールで、[Agent Builder] ページに移動します。

    Agent Builder

  2. ナビゲーション メニューで [データストア] をクリックします。

  3. [新しいデータストア] をクリックします。

  4. [データソースを選択] ページで、[ウェブサイトのコンテンツ] を選択します。

  5. このデータストアでウェブサイトの高度なインデックス登録を有効にするかどうかを選択します。このオプションを後でオフにすることはできません。

    ウェブサイトの高度なインデックス登録では、検索の要約、フォローアップ付き検索、抽出回答などの追加機能が提供されます。高度なウェブサイト インデックス登録を使用すると、追加料金がかかります。また、インデックスに登録するウェブサイトのドメインの所有権を確認する必要があります。詳細については、ウェブサイトの高度なインデックス登録と料金をご覧ください。

  6. [追加するサイト] フィールドに、インデックスに登録するウェブサイトの URL を指定します。カンマ区切りを使用せずに、1 行に 1 つの URL を含めます。

  7. 省略可: [除外するサイト] フィールドに、アプリから除外するウェブサイトを入力します。

  8. [続行] をクリックします。

  9. データストアの名前を入力します。

  10. データストアのロケーションを選択します。ロケーションを選択するには、ウェブサイトの高度なインデックス登録をオンにする必要があります。

  11. [作成] をクリックします。Vertex AI Agent Builder によってデータストアが作成され、[データストア] ページにデータストアが表示されます。

  12. データストアに関する情報を表示するには、[名前] 列でデータストアの名前をクリックします。データストアのページが表示されます。

    [ウェブサイトの高度なインデックス登録] をオンにしている場合は、ドメインの所有権を確認するよう求める警告が表示されます。割り当て不足（指定したウェブサイトのページ数が、プロジェクトの「プロジェクトあたりのドキュメント数」の割り当てを超えている場合）は、割り当てのアップグレードを促す警告がさらに表示されます。次の手順では、ドメインの所有権を確認して割り当てをアップグレードする方法について説明します。

  13. ドメインの所有権を確認する手順は次のとおりです。

    1. [Google Search Console で確認] をクリックします。[Google Search Console へようこそ] ページが表示されます。
    2. 画面上の手順に沿って、ドメイン全体を確認する場合と、ドメインの一部である URL プレフィックスを確認する場合に応じて、ドメインまたは URL プレフィックスを確認します。詳しくは、Search Console ヘルプのサイトの所有権を確認するをご覧ください。
    3. ドメイン所有権の確認ワークフローが完了したら、[Agent Builder] ページに戻り、ナビゲーション メニューの [データストア] をクリックします。
    4. [名前] 列でデータストアの名前をクリックします。データストアのページが表示されます。
    5. [ステータスを更新] をクリックして、[ステータス] 列の値を更新します。 ウェブサイトの [ステータス] 列には、インデックス登録が進行中であることが示されます。
    6. すべてのウェブサイトのインデックス登録が開始されるまで、ドメインの所有権の確認が必要なウェブサイトごとにドメインの所有権の確認手順を繰り返します。URL の [ステータス] 列に [インデックス登録済み] と表示されている場合、その URL または URL パターンに対してウェブサイトのインデックス登録の高度な機能を使用できます。

  14. 割り当てをアップグレードする手順は次のとおりです。

    1. [割り当てをアップグレード] をクリックします。[Discovery Engine API] ペインが表示され、[割り当て] タブが選択されています。
    2. Google Cloud ドキュメントの割り当て上限の引き上げをリクエストするの手順に沿って操作します。増やす割り当ては [ドキュメントの数] です。
    3. 割り当て上限の引き上げリクエストを送信したら、[Agent Builder] ページに戻り、ナビゲーション メニューの [データストア] をクリックします。
    4. [名前] 列でデータストアの名前をクリックします。[ステータス] 列には、割り当てを超えたウェブサイトのインデックス作成が進行中であることが示されます。URL の [ステータス] 列に [インデックス登録済み] と表示されている場合、その URL または URL パターンに対してウェブサイトのインデックス登録の高度な機能を使用できます。

次のステップ

BigQuery

BigQuery からデータを取り込むには、次の手順でデータストアを作成し、Google Cloud コンソールまたは API を使用してデータを取り込みます。

データをインポートする前に、取り込むデータを準備します。

Console

Google Cloud コンソールを使用して BigQuery からデータを取り込む手順は次のとおりです。

  1. Google Cloud コンソールで、[Agent Builder] ページに移動します。

    Agent Builder

  2. [データストア] ページに移動します。

  3. [新しいデータストア] をクリックします。

  4. [タイプ] ページで、[BigQuery] を選択します。

  5. [BigQuery のパス] フィールドで [参照] をクリックし、取り込み用に準備したテーブルを選択して、[選択] をクリックします。 または、[BigQuery パス] フィールドにテーブルの場所を直接入力します。

  6. インポートするデータの種類を選択します。

  7. [続行] をクリックします。

  8. 構造化データを 1 回限りインポートする場合:

    1. フィールドをキー プロパティにマッピングします。

    2. スキーマに重要なフィールドが欠落している場合は、[新しいフィールドを追加] を使用して追加します。

      詳細については、自動検出と編集についてをご覧ください。

    3. [続行] をクリックします。

  9. データストアのリージョンを選択します。

  10. データストアの名前を入力します。

  11. [作成] をクリックします。

  12. データストアが作成されたことを確認するには、[データストア] ページに移動し、データストア名をクリックして、[データ] ページで詳細を表示します。

  13. 取り込みのステータスを確認するには、[データストア] ページに移動し、データストア名をクリックして、[データ] ページで詳細を表示します。[アクティビティ] タブのステータス列が [進行中] から [インポート完了] に変わると、取り込みが完了します。

    取り込みには、データのサイズに応じて、数分から数時間かかることがあります。

REST

コマンドラインを使用してデータストアを作成し、BigQuery からデータをインポートする手順は次のとおりです。

  1. データストアを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "GENERIC",
  "solutionTypes": ["SOLUTION_TYPE_RECOMMENDATION"]
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: 作成するレコメンデーション データストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
    • DATA_STORE_DISPLAY_NAME: 作成するレコメンデーション データストアの表示名。

  2. 省略可: 独自のスキーマを使用して構造化データをアップロードする場合は、スキーマを指定できます。スキーマを指定すると、通常はより良い結果が得られます。それ以外の場合、スキーマは自動検出されます。詳細については、スキーマを指定する、または自動検出するをご覧ください。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: レコメンデーション データストアの ID。

    • JSON_SCHEMA_OBJECT: JSON オブジェクトとしての JSON スキーマ。次に例を示します。

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  3. BigQuery からデータをインポートします。

    スキーマを定義した場合は、データがそのスキーマに準拠していることを確認します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
-d '{
  "bigquerySource": {
    "projectId": "PROJECT_ID",
    "datasetId":"DATASET_ID",
    "tableId": "TABLE_ID",
    "dataSchema": "DATA_SCHEMA",
  },
  "reconciliationMode": "RECONCILIATION_MODE",
  "autoGenerateIds": "AUTO_GENERATE_IDS",
  "idField": "ID_FIELD",
  "errorConfig": {
    "gcsPrefix": "ERROR_DIRECTORY"
  }
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: レコメンデーション データストアの ID。
    • DATASET_ID: BigQuery データセットの ID。
    • TABLE_ID: BigQuery テーブルの ID。
      • BigQuery テーブルが PROJECT_ID にない場合は、サービス アカウント service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com に BigQuery テーブルに対する「BigQuery データ閲覧者」権限を付与する必要があります。たとえば、ソース プロジェクト「123」から宛先プロジェクト「456」に BigQuery テーブルをインポートする場合は、プロジェクト「123」の BigQuery テーブルに service-456@gcp-sa-discoveryengine.iam.gserviceaccount.com 権限を付与します。
    • DATA_SCHEMA: 省略可。値は document および custom です。デフォルトは document です。
      • document: 使用する BigQuery テーブルは、取り込み用にデータを準備するで説明されているデフォルトの BigQuery スキーマに準拠している必要があります。各ドキュメントの ID を自分で定義し、すべてのデータを jsonData 文字列にラップできます。
      • custom: 任意の BigQuery テーブル スキーマが受け入れられ、インポートされた各ドキュメントの ID が Recommendations によって自動的に生成されます。
    • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ（例: gs://<your-gcs-bucket>/directory/import_errors）。Recommendations が一時ディレクトリを自動的に作成できるように、このフィールドを空のままにすることをおすすめします。
    • RECONCILIATION_MODE: 省略可。値は FULL および INCREMENTAL です。デフォルトは INCREMENTAL です。INCREMENTAL を指定すると、BigQuery からデータストアへのデータの増分更新が行われます。これにより、アップサート オペレーションが実行され、新しいドキュメントを追加し、既存のドキュメントを更新された同じ ID のドキュメントで置き換えます。FULL を指定すると、データストア内のドキュメントが完全に再ベース化されます。つまり、新規および更新されたドキュメントがデータストアに追加され、BigQuery にないドキュメントがデータストアから削除されます。FULL モードは、不要になったドキュメントを自動的に削除する場合に便利です。

    • AUTO_GENERATE_IDS: 省略可。ドキュメント ID を自動生成するかどうかを指定します。true に設定すると、ドキュメント ID はペイロードのハッシュに基づいて生成されます。生成されたドキュメント ID は、複数のインポートで整合性が維持されない場合があります。複数のインポートで ID を自動生成する場合は、ドキュメント ID の整合性を維持するために、reconciliationMode を FULL に設定することを強くおすすめします。

      autoGenerateIds は、bigquerySource.dataSchema が custom に設定されている場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。autoGenerateIds を指定しない場合、または false に設定しない場合は、idField を指定する必要があります。そうしないと、ドキュメントのインポートに失敗します。

    • ID_FIELD: 省略可。ドキュメント ID であるフィールドを指定します。BigQuery ソースファイルの場合、idField は、ドキュメント ID を含む BigQuery テーブルの列の名前を示します。

      idField は、（1）bigquerySource.dataSchema が custom に設定されていること、（2）auto_generate_ids が false に設定されているか、指定されていないこと、の場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

      BigQuery 列名の値は文字列型で、1 から 63 文字の範囲で、RFC-1034 に準拠している必要があります。そうしないと、ドキュメントのインポートに失敗します。

C#

詳細については、Vertex AI Agent Builder C# API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedDocumentServiceClientSnippets
{
    /// <summary>Snippet for ImportDocuments</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void ImportDocumentsRequestObject()
    {
        // Create client
        DocumentServiceClient documentServiceClient = DocumentServiceClient.Create();
        // Initialize request argument(s)
        ImportDocumentsRequest request = new ImportDocumentsRequest
        {
            ParentAsBranchName = BranchName.FromProjectLocationDataStoreBranch("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]"),
            InlineSource = new ImportDocumentsRequest.Types.InlineSource(),
            ErrorConfig = new ImportErrorConfig(),
            ReconciliationMode = ImportDocumentsRequest.Types.ReconciliationMode.Unspecified,
            UpdateMask = new FieldMask(),
            AutoGenerateIds = false,
            IdField = "",
        };
        // Make the request
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> response = documentServiceClient.ImportDocuments(request);

        // Poll until the returned long-running operation is complete
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        ImportDocumentsResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> retrievedResponse = documentServiceClient.PollOnceImportDocuments(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            ImportDocumentsResponse retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewDocumentClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.ImportDocumentsRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#ImportDocumentsRequest.
	}
	op, err := c.ImportDocuments(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

import com.google.cloud.discoveryengine.v1.BranchName;
import com.google.cloud.discoveryengine.v1.DocumentServiceClient;
import com.google.cloud.discoveryengine.v1.ImportDocumentsRequest;
import com.google.cloud.discoveryengine.v1.ImportDocumentsResponse;
import com.google.cloud.discoveryengine.v1.ImportErrorConfig;
import com.google.protobuf.FieldMask;

public class SyncImportDocuments {

  public static void main(String[] args) throws Exception {
    syncImportDocuments();
  }

  public static void syncImportDocuments() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentServiceClient documentServiceClient = DocumentServiceClient.create()) {
      ImportDocumentsRequest request =
          ImportDocumentsRequest.newBuilder()
              .setParent(
                  BranchName.ofProjectLocationDataStoreBranchName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]")
                      .toString())
              .setErrorConfig(ImportErrorConfig.newBuilder().build())
              .setUpdateMask(FieldMask.newBuilder().build())
              .setAutoGenerateIds(true)
              .setIdField("idField1629396127")
              .build();
      ImportDocumentsResponse response = documentServiceClient.importDocumentsAsync(request).get();
    }
  }
}

Node.js

詳細については、Vertex AI Agent Builder Node.js API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  The Inline source for the input content for documents.
 */
// const inlineSource = {}
/**
 *  Cloud Storage location for the input content.
 */
// const gcsSource = {}
/**
 *  BigQuery input source.
 */
// const bigquerySource = {}
/**
 *  FhirStore input source.
 */
// const fhirStoreSource = {}
/**
 *  Spanner input source.
 */
// const spannerSource = {}
/**
 *  Cloud SQL input source.
 */
// const cloudSqlSource = {}
/**
 *  Firestore input source.
 */
// const firestoreSource = {}
/**
 *  AlloyDB input source.
 */
// const alloyDbSource = {}
/**
 *  Cloud Bigtable input source.
 */
// const bigtableSource = {}
/**
 *  Required. The parent branch resource name, such as
 *  `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}`.
 *  Requires create/update permission.
 */
// const parent = 'abc123'
/**
 *  The desired location of errors incurred during the Import.
 */
// const errorConfig = {}
/**
 *  The mode of reconciliation between existing documents and the documents to
 *  be imported. Defaults to
 *  ReconciliationMode.INCREMENTAL google.cloud.discoveryengine.v1.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL.
 */
// const reconciliationMode = {}
/**
 *  Indicates which fields in the provided imported documents to update. If
 *  not set, the default is to update all fields.
 */
// const updateMask = {}
/**
 *  Whether to automatically generate IDs for the documents if absent.
 *  If set to `true`,
 *  Document.id google.cloud.discoveryengine.v1.Document.id s are
 *  automatically generated based on the hash of the payload, where IDs may not
 *  be consistent during multiple imports. In which case
 *  ReconciliationMode.FULL google.cloud.discoveryengine.v1.ImportDocumentsRequest.ReconciliationMode.FULL 
 *  is highly recommended to avoid duplicate contents. If unset or set to
 *  `false`, Document.id google.cloud.discoveryengine.v1.Document.id s have
 *  to be specified using
 *  id_field google.cloud.discoveryengine.v1.ImportDocumentsRequest.id_field,
 *  otherwise, documents without IDs fail to be imported.
 *  Supported data sources:
 *  * GcsSource google.cloud.discoveryengine.v1.GcsSource.
 *  GcsSource.data_schema google.cloud.discoveryengine.v1.GcsSource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * BigQuerySource google.cloud.discoveryengine.v1.BigQuerySource.
 *  BigQuerySource.data_schema google.cloud.discoveryengine.v1.BigQuerySource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * SpannerSource google.cloud.discoveryengine.v1.SpannerSource.
 *  * CloudSqlSource google.cloud.discoveryengine.v1.CloudSqlSource.
 *  * FirestoreSource google.cloud.discoveryengine.v1.FirestoreSource.
 *  * BigtableSource google.cloud.discoveryengine.v1.BigtableSource.
 */
// const autoGenerateIds = true
/**
 *  The field indicates the ID field or column to be used as unique IDs of
 *  the documents.
 *  For GcsSource google.cloud.discoveryengine.v1.GcsSource  it is the key of
 *  the JSON field. For instance, `my_id` for JSON `{"my_id": "some_uuid"}`.
 *  For others, it may be the column name of the table where the unique ids are
 *  stored.
 *  The values of the JSON field or the table column are used as the
 *  Document.id google.cloud.discoveryengine.v1.Document.id s. The JSON field
 *  or the table column must be of string type, and the values must be set as
 *  valid strings conform to RFC-1034 (https://tools.ietf.org/html/rfc1034)
 *  with 1-63 characters. Otherwise, documents without valid IDs fail to be
 *  imported.
 *  Only set this field when
 *  auto_generate_ids google.cloud.discoveryengine.v1.ImportDocumentsRequest.auto_generate_ids 
 *  is unset or set as `false`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  If it is unset, a default value `_id` is used when importing from the
 *  allowed data sources.
 *  Supported data sources:
 *  * GcsSource google.cloud.discoveryengine.v1.GcsSource.
 *  GcsSource.data_schema google.cloud.discoveryengine.v1.GcsSource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * BigQuerySource google.cloud.discoveryengine.v1.BigQuerySource.
 *  BigQuerySource.data_schema google.cloud.discoveryengine.v1.BigQuerySource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * SpannerSource google.cloud.discoveryengine.v1.SpannerSource.
 *  * CloudSqlSource google.cloud.discoveryengine.v1.CloudSqlSource.
 *  * FirestoreSource google.cloud.discoveryengine.v1.FirestoreSource.
 *  * BigtableSource google.cloud.discoveryengine.v1.BigtableSource.
 */
// const idField = 'abc123'

// Imports the Discoveryengine library
const {DocumentServiceClient} = require('@google-cloud/discoveryengine').v1;

// Instantiates a client
const discoveryengineClient = new DocumentServiceClient();

async function callImportDocuments() {
  // Construct request
  const request = {
    parent,
  };

  // Run request
  const [operation] = await discoveryengineClient.importDocuments(request);
  const [response] = await operation.promise();
  console.log(response);
}

callImportDocuments();

Python

詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。



def import_documents_bigquery_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    bigquery_dataset: str,
    bigquery_table: str,
) -> str:

    from google.api_core.client_options import ClientOptions
    from google.cloud import discoveryengine

    # TODO(developer): Uncomment these variables before running the sample.
    # project_id = "YOUR_PROJECT_ID"
    # location = "YOUR_LOCATION" # Values: "global"
    # data_store_id = "YOUR_DATA_STORE_ID"
    # bigquery_dataset = "YOUR_BIGQUERY_DATASET"
    # bigquery_table = "YOUR_BIGQUERY_TABLE"

    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.DocumentServiceClient(client_options=client_options)

    # The full resource name of the search engine branch.
    # e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
    parent = client.branch_path(
        project=project_id,
        location=location,
        data_store=data_store_id,
        branch="default_branch",
    )

    request = discoveryengine.ImportDocumentsRequest(
        parent=parent,
        bigquery_source=discoveryengine.BigQuerySource(
            project_id=project_id,
            dataset_id=bigquery_dataset,
            table_id=bigquery_table,
            data_schema="custom",
        ),
        # Options: `FULL`, `INCREMENTAL`
        reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
    )

    # Make the request
    operation = client.import_documents(request=request)

    print(f"Waiting for operation to complete: {operation.operation.name}")
    response = operation.result()

    # After the operation is complete,
    # get information from operation metadata
    metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

    # Handle the response
    print(response)
    print(metadata)

    return operation.operation.name


def import_documents_gcs_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    gcs_uri: str,
) -> str:
    from google.api_core.client_options import ClientOptions
    from google.cloud import discoveryengine

    # TODO(developer): Uncomment these variables before running the sample.
    # project_id = "YOUR_PROJECT_ID"
    # location = "YOUR_LOCATION" # Values: "global"
    # data_store_id = "YOUR_DATA_STORE_ID"

    # Examples:
    # - Unstructured documents
    #   - `gs://bucket/directory/file.pdf`
    #   - `gs://bucket/directory/*.pdf`
    # - Unstructured documents with JSONL Metadata
    #   - `gs://bucket/directory/file.json`
    # - Unstructured documents with CSV Metadata
    #   - `gs://bucket/directory/file.csv`
    # gcs_uri = "YOUR_GCS_PATH"

    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.DocumentServiceClient(client_options=client_options)

    # The full resource name of the search engine branch.
    # e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
    parent = client.branch_path(
        project=project_id,
        location=location,
        data_store=data_store_id,
        branch="default_branch",
    )

    request = discoveryengine.ImportDocumentsRequest(
        parent=parent,
        gcs_source=discoveryengine.GcsSource(
            # Multiple URIs are supported
            input_uris=[gcs_uri],
            # Options:
            # - `content` - Unstructured documents (PDF, HTML, DOC, TXT, PPTX)
            # - `custom` - Unstructured documents with custom JSONL metadata
            # - `document` - Structured documents in the discoveryengine.Document format.
            # - `csv` - Unstructured documents with CSV metadata
            data_schema="content",
        ),
        # Options: `FULL`, `INCREMENTAL`
        reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
    )

    # Make the request
    operation = client.import_documents(request=request)

    print(f"Waiting for operation to complete: {operation.operation.name}")
    response = operation.result()

    # After the operation is complete,
    # get information from operation metadata
    metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

    # Handle the response
    print(response)
    print(metadata)

    return operation.operation.name

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the import_documents call in the DocumentService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::DocumentService::Client#import_documents.
#
def import_documents
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::DocumentService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::ImportDocumentsRequest.new

  # Call the import_documents method.
  result = client.import_documents request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

次のステップ

Cloud Storage

Cloud Storage からデータを取り込むには、次の手順でデータストアを作成し、Google Cloud コンソールまたは API を使用してデータを取り込みます。

データをインポートする前に、取り込むデータを準備します。

Console

コンソールを使用して Cloud Storage バケットからデータを取り込む手順は次のとおりです。

  1. Google Cloud コンソールで、[Agent Builder] ページに移動します。

    Agent Builder

  2. [データストア] ページに移動します。

  3. [新しいデータストア] をクリックします。

  4. [タイプ] ページで、[Cloud Storage] を選択します。

  5. [インポートするフォルダまたはファイルを選択] セクションで、[フォルダ] または [ファイル] を選択します。

  6. [参照] をクリックして、取り込み用に準備したデータを選択し、[選択] をクリックします。 または、[gs://] フィールドにロケーションを直接入力します。

  7. インポートするデータの種類を選択します。

  8. [続行] をクリックします。

  9. 構造化データを 1 回限りインポートする場合:

    1. フィールドをキー プロパティにマッピングします。

    2. スキーマに重要なフィールドが欠落している場合は、[新しいフィールドを追加] を使用して追加します。

      詳細については、自動検出と編集についてをご覧ください。

    3. [続行] をクリックします。

  10. データストアのリージョンを選択します。

  11. データストアの名前を入力します。

  12. [作成] をクリックします。

  13. データストアが作成されたことを確認するには、[データストア] ページに移動し、データストア名をクリックして、[データ] ページで詳細を表示します。

  14. 取り込みのステータスを確認するには、[データストア] ページに移動し、データストア名をクリックして、[データ] ページで詳細を表示します。[アクティビティ] タブのステータス列が [進行中] から [インポート完了] に変わると、取り込みが完了します。

    取り込みには、データのサイズに応じて、数分から数時間かかることがあります。

REST

コマンドラインを使用してデータストアを作成し、Cloud Storage からデータを取り込む手順は次のとおりです。

  1. データストアを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "GENERIC",
  "solutionTypes": ["SOLUTION_TYPE_RECOMMENDATION"],
  "contentConfig": "CONTENT_REQUIRED"
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: 作成するレコメンデーション データストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
    • DATA_STORE_DISPLAY_NAME: 作成するレコメンデーション データストアの表示名。

  2. Cloud Storage からデータをインポートします。

      curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents:import" \
  -d '{
    "gcsSource": {
      "inputUris": ["INPUT_FILE_PATTERN_1", "INPUT_FILE_PATTERN_2"],
      "dataSchema": "DATA_SCHEMA",
    },
    "reconciliationMode": "RECONCILIATION_MODE",
    "autoGenerateIds": "AUTO_GENERATE_IDS",
    "idField": "ID_FIELD",
    "errorConfig": {
      "gcsPrefix": "ERROR_DIRECTORY"
    }
  }'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: レコメンデーション データストアの ID。

    • INPUT_FILE_PATTERN: ドキュメントを含む Cloud Storage 内のファイル パターン。

      構造化データの場合、または非構造化ドキュメントのメタデータを含む非構造化データの場合、入力ファイル パターンの例は gs://<your-gcs-bucket>/directory/object.json です。また、1 つ以上のファイルに一致するパターン（gs://<your-gcs-bucket>/directory/*.json など）も使用できます。

      非構造化ドキュメントの例は gs://<your-gcs-bucket>/directory/*.pdf です。パターンに一致する各ファイルがドキュメントになります。

      <your-gcs-bucket> が PROJECT_ID にない場合は、サービス アカウント service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com に Cloud Storage バケットに対する「ストレージ オブジェクト閲覧者」権限を付与する必要があります。たとえば、転送元プロジェクト「123」から転送先プロジェクト「456」に Cloud Storage バケットをインポートする場合は、プロジェクト「123」の Cloud Storage バケットに対する service-456@gcp-sa-discoveryengine.iam.gserviceaccount.com 権限を付与します。

    • DATA_SCHEMA: 省略可。値は document、custom、csv および content です。デフォルトは document です。

      • document: 非構造化ドキュメントのメタデータを含む非構造化データをアップロードします。ファイルの各行は、次のいずれかの形式にする必要があります。各ドキュメントの ID を定義できます。

        • { "id": "<your-id>", "jsonData": "<JSON string>", "content": { "mimeType": "<application/pdf or text/html>", "uri": "gs://<your-gcs-bucket>/directory/filename.pdf" } }
        • { "id": "<your-id>", "structData": <JSON object>, "content": { "mimeType": "<application/pdf or text/html>", "uri": "gs://<your-gcs-bucket>/directory/filename.pdf" } }

      • custom: 構造化ドキュメントの JSON をアップロードします。データはスキーマに従って編成されます。スキーマを指定することもできます。指定しない場合、スキーマは自動的に検出されます。ドキュメントの JSON 文字列を各行に直接一貫した形式で配置できます。インポートされた各ドキュメントの ID は、推奨事項によって自動的に生成されます。

      • content: 非構造化ドキュメント（PDF、HTML、DOC、TXT、PPTX）をアップロードします。各ドキュメントの ID は、SHA256(GCS_URI) の最初の 128 ビットが 16 進数文字列としてエンコードされたものとして自動的に生成されます。一致するファイルが 10 万ファイルの制限を超えない限り、複数の入力ファイル パターンを指定できます。

      • csv: CSV ファイルにヘッダー行を含め、各ヘッダーをドキュメント フィールドにマッピングします。inputUris フィールドを使用して、CSV ファイルのパスを指定します。

    • ERROR_DIRECTORY: 省略可。インポートに関するエラー情報用の Cloud Storage ディレクトリ（例: gs://<your-gcs-bucket>/directory/import_errors）。Recommendations が一時ディレクトリを自動的に作成できるように、このフィールドを空のままにすることをおすすめします。

    • RECONCILIATION_MODE: 省略可。値は FULL および INCREMENTAL です。デフォルトは INCREMENTAL です。INCREMENTAL を指定すると、Cloud Storage からデータストアへのデータの増分更新が行われます。これにより、アップサート オペレーションが実行され、新しいドキュメントを追加し、既存のドキュメントを更新された同じ ID のドキュメントで置き換えます。FULL を指定すると、データストア内のドキュメントが完全に再ベース化されます。つまり、新しいドキュメントと更新されたドキュメントがデータストアに追加され、Cloud Storage にないドキュメントがデータストアから削除されます。FULL モードは、不要になったドキュメントを自動的に削除する場合に便利です。

    • AUTO_GENERATE_IDS: 省略可。ドキュメント ID を自動生成するかどうかを指定します。true に設定すると、ドキュメント ID はペイロードのハッシュに基づいて生成されます。生成されたドキュメント ID は、複数のインポートで整合性が維持されない場合があります。複数のインポートで ID を自動生成する場合は、ドキュメント ID の整合性を維持するために、reconciliationMode を FULL に設定することを強くおすすめします。

      autoGenerateIds は、gcsSource.dataSchema が custom または csv に設定されている場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。autoGenerateIds を指定しない場合、または false に設定しない場合は、idField を指定する必要があります。そうしないと、ドキュメントのインポートに失敗します。

    • ID_FIELD: 省略可。ドキュメント ID のフィールドを指定します。Cloud Storage ソースドキュメントの場合、idField は、ドキュメント ID である JSON フィールドの名前を指定します。たとえば、{"my_id":"some_uuid"} がドキュメントの 1 つのドキュメント ID フィールドの場合は、"idField":"my_id" を指定します。これにより、"my_id" という名前のすべての JSON フィールドがドキュメント ID として識別されます。

      このフィールドは、（1）gcsSource.dataSchema が custom または csv に設定されていること、（2）auto_generate_ids が false に設定されているか未指定であることの両方の場合にのみ指定します。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。

      Cloud Storage JSON フィールドの値は、文字列型で、1 から 63 文字の範囲で、RFC-1034 に準拠している必要があります。そうしないと、ドキュメントのインポートに失敗します。

      id_field で指定された JSON フィールド名は、文字列型で、1 から 63 文字の範囲で、RFC-1034 に準拠している必要があります。そうしないと、ドキュメントのインポートに失敗します。

C#

詳細については、Vertex AI Agent Builder C# API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

using Google.Cloud.DiscoveryEngine.V1;
using Google.LongRunning;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedDocumentServiceClientSnippets
{
    /// <summary>Snippet for ImportDocuments</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void ImportDocumentsRequestObject()
    {
        // Create client
        DocumentServiceClient documentServiceClient = DocumentServiceClient.Create();
        // Initialize request argument(s)
        ImportDocumentsRequest request = new ImportDocumentsRequest
        {
            ParentAsBranchName = BranchName.FromProjectLocationDataStoreBranch("[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]"),
            InlineSource = new ImportDocumentsRequest.Types.InlineSource(),
            ErrorConfig = new ImportErrorConfig(),
            ReconciliationMode = ImportDocumentsRequest.Types.ReconciliationMode.Unspecified,
            UpdateMask = new FieldMask(),
            AutoGenerateIds = false,
            IdField = "",
        };
        // Make the request
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> response = documentServiceClient.ImportDocuments(request);

        // Poll until the returned long-running operation is complete
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        ImportDocumentsResponse result = completedResponse.Result;

        // Or get the name of the operation
        string operationName = response.Name;
        // This name can be stored, then the long-running operation retrieved later by name
        Operation<ImportDocumentsResponse, ImportDocumentsMetadata> retrievedResponse = documentServiceClient.PollOnceImportDocuments(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            ImportDocumentsResponse retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

詳細については、Vertex AI Agent Builder Go API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。


package main

import (
	"context"

	discoveryengine "cloud.google.com/go/discoveryengine/apiv1"
	discoveryenginepb "cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := discoveryengine.NewDocumentClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.ImportDocumentsRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#ImportDocumentsRequest.
	}
	op, err := c.ImportDocuments(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}

	resp, err := op.Wait(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

Java

詳細については、Vertex AI Agent Builder Java API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

import com.google.cloud.discoveryengine.v1.BranchName;
import com.google.cloud.discoveryengine.v1.DocumentServiceClient;
import com.google.cloud.discoveryengine.v1.ImportDocumentsRequest;
import com.google.cloud.discoveryengine.v1.ImportDocumentsResponse;
import com.google.cloud.discoveryengine.v1.ImportErrorConfig;
import com.google.protobuf.FieldMask;

public class SyncImportDocuments {

  public static void main(String[] args) throws Exception {
    syncImportDocuments();
  }

  public static void syncImportDocuments() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (DocumentServiceClient documentServiceClient = DocumentServiceClient.create()) {
      ImportDocumentsRequest request =
          ImportDocumentsRequest.newBuilder()
              .setParent(
                  BranchName.ofProjectLocationDataStoreBranchName(
                          "[PROJECT]", "[LOCATION]", "[DATA_STORE]", "[BRANCH]")
                      .toString())
              .setErrorConfig(ImportErrorConfig.newBuilder().build())
              .setUpdateMask(FieldMask.newBuilder().build())
              .setAutoGenerateIds(true)
              .setIdField("idField1629396127")
              .build();
      ImportDocumentsResponse response = documentServiceClient.importDocumentsAsync(request).get();
    }
  }
}

Node.js

詳細については、Vertex AI Agent Builder Node.js API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  The Inline source for the input content for documents.
 */
// const inlineSource = {}
/**
 *  Cloud Storage location for the input content.
 */
// const gcsSource = {}
/**
 *  BigQuery input source.
 */
// const bigquerySource = {}
/**
 *  FhirStore input source.
 */
// const fhirStoreSource = {}
/**
 *  Spanner input source.
 */
// const spannerSource = {}
/**
 *  Cloud SQL input source.
 */
// const cloudSqlSource = {}
/**
 *  Firestore input source.
 */
// const firestoreSource = {}
/**
 *  AlloyDB input source.
 */
// const alloyDbSource = {}
/**
 *  Cloud Bigtable input source.
 */
// const bigtableSource = {}
/**
 *  Required. The parent branch resource name, such as
 *  `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/branches/{branch}`.
 *  Requires create/update permission.
 */
// const parent = 'abc123'
/**
 *  The desired location of errors incurred during the Import.
 */
// const errorConfig = {}
/**
 *  The mode of reconciliation between existing documents and the documents to
 *  be imported. Defaults to
 *  ReconciliationMode.INCREMENTAL google.cloud.discoveryengine.v1.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL.
 */
// const reconciliationMode = {}
/**
 *  Indicates which fields in the provided imported documents to update. If
 *  not set, the default is to update all fields.
 */
// const updateMask = {}
/**
 *  Whether to automatically generate IDs for the documents if absent.
 *  If set to `true`,
 *  Document.id google.cloud.discoveryengine.v1.Document.id s are
 *  automatically generated based on the hash of the payload, where IDs may not
 *  be consistent during multiple imports. In which case
 *  ReconciliationMode.FULL google.cloud.discoveryengine.v1.ImportDocumentsRequest.ReconciliationMode.FULL 
 *  is highly recommended to avoid duplicate contents. If unset or set to
 *  `false`, Document.id google.cloud.discoveryengine.v1.Document.id s have
 *  to be specified using
 *  id_field google.cloud.discoveryengine.v1.ImportDocumentsRequest.id_field,
 *  otherwise, documents without IDs fail to be imported.
 *  Supported data sources:
 *  * GcsSource google.cloud.discoveryengine.v1.GcsSource.
 *  GcsSource.data_schema google.cloud.discoveryengine.v1.GcsSource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * BigQuerySource google.cloud.discoveryengine.v1.BigQuerySource.
 *  BigQuerySource.data_schema google.cloud.discoveryengine.v1.BigQuerySource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * SpannerSource google.cloud.discoveryengine.v1.SpannerSource.
 *  * CloudSqlSource google.cloud.discoveryengine.v1.CloudSqlSource.
 *  * FirestoreSource google.cloud.discoveryengine.v1.FirestoreSource.
 *  * BigtableSource google.cloud.discoveryengine.v1.BigtableSource.
 */
// const autoGenerateIds = true
/**
 *  The field indicates the ID field or column to be used as unique IDs of
 *  the documents.
 *  For GcsSource google.cloud.discoveryengine.v1.GcsSource  it is the key of
 *  the JSON field. For instance, `my_id` for JSON `{"my_id": "some_uuid"}`.
 *  For others, it may be the column name of the table where the unique ids are
 *  stored.
 *  The values of the JSON field or the table column are used as the
 *  Document.id google.cloud.discoveryengine.v1.Document.id s. The JSON field
 *  or the table column must be of string type, and the values must be set as
 *  valid strings conform to RFC-1034 (https://tools.ietf.org/html/rfc1034)
 *  with 1-63 characters. Otherwise, documents without valid IDs fail to be
 *  imported.
 *  Only set this field when
 *  auto_generate_ids google.cloud.discoveryengine.v1.ImportDocumentsRequest.auto_generate_ids 
 *  is unset or set as `false`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  If it is unset, a default value `_id` is used when importing from the
 *  allowed data sources.
 *  Supported data sources:
 *  * GcsSource google.cloud.discoveryengine.v1.GcsSource.
 *  GcsSource.data_schema google.cloud.discoveryengine.v1.GcsSource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * BigQuerySource google.cloud.discoveryengine.v1.BigQuerySource.
 *  BigQuerySource.data_schema google.cloud.discoveryengine.v1.BigQuerySource.data_schema 
 *  must be `custom` or `csv`. Otherwise, an INVALID_ARGUMENT error is thrown.
 *  * SpannerSource google.cloud.discoveryengine.v1.SpannerSource.
 *  * CloudSqlSource google.cloud.discoveryengine.v1.CloudSqlSource.
 *  * FirestoreSource google.cloud.discoveryengine.v1.FirestoreSource.
 *  * BigtableSource google.cloud.discoveryengine.v1.BigtableSource.
 */
// const idField = 'abc123'

// Imports the Discoveryengine library
const {DocumentServiceClient} = require('@google-cloud/discoveryengine').v1;

// Instantiates a client
const discoveryengineClient = new DocumentServiceClient();

async function callImportDocuments() {
  // Construct request
  const request = {
    parent,
  };

  // Run request
  const [operation] = await discoveryengineClient.importDocuments(request);
  const [response] = await operation.promise();
  console.log(response);
}

callImportDocuments();

Python

詳細については、Vertex AI Agent Builder Python API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。



def import_documents_bigquery_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    bigquery_dataset: str,
    bigquery_table: str,
) -> str:

    from google.api_core.client_options import ClientOptions
    from google.cloud import discoveryengine

    # TODO(developer): Uncomment these variables before running the sample.
    # project_id = "YOUR_PROJECT_ID"
    # location = "YOUR_LOCATION" # Values: "global"
    # data_store_id = "YOUR_DATA_STORE_ID"
    # bigquery_dataset = "YOUR_BIGQUERY_DATASET"
    # bigquery_table = "YOUR_BIGQUERY_TABLE"

    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.DocumentServiceClient(client_options=client_options)

    # The full resource name of the search engine branch.
    # e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
    parent = client.branch_path(
        project=project_id,
        location=location,
        data_store=data_store_id,
        branch="default_branch",
    )

    request = discoveryengine.ImportDocumentsRequest(
        parent=parent,
        bigquery_source=discoveryengine.BigQuerySource(
            project_id=project_id,
            dataset_id=bigquery_dataset,
            table_id=bigquery_table,
            data_schema="custom",
        ),
        # Options: `FULL`, `INCREMENTAL`
        reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
    )

    # Make the request
    operation = client.import_documents(request=request)

    print(f"Waiting for operation to complete: {operation.operation.name}")
    response = operation.result()

    # After the operation is complete,
    # get information from operation metadata
    metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

    # Handle the response
    print(response)
    print(metadata)

    return operation.operation.name


def import_documents_gcs_sample(
    project_id: str,
    location: str,
    data_store_id: str,
    gcs_uri: str,
) -> str:
    from google.api_core.client_options import ClientOptions
    from google.cloud import discoveryengine

    # TODO(developer): Uncomment these variables before running the sample.
    # project_id = "YOUR_PROJECT_ID"
    # location = "YOUR_LOCATION" # Values: "global"
    # data_store_id = "YOUR_DATA_STORE_ID"

    # Examples:
    # - Unstructured documents
    #   - `gs://bucket/directory/file.pdf`
    #   - `gs://bucket/directory/*.pdf`
    # - Unstructured documents with JSONL Metadata
    #   - `gs://bucket/directory/file.json`
    # - Unstructured documents with CSV Metadata
    #   - `gs://bucket/directory/file.csv`
    # gcs_uri = "YOUR_GCS_PATH"

    #  For more information, refer to:
    # https://cloud.google.com/generative-ai-app-builder/docs/locations#specify_a_multi-region_for_your_data_store
    client_options = (
        ClientOptions(api_endpoint=f"{location}-discoveryengine.googleapis.com")
        if location != "global"
        else None
    )

    # Create a client
    client = discoveryengine.DocumentServiceClient(client_options=client_options)

    # The full resource name of the search engine branch.
    # e.g. projects/{project}/locations/{location}/dataStores/{data_store_id}/branches/{branch}
    parent = client.branch_path(
        project=project_id,
        location=location,
        data_store=data_store_id,
        branch="default_branch",
    )

    request = discoveryengine.ImportDocumentsRequest(
        parent=parent,
        gcs_source=discoveryengine.GcsSource(
            # Multiple URIs are supported
            input_uris=[gcs_uri],
            # Options:
            # - `content` - Unstructured documents (PDF, HTML, DOC, TXT, PPTX)
            # - `custom` - Unstructured documents with custom JSONL metadata
            # - `document` - Structured documents in the discoveryengine.Document format.
            # - `csv` - Unstructured documents with CSV metadata
            data_schema="content",
        ),
        # Options: `FULL`, `INCREMENTAL`
        reconciliation_mode=discoveryengine.ImportDocumentsRequest.ReconciliationMode.INCREMENTAL,
    )

    # Make the request
    operation = client.import_documents(request=request)

    print(f"Waiting for operation to complete: {operation.operation.name}")
    response = operation.result()

    # After the operation is complete,
    # get information from operation metadata
    metadata = discoveryengine.ImportDocumentsMetadata(operation.metadata)

    # Handle the response
    print(response)
    print(metadata)

    return operation.operation.name

Ruby

詳細については、Vertex AI Agent Builder Ruby API のリファレンス ドキュメントをご覧ください。

Vertex AI Agent Builder に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、ローカル開発環境の認証の設定をご覧ください。

このサンプルでは、BigQuery または Cloud Storage から非構造化データを既存のデータストアに取り込みます。

require "google/cloud/discovery_engine/v1"

##
# Snippet for the import_documents call in the DocumentService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DiscoveryEngine::V1::DocumentService::Client#import_documents.
#
def import_documents
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::DocumentService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DiscoveryEngine::V1::ImportDocumentsRequest.new

  # Call the import_documents method.
  result = client.import_documents request

  # The returned object is of type Gapic::Operation. You can use it to
  # check the status of an operation, cancel it, or wait for results.
  # Here is how to wait for a response.
  result.wait_until_done! timeout: 60
  if result.response?
    p result.response
  else
    puts "No response received."
  end
end

次のステップ

API を使用して構造化 JSON データをアップロードする

API を使用して JSON ドキュメントまたはオブジェクトを直接アップロードする手順は次のとおりです。

データをインポートする前に、取り込むデータを準備します。

REST

コマンドラインを使用してデータストアを作成し、構造化 JSON データをインポートする手順は次のとおりです。

  1. データストアを作成します。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "GENERIC",
  "solutionTypes": ["SOLUTION_TYPE_RECOMMENDATION"]
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: 作成するレコメンデーション データストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
    • DATA_STORE_DISPLAY_NAME: 作成するレコメンデーション データストアの表示名。

  2. 省略可: 独自のスキーマを指定します。スキーマを指定すると、通常はより良い結果が得られます。詳細については、スキーマを指定する、または自動検出するをご覧ください。

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    以下を置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID。
    • DATA_STORE_ID: レコメンデーション データストアの ID。

    • JSON_SCHEMA_OBJECT: JSON オブジェクトとしての JSON スキーマ。次に例を示します。

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  3. 定義されたスキーマに準拠する構造化データをインポートします。

    データのアップロードには、次のような方法があります。

    • JSON ドキュメントをアップロードします。

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents?documentId=DOCUMENT_ID" \
-d '{
  "jsonData": "JSON_DOCUMENT_STRING"
}'

      JSON_DOCUMENT_STRING は、単一の文字列として JSON ドキュメントを置き換えます。これは、前の手順で指定した JSON スキーマに準拠している必要があります。次に例を示します。

      ```none
{ \"title\": \"test title\", \"categories\": [\"cat_1\", \"cat_2\"], \"uri\": \"test uri\"}
```

    • JSON オブジェクトをアップロードします。

      curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents?documentId=DOCUMENT_ID" \
-d '{
  "structData": JSON_DOCUMENT_OBJECT
}'

      JSON_DOCUMENT_OBJECT は、JSON オブジェクトとして JSON ドキュメントを置き換えます。これは、前の手順で指定した JSON スキーマに準拠している必要があります。次に例を示します。

      ```json
{
  "title": "test title",
  "categories": [
    "cat_1",
    "cat_2"
  ],
  "uri": "test uri"
}
```

    • JSON ドキュメントで更新します。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID" \
-d '{
  "jsonData": "JSON_DOCUMENT_STRING"
}'

    • JSON オブジェクトで更新します。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID" \
-d '{
  "structData": JSON_DOCUMENT_OBJECT
}'

次のステップ

Terraform を使用してデータストアを作成する

Terraform を使用して空のデータストアを作成できます。空のデータストアを作成したら、Google Cloud コンソールまたは API コマンドを使用してデータストアにデータを取り込むことができます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

Terraform を使用して空のデータストアを作成するには、 google_discovery_engine_data_store をご覧ください。