Crea un almacén de datos de recomendaciones genérico

Nota: Esta función es una Versión preliminar que está sujeta a las “Condiciones de la oferta de la fase previa a la DG” de las Condiciones específicas del servicio de GCP. La asistencia de los productos y las características de la fase previa a la DG puede ser limitada, y es posible que los cambios en estos productos y características no sean compatibles con otras versiones de la fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento. Además, si usas esta función, aceptas los Términos y Condiciones de la Versión Preliminar de IA Generativa (“Términos de la Versión Preliminar”). Para usar esta función, puedes procesar datos personales según está descrito en el Anexo de Tratamiento de Datos de Cloud, sujeto a las restricciones y obligaciones aplicables en el Acuerdo (como se define en los Términos de la Versión Preliminar).

Para crear un almacén de datos y transferir datos para recomendaciones genéricas, ve a la sección de la fuente que planeas usar:

• BigQuery
• Cloud Storage
• Cómo subir datos JSON estructurados con la API

BigQuery

Para transferir datos de BigQuery, sigue estos pasos para crear un almacén de datos y transferir datos con la consola de Google Cloud o la API.

Antes de importar tus datos, consulta Prepara los datos para la transferencia.

Console

Para usar la consola de Google Cloud y transferir datos de BigQuery, sigue estos pasos:

1. En la consola de Google Cloud, ve a la página Agent Builder.

   Agent Builder

2. Ve a la página Almacenes de datos.

3. Haz clic en Nuevo almacén de datos.

4. En la página Tipo, selecciona BigQuery.

5. En el campo Ruta de acceso de BigQuery, haz clic en Explorar, selecciona una tabla que hayas preparado para transferir y, luego, haz clic en Seleccionar. Como alternativa, ingresa la ubicación de la tabla directamente en el campo Ruta de BigQuery.

6. Selecciona el tipo de datos que deseas importar.

7. Haz clic en Continuar.

8. Si realizas una importación única de datos estructurados, haz lo siguiente:

   1. Asigna campos a propiedades clave.

   2. Si faltan campos importantes en el esquema, usa Agregar campo nuevo para agregarlos.

      Para obtener más información, consulta Acerca de la detección automática y la edición.

   3. Haz clic en Continuar.

9. Elige una región para tu almacén de datos.

10. Ingresa un nombre para tu almacén de datos.

11. Haz clic en Crear.

12. Para confirmar que se creó tu almacén de datos, ve a la página Almacenes de datos y haz clic en el nombre del almacén de datos para ver los detalles en la página Datos.

13. Para verificar el estado de la transferencia, ve a la página Almacenes de datos y haz clic en el nombre de tu almacén de datos para ver los detalles en la página Datos. Cuando la columna de estado de la pestaña Actividad cambie de En curso a Importación completada, se habrá completado la transferencia.

    Según el tamaño de tus datos, la transferencia puede tardar varios minutos o varias horas.

REST

Para usar la línea de comandos y crear un almacén de datos y, luego, importar datos desde BigQuery, sigue estos pasos:

1. Crea un almacén de datos.

   Nota: Este paso es experimental. Si deseas un procedimiento de GA, sigue los pasos 1 a 4 de las instrucciones de Console para crear un almacén de datos.

   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"]
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: Es el ID del almacén de datos de recomendaciones que deseas crear. Este ID solo puede contener letras en minúscula, dígitos, guiones bajos y guiones.
   • DATA_STORE_DISPLAY_NAME: Es el nombre visible del almacén de datos de recomendaciones que deseas crear.

2. Opcional: Si subes datos estructurados con tu propio esquema, puedes proporcionarlo. Cuando proporcionas el esquema, por lo general, obtienes mejores resultados. De lo contrario, el esquema se detecta automáticamente. Para obtener más información, consulta Proporciona o detecta automáticamente un esquema.

   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
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: El ID del almacén de datos de recomendaciones.

   • JSON_SCHEMA_OBJECT: Tu esquema JSON como objeto JSON, por ejemplo:

     {
       "$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. Importa datos de BigQuery.

   Si definiste un esquema, asegúrate de que los datos cumplan con ese esquema.

   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"
     }
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: El ID del almacén de datos de recomendaciones.
   • DATASET_ID: El ID del conjunto de datos de BigQuery.
   • TABLE_ID: El ID de la tabla de BigQuery.
     • Si la tabla de BigQuery no está en PROJECT_ID, debes otorgarle a la cuenta de servicio service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com permiso de "Visualizador de datos de BigQuery" para la tabla de BigQuery. Por ejemplo, si importas una tabla de BigQuery del proyecto de origen "123" al proyecto de destino "456", otorga permisos [e-mail] para la tabla de BigQuery en el proyecto "123".
   • DATA_SCHEMA: es opcional. Los valores son document y custom. El valor predeterminado es document.
     • document: La tabla de BigQuery que uses debe cumplir con el esquema predeterminado de BigQuery que se proporciona en Cómo preparar los datos para la transferencia. Puedes definir el ID de cada documento por tu cuenta, mientras unes todos los datos en la cadena jsonData.
     • custom: Se acepta cualquier esquema de tabla de BigQuery, y Recomendaciones genera automáticamente los IDs de cada documento que se importa.
   • ERROR_DIRECTORY: es opcional. Un directorio de Cloud Storage para obtener información sobre los errores de la importación (por ejemplo, gs://<your-gcs-bucket>/directory/import_errors). Google recomienda dejar este campo vacío para que Recomendaciones cree automáticamente un directorio temporal.
   • RECONCILIATION_MODE: es opcional. Los valores son FULL y INCREMENTAL. El valor predeterminado es INCREMENTAL. Especificar INCREMENTAL provoca una actualización incremental de los datos de BigQuery a tu almacén de datos. Esto realiza una operación de inserción y actualización, que agrega documentos nuevos y reemplaza los existentes por documentos actualizados con el mismo ID. Especificar FULL causa una rebase completa de los documentos en tu almacén de datos. En otras palabras, los documentos nuevos y actualizados se agregan a tu almacén de datos, y los documentos que no están en BigQuery se quitan de tu almacén de datos. El modo FULL es útil si quieres borrar automáticamente los documentos que ya no necesitas.

   • AUTO_GENERATE_IDS: es opcional. Especifica si se deben generar automáticamente los IDs de documento. Si se establece en true, los IDs de los documentos se generan en función de un hash de la carga útil. Ten en cuenta que los IDs de documentos generados pueden no mantenerse coherentes en varias importaciones. Si generas IDs automáticamente en varias importaciones, Google recomienda configurar reconciliationMode como FULL para mantener IDs de documentos coherentes.

     Especifica autoGenerateIds solo cuando bigquerySource.dataSchema se establece en custom. De lo contrario, se muestra un error INVALID_ARGUMENT. Si no especificas autoGenerateIds o lo configuras en false, debes especificar idField. De lo contrario, los documentos no se importarán.

   • ID_FIELD: es opcional. Especifica qué campos son los IDs de los documentos. En el caso de los archivos de origen de BigQuery, idField indica el nombre de la columna en la tabla de BigQuery que contiene los IDs de documentos.

     Especifica idField solo cuando: (1) bigquerySource.dataSchema se establece como custom y (2) auto_generate_ids se establece como false o no se especifica. De lo contrario, se muestra un error INVALID_ARGUMENT.

     El valor del nombre de la columna de BigQuery debe ser de tipo cadena, debe tener entre 1 y 63 caracteres y debe cumplir con RFC-1034. De lo contrario, no se importarán los documentos.

C#

Para obtener más información, consulta la documentación de referencia de la API de C# del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Go del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Java del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Node.js del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

/**
 * 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

Para obtener más información, consulta la documentación de referencia de la API de Python del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Ruby del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Próximos pasos

• Para conectar tu almacén de datos a una app, crea una app y selecciona tu almacén de datos siguiendo los pasos que se indican en Cómo crear una app de recomendaciones genéricas.

• Para obtener una vista previa de cómo aparecen tus recomendaciones después de configurar la app y el almacén de datos, consulta Obtén recomendaciones.

Cloud Storage

Para transferir datos desde Cloud Storage, sigue estos pasos para crear un almacén de datos y transferir datos con la consola de Google Cloud o la API.

Antes de importar tus datos, consulta Prepara los datos para la transferencia.

Console

Para usar la consola y transferir datos de un bucket de Cloud Storage, sigue estos pasos:

1. En la consola de Google Cloud, ve a la página Agent Builder.

   Agent Builder

2. Ve a la página Almacenes de datos.

3. Haz clic en Nuevo almacén de datos.

4. En la página Tipo, selecciona Cloud Storage.

5. En la sección Selecciona una carpeta o un archivo que desees importar, selecciona Carpeta o Archivo.

6. Haz clic en Explorar y elige los datos que preparaste para transferir. Luego, haz clic en Seleccionar. Como alternativa, ingresa la ubicación directamente en el campo gs://.

7. Selecciona el tipo de datos que deseas importar.

8. Haz clic en Continuar.

9. Si realizas una importación única de datos estructurados, haz lo siguiente:

   1. Asigna campos a propiedades clave.

   2. Si faltan campos importantes en el esquema, usa Agregar campo nuevo para agregarlos.

      Para obtener más información, consulta Acerca de la detección automática y la edición.

   3. Haz clic en Continuar.

10. Elige una región para tu almacén de datos.

11. Ingresa un nombre para tu almacén de datos.

12. Haz clic en Crear.

13. Para confirmar que se creó tu almacén de datos, ve a la página Almacenes de datos y haz clic en el nombre del almacén de datos para ver los detalles en la página Datos.

14. Para verificar el estado de la transferencia, ve a la página Almacenes de datos y haz clic en el nombre de tu almacén de datos para ver los detalles en la página Datos. Cuando la columna de estado de la pestaña Actividad cambie de En curso a Importación completada, se habrá completado la transferencia.

    Según el tamaño de tus datos, la transferencia puede tardar varios minutos o varias horas.

REST

Para usar la línea de comandos y crear un almacén de datos y transferir datos desde Cloud Storage, sigue estos pasos:

1. Crea un almacén de datos.

   Nota: Este paso es experimental. Si deseas un procedimiento de GA, sigue los pasos 1 a 4 de las instrucciones de Console para crear un almacén de datos.

   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"
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: Es el ID del almacén de datos de recomendaciones que deseas crear. Este ID solo puede contener letras en minúscula, dígitos, guiones bajos y guiones.
   • DATA_STORE_DISPLAY_NAME: Es el nombre visible del almacén de datos de recomendaciones que deseas crear.

2. Importar datos desde 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"
       }
     }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: El ID del almacén de datos de recomendaciones.

   • INPUT_FILE_PATTERN: Es un patrón de archivo en Cloud Storage que contiene tus documentos.

     Para datos estructurados o datos no estructurados con metadatos para documentos no estructurados, un ejemplo del patrón de archivo de entrada es gs://<your-gcs-bucket>/directory/object.json, o un patrón que coincida con uno o más archivos, como gs://<your-gcs-bucket>/directory/*.json.

     Para los documentos no estructurados, un ejemplo es gs://<your-gcs-bucket>/directory/*.pdf. Cada archivo que coincida con el patrón se convierte en un documento.

     Si <your-gcs-bucket> no está debajo de PROJECT_ID, debes otorgarle a la cuenta de servicio service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com los permisos de “Visualizador de objetos de almacenamiento” para el bucket de Cloud Storage. Por ejemplo, si importas un bucket de Cloud Storage del proyecto de origen "123" al proyecto de destino "456", otorga permisos [e-mail] en el bucket de Cloud Storage del proyecto "123".

   • DATA_SCHEMA: es opcional. Los valores son document, custom, csv y content. El valor predeterminado es document.

     • document: Sube datos no estructurados con metadatos para documentos no estructurados. Cada línea del archivo debe seguir uno de los siguientes formatos. Puedes definir el ID de cada documento:

       • { "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: Sube JSON para documentos estructurados. Los datos se organizan según un esquema. Puedes especificar el esquema. De lo contrario, se detectará automáticamente. Puedes colocar la cadena JSON del documento en un formato coherente directamente en cada línea, y Recomendaciones genera automáticamente los IDs de cada documento importado.

     • content: Sube documentos no estructurados (PDF, HTML, DOC, TXT y PPTX). El ID de cada documento se genera automáticamente como los primeros 128 bits de SHA256(GCS_URI) codificados como una cadena hexadecimal. Puedes especificar varios patrones de archivos de entrada, siempre y cuando los archivos coincidentes no superen el límite de 100,000 archivos.

     • csv: Incluye una fila de encabezado en el archivo CSV, con cada encabezado asignado a un campo de documento. Especifica la ruta de acceso al archivo CSV con el campo inputUris.

   • ERROR_DIRECTORY: es opcional. Un directorio de Cloud Storage para obtener información sobre los errores de la importación (por ejemplo, gs://<your-gcs-bucket>/directory/import_errors) Google recomienda dejar este campo vacío para que Recomendaciones cree automáticamente un directorio temporal.

   • RECONCILIATION_MODE: es opcional. Los valores son FULL y INCREMENTAL. El valor predeterminado es INCREMENTAL. Especificar INCREMENTAL provoca una actualización incremental de los datos de Cloud Storage a tu almacén de datos. Esto realiza una operación de inserción y actualización, que agrega documentos nuevos y reemplaza los existentes por documentos actualizados con el mismo ID. Especificar FULL causa una rebase completa de los documentos en tu almacén de datos. En otras palabras, se agregan documentos nuevos y actualizados a tu almacén de datos, y se quitan los documentos que no están en Cloud Storage. El modo FULL es útil si quieres borrar automáticamente los documentos que ya no necesitas.

   • AUTO_GENERATE_IDS: es opcional. Especifica si se deben generar automáticamente los IDs de documento. Si se establece en true, los IDs de los documentos se generan en función de un hash de la carga útil. Ten en cuenta que los IDs de documentos generados pueden no ser coherentes en varias importaciones. Si generas IDs automáticamente en varias importaciones, Google recomienda configurar reconciliationMode como FULL para mantener IDs de documentos coherentes.

     Especifica autoGenerateIds solo cuando gcsSource.dataSchema se establece como custom o csv. De lo contrario, se muestra un error INVALID_ARGUMENT. Si no especificas autoGenerateIds o lo configuras en false, debes especificar idField. De lo contrario, los documentos no se importarán.

   • ID_FIELD: es opcional. Especifica qué campos son los IDs de los documentos. En el caso de los documentos de origen de Cloud Storage, idField especifica el nombre en los campos JSON que son IDs de documentos. Por ejemplo, si {"my_id":"some_uuid"} es el campo de ID de documento en uno de tus documentos, especifica "idField":"my_id". Esto identifica todos los campos JSON con el nombre "my_id" como IDs de documentos.

     Especifica este campo solo cuando: (1) gcsSource.dataSchema esté configurado como custom o csv, y (2) auto_generate_ids esté configurado como false o no se especifique. De lo contrario, se muestra un error INVALID_ARGUMENT.

     Ten en cuenta que el valor del campo JSON de Cloud Storage debe ser de tipo cadena, debe tener entre 1 y 63 caracteres y debe cumplir con la RFC-1034. De lo contrario, no se importarán los documentos.

     Ten en cuenta que el nombre del campo JSON especificado por id_field debe ser de tipo cadena, debe tener entre 1 y 63 caracteres y debe cumplir con la RFC-1034. De lo contrario, no se importarán los documentos.

C#

Para obtener más información, consulta la documentación de referencia de la API de C# del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Go del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Java del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Node.js del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

/**
 * 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

Para obtener más información, consulta la documentación de referencia de la API de Python del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Para obtener más información, consulta la documentación de referencia de la API de Ruby del compilador de agentes de Vertex AI.

Para autenticarte en Vertex AI Agent Builder, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

En este ejemplo, se transfieren datos no estructurados de BigQuery o Cloud Storage a un almacén de datos existente.

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

Próximos pasos

• Para conectar tu almacén de datos a una app, crea una app y selecciona tu almacén de datos siguiendo los pasos que se indican en Cómo crear una app de recomendaciones genéricas.

• Para obtener una vista previa de cómo aparecen tus recomendaciones después de configurar la app y el almacén de datos, consulta Obtén recomendaciones.

Sube datos JSON estructurados con la API

Para subir directamente un documento o objeto JSON con la API, sigue estos pasos.

Antes de importar tus datos, prepáralos para la transferencia.

REST

Para usar la línea de comandos y crear un almacén de datos y, luego, importar datos JSON estructurados, sigue estos pasos:

1. Crea un almacén de datos.

   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"]
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: Es el ID del almacén de datos de recomendaciones que deseas crear. Este ID solo puede contener letras en minúscula, dígitos, guiones bajos y guiones.
   • DATA_STORE_DISPLAY_NAME: Es el nombre visible del almacén de datos de recomendaciones que deseas crear.

2. Opcional: Proporciona tu propio esquema. Cuando proporcionas un esquema, por lo general, obtienes mejores resultados. Para obtener más información, consulta Proporciona o detecta automáticamente un esquema.

   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
   }'
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID de tu Google Cloud proyecto.
   • DATA_STORE_ID: El ID del almacén de datos de recomendaciones.

   • JSON_SCHEMA_OBJECT: Tu esquema JSON como objeto JSON, por ejemplo:

     {
       "$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. Importa datos estructurados que se ajusten al esquema definido.

   Existen algunos enfoques que puedes usar para subir datos, como los siguientes:

   • Sube un documento 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"
     }'
     

     Reemplaza JSON_DOCUMENT_STRING por el documento JSON como una sola cadena. Debe cumplir con el esquema JSON que proporcionaste en el paso anterior, por ejemplo:

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

   • Sube un objeto 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
     }'
     

     Reemplaza JSON_DOCUMENT_OBJECT por el documento JSON como un objeto JSON. Debe cumplir con el esquema JSON que proporcionaste en el paso anterior, por ejemplo:

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

   • Actualiza con un documento 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"
     }'
     

   • Actualiza con un objeto 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
     }'
     

Próximos pasos

• Para conectar tu almacén de datos a una app, crea una app y selecciona tu almacén de datos siguiendo los pasos que se indican en Cómo crear una app de recomendaciones genéricas.

• Para obtener una vista previa de cómo aparecen tus recomendaciones después de configurar la app y el almacén de datos, consulta Obtén recomendaciones.

Crea un almacén de datos con Terraform

Puedes usar Terraform para crear un almacén de datos vacío. Después de crear el almacén de datos vacío, puedes transferir datos al almacén con la consola de Google Cloud o los comandos de la API.

Si deseas obtener más información para aplicar o quitar una configuración de Terraform, consulta los comandos básicos de Terraform.

Para crear un almacén de datos vacío con Terraform, consulta google_discovery_engine_data_store.