Criar um repositório de dados de recomendações genéricas

Observação: este recurso é uma oferta de pré-lançamento, sujeita aos "Termos das Ofertas de pré-GA" dos Termos específicos de serviço do GCP. Os produtos e recursos pré-GA podem ter suporte limitado, e as mudanças neles podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as descrições da fase de lançamento. Além disso, ao usar esse recurso, você concorda com os Termos e Condições da Prévia da IA generativa ("Termos da prévia"). Para esse recurso, é possível processar dados pessoais conforme descrito no Adendo sobre processamento de dados do Cloud, sujeito às restrições e obrigações aplicáveis no Contrato (conforme definido nos Termos de Pré-lançamento).

Para criar um repositório de dados e transferir dados para recomendações genéricas, acesse a seção da fonte que você planeja usar:

• URLs do site
• BigQuery
• Cloud Storage
• Fazer upload de dados JSON estruturados com a API

URLs de sites

Console

Para usar o console do Google Cloud para criar um armazenamento de dados e indexar dados de um site, siga estas etapas:

1. No Console do Google Cloud, acesse a página Criador de agentes.

   Agent Builder.

2. No menu de navegação, clique em Repositórios de dados.

3. Clique em Novo repositório de dados.

4. Na página Selecione uma fonte de dados, escolha Conteúdo do site.

5. Escolha se você quer ativar a Indexação avançada de sites para esse repositório de dados. Não será possível desativar essa opção depois.

   A indexação avançada de sites oferece recursos adicionais, como resumo de pesquisa, pesquisa com acompanhamento e respostas de extração. A indexação avançada de sites tem um custo adicional e exige que você verifique a propriedade do domínio de qualquer site que você indexar. Para mais informações, consulte Indexação avançada de sites e Preços.

6. No campo Sites a incluir, especifique os URLs dos sites que você quer indexar. Inclua um URL por linha, sem separadores por vírgula.

7. Opcional: no campo Sites a serem excluídos, insira os sites que você quer excluir do app.

8. Clique em Continuar.

9. Insira um nome para o repositório de dados.

10. Selecione um local para o repositório de dados. A indexação avançada de sites deve ser ativada para selecionar um local.

11. Clique em Criar. O Vertex AI Agent Builder cria e exibe seus repositórios de dados na página Repositórios de dados.

12. Para acessar informações sobre seu repositório de dados, clique no nome dele na coluna Nome. Sua página de repositório de dados é exibida.

    Se você ativou a Indexação avançada de sites, um aviso vai aparecer solicitando que você verifique a propriedade do domínio. Se você tiver um déficit de cota (o de páginas nos sites que você especificou excede o "Número de documentos por projeto" cota para seu projeto), e um aviso adicional será exibido solicitando que você faça upgrade da cota. O as etapas a seguir mostram como verificar a propriedade do domínio e fazer o upgrade a cota de ingestão de registros.

13. Para verificar a propriedade do domínio, siga estas etapas:

    1. Clique em Verificar no Google Search Console. A página Welcome to the Google Search Console aparece.
    2. Siga as instruções na tela para verificar um domínio ou um prefixo de URL, dependendo se você está verificando um domínio inteiro ou um prefixo de URL que faz parte de um domínio. Para mais informações, consulte Verificar a propriedade do site na Ajuda do Search Console.
    3. Quando terminar o fluxo de trabalho de verificação de domínio, volte para a Agent Builder e clique em Repositórios de dados no menu de navegação.
    4. Clique no nome do repositório de dados na coluna Nome. Seu repositório de dados é exibida.
    5. Clique em Atualizar status para atualizar os valores na coluna Status. A coluna Status do seu site indica que a indexação está em o progresso.
    6. Repita as etapas de verificação de domínio para cada site que exige a verificação do domínio até que todos iniciem a indexação. Quando a coluna Status de um URL mostra Indexado, os recursos de indexação avançada de sites estão disponíveis para esse URL ou padrão de URL.

14. Para fazer upgrade da sua cota, siga estas etapas:

    1. Clique em Fazer upgrade da cota. O painel API Discovery Engine será exibido, selecione a guia Cotas.
    2. Siga as instruções em Solicitar um limite de cota maior na documentação do Google Cloud. O aumentar é o Número de documentos.
    3. Depois de enviar a solicitação para um limite de cota maior, volte para a página Agent Builder e clique em Repositórios de dados no menu de navegação.
    4. Clique no nome do repositório de dados na coluna Nome. o status; indica que a indexação dos sites que ultrapassaram a cota está em andamento. Quando a coluna Status de um URL mostra Indexado, os recursos de indexação avançada de sites estão disponíveis para esse URL ou padrão de URL.

Próximas etapas

• Para anexar o repositório de dados a um app, crie um app e selecione o repositório de dados seguindo as etapas em Criar um app de recomendações genéricas.

• Para visualizar como suas recomendações aparecem depois que o app e o repositório de dados são configurar, consulte Receba recomendações.

BigQuery

Para ingerir dados do BigQuery, siga as etapas abaixo para criar um repositório de dados e ingerir dados usando o console do Google Cloud ou a API.

Antes de importar seus dados, revise Preparar os dados para ingestão.

Console

Para usar o console do Google Cloud para ingerir dados do BigQuery, siga estas etapas:

1. No Console do Google Cloud, acesse a página Criador de agentes.

   Agent Builder.

2. Acesse a página Repositórios de dados.

3. Clique em Novo repositório de dados.

4. Na página Tipo, selecione BigQuery.

5. No campo Caminho do BigQuery, clique em Procurar, selecione uma tabela que você preparou para ingestão e clique em Selecionar. Se preferir, insira o local da tabela diretamente no caminho do BigQuery. .

6. Selecione o tipo de dados que você está importando.

7. Clique em Continuar.

8. Se você estiver fazendo uma importação única de dados estruturados:

   1. Associe campos a propriedades principais.

   2. Se houver campos importantes ausentes no esquema, use Adicionar novo campo para adicioná-los.

      Para mais informações, consulte Sobre a detecção e edição automáticas.

   3. Clique em Continuar.

9. Escolha uma região para o repositório de dados.

10. Insira um nome para o repositório de dados.

11. Clique em Criar.

12. Para confirmar que o repositório de dados foi criado, acesse a página Repositórios de dados e clique no nome do repositório para conferir os detalhes na página Dados.

13. Para verificar o status do seu processamento, acesse a página Repositórios de dados. e clique no nome do repositório de dados para ver detalhes sobre ele na página Dados. Quando a coluna de status na guia Atividade muda de Em andamento para Importação concluída, a transferência é concluída.

    Dependendo do tamanho dos dados, a ingestão pode demorar minutos ou várias horas.

REST

Para usar a linha de comando e importar dados do BigQuery, siga estas etapas:

1. Crie um repositório de dados.

   Observação: esta etapa é experimental. Se você quiser um procedimento em GA, crie um armazenamento seguindo as etapas de 1 a 4 das instruções do console.

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

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hifens.
   • DATA_STORE_DISPLAY_NAME: o nome de exibição do repositório de dados de recomendações que você quer criar.

2. Opcional: se você estiver fazendo upload de dados estruturados com seu próprio esquema, poderá fornecer o esquema. Quando você fornece o esquema, normalmente obtém resultados melhores. Caso contrário, o esquema é detectado automaticamente. Para mais informações, consulte Fornecer ou detectar automaticamente um 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
   }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações.

   • JSON_SCHEMA_OBJECT: seu esquema JSON como um objeto JSON, por exemplo:

     {
       "$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. Importe dados do BigQuery.

   Se você definiu um esquema, verifique se os dados estão em conformidade com ele.

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

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações.
   • DATASET_ID: o ID do BigQuery. no conjunto de dados.
   • TABLE_ID: o ID da tabela do BigQuery.
     • Se a tabela do BigQuery não estiver em PROJECT_ID, você precisa dar à conta de serviço service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com "Leitor de dados do BigQuery" para o Tabela do BigQuery. Por exemplo, se você importar uma tabela do BigQuery do projeto de origem "123" para ao projeto de destino "456", forneça [e-mail] permissões para a tabela do BigQuery em o projeto "123".
   • DATA_SCHEMA: opcional. Os valores são document e custom. O padrão é document.
     • document: a tabela do BigQuery que você usa precisa estar em conformidade com o esquema padrão do BigQuery fornecido em Preparar dados para transferência. Você pode definir o ID de cada documento, encerrando todos os dados na string jsonData.
     • custom: qualquer esquema de tabela do BigQuery é aceito, e as recomendações geram automaticamente os IDs de cada documento importado.
   • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erro sobre a importação, por exemplo, gs://<your-gcs-bucket>/directory/import_errors. Recomendações do Google deixando este campo em branco para que as Recomendações criar automaticamente um diretório temporário.
   • RECONCILIATION_MODE: opcional. Os valores são FULL e INCREMENTAL. O padrão é INCREMENTAL. Como especificar INCREMENTAL causa uma atualização incremental dos dados do BigQuery ao seu repositório de dados. Isso faz uma operação de inserção, que adiciona novos documentos e substitui os documentos existentes por documentos atualizados com o mesmo ID. Especificar FULL causa uma realocação total do documentos em seu repositório de dados. Em outras palavras, documentos novos e atualizados são adicionados ao repositório de dados, e os que não estão no BigQuery são removidos. O modo FULL é útil se você quiser excluir automaticamente documentos que não são mais necessários.

   • AUTO_GENERATE_IDS: opcional. Especifica se os IDs de documentos serão gerados automaticamente. Se definido como true, os IDs dos documentos são gerados com base em um hash do payload. Os IDs de documento gerados podem não permanecer consistentes em várias importações. Se você gerar IDs automaticamente em várias importações, o Google recomenda definir reconciliationMode como FULL para manter os IDs de documentos consistentes.

     Especifique autoGenerateIds apenas quando bigquerySource.dataSchema for Defina como custom. Caso contrário, será exibido um erro INVALID_ARGUMENT. retornados. Se você não especificar autoGenerateIds ou defini-lo como false, é preciso especificar idField. Caso contrário, a importação dos documentos vai falhar.

   • ID_FIELD: opcional. Especifica quais campos são os IDs de documentos. Para arquivos de origem do BigQuery, idField indica o nome da coluna na tabela do BigQuery que contém os IDs dos documentos.

     Especifique idField apenas quando: (1) bigquerySource.dataSchema estiver definido como custom e (2) auto_generate_ids está definido como false ou é não especificado. Caso contrário, será retornado um erro INVALID_ARGUMENT.

     O valor do nome da coluna do BigQuery precisa ser do tipo string, ter entre 1 e 63 caracteres e estar em conformidade com o RFC-1034. Caso contrário, o documentos não são importados.

C#

Para mais informações, consulte a API Vertex AI Agent Builder C# documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou do Cloud Storage em um repositório de dados.

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 mais informações, consulte a documentação de referência da API Go do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

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 mais informações, consulte a API Vertex AI Agent Builder Java documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

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 mais informações, consulte a documentação de referência da API Node.js do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

/**
 * 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 mais informações, consulte a documentação de referência da API Python do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

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 mais informações, consulte a API Vertex AI Agent Builder Ruby documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

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óximas etapas

• Para anexar o repositório de dados a um app, crie um app e selecione o repositório de dados seguindo as etapas em Criar um app de recomendações genéricas.

• Para conferir como as recomendações vão aparecer depois que o app e o repositório de dados forem configurados, consulte Receber recomendações.

Cloud Storage

Para transferir dados do Cloud Storage, siga as etapas abaixo para criar um repositório de dados e fazer a transferência usando o console do Google Cloud ou a API.

Antes de importar seus dados, consulte Preparar dados para ingestão.

Console

Para usar o console para ingerir dados de um bucket do Cloud Storage, siga estas instruções etapas:

1. No Console do Google Cloud, acesse a página Criador de agentes.

   Agent Builder.

2. Acesse a página Repositórios de dados.

3. Clique em Novo repositório de dados.

4. Na página Tipo, selecione Cloud Storage.

5. Na seção Selecionar uma pasta ou um arquivo para importar, selecione Pasta ou Arquivo.

6. Clique em Procurar e escolha os dados que você preparou para ingestão. Em seguida, clique em Selecionar. Se preferir, insira o local diretamente no campo gs://.

7. Selecione o tipo de dados que você está importando.

8. Clique em Continuar.

9. Se você estiver fazendo uma importação única de dados estruturados:

   1. Associe campos a propriedades principais.

   2. Se houver campos importantes faltando no esquema, use Adicionar novo para adicioná-las.

      Para mais informações, consulte Sobre a detecção automática e editar.

   3. Clique em Continuar.

10. Escolha uma região para o repositório de dados.

11. Insira um nome para o repositório de dados.

12. Clique em Criar.

13. Para confirmar que o repositório de dados foi criado, acesse a página Repositórios de dados e clique no nome do repositório para conferir os detalhes na página Dados.

14. Para verificar o status do seu processamento, acesse a página Repositórios de dados. e clique no nome do repositório de dados para ver detalhes sobre ele na página Dados. Quando a coluna de status na guia Atividade muda de Em andamento para Importação concluída, a transferência é concluída.

    Dependendo do tamanho dos dados, a ingestão pode demorar minutos ou várias horas.

REST

Usar a linha de comando para criar um repositório de dados e ingerir dados de Cloud Storage, siga estas etapas:

1. Criar um repositório de dados.

   Observação: esta etapa é experimental. Se você quiser um procedimento em GA, crie um armazenamento seguindo as etapas de 1 a 4 das instruções do console.

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

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hifens.
   • DATA_STORE_DISPLAY_NAME: o nome de exibição do repositório de dados de recomendações que você quer criar.

2. Importa dados do 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"
       }
     }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações.

   • INPUT_FILE_PATTERN: um padrão de arquivo no Cloud Storage que contêm seus documentos.

     Para dados estruturados ou não estruturados com metadados para documentos não estruturados, um exemplo de padrão de arquivo de entrada é gs://<your-gcs-bucket>/directory/object.json ou um padrão que corresponde a um ou mais arquivos, como gs://<your-gcs-bucket>/directory/*.json.

     Para documentos não estruturados, um exemplo é gs://<your-gcs-bucket>/directory/*.pdf: Cada arquivo com correspondência pelo padrão se torna um documento.

     Se <your-gcs-bucket> não estiver em PROJECT_ID, você precisará conceder à conta de serviço service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com as permissões de "Leitor de objetos do Storage" para o bucket do Cloud Storage. Para exemplo, se você estiver importando um bucket do Cloud Storage de projeto de origem "123" ao projeto de destino "456", forneça [e-mail] no bucket do Cloud Storage no projeto "123".

   • DATA_SCHEMA: opcional. Os valores são document, custom, csv e content. O padrão é document.

     • document: faz upload de dados não estruturados com metadados para e não estruturados. Cada linha do arquivo precisa seguir um dos seguintes formatos. É possível definir o 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: faz upload do JSON para documentos estruturados. Os dados são e são organizados de acordo com um esquema. É possível especificar o esquema. Caso contrário, ele será detectado automaticamente. Você pode colocar a string JSON do documento em um formato consistente diretamente em cada linha, e o Recommendations gera automaticamente os IDs para cada documento importado.

     • content: faça upload de documentos não estruturados (PDF, HTML, DOC, TXT, PPTX). O ID de cada documento é gerado automaticamente como os primeiros 128 bits de SHA256(GCS_URI) codificados como uma string hexadecimal. É possível especificar vários padrões de arquivo de entrada, desde que os arquivos correspondentes não excedam o limite de 100 mil arquivos.

     • csv: inclui uma linha de cabeçalho no arquivo CSV. com cada cabeçalho mapeado para um campo do documento. Especifique o caminho o arquivo CSV usando o campo inputUris.

   • ERROR_DIRECTORY: opcional. Um diretório do Cloud Storage para informações de erro sobre a importação, por exemplo, gs://<your-gcs-bucket>/directory/import_errors. O Google recomenda deixar esse campo em branco para permitir que o Recommendations crie automaticamente um diretório temporário.

   • RECONCILIATION_MODE: opcional. Os valores são FULL e INCREMENTAL. O padrão é INCREMENTAL. Como especificar INCREMENTAL causa uma atualização incremental de dados do Cloud Storage para seu repositório de dados. Isso faz uma operação de inserção, que adiciona novos documentos e substitui os documentos existentes por atualizados com os mesmos ID. Especificar FULL causa uma realocação total dos documentos no seu repositório de dados. Em outras palavras, documentos novos e atualizados são adicionados à loja de dados, e aqueles que não estão no Cloud Storage são removidos dela. O modo FULL é útil se você quiser para excluir automaticamente os documentos desnecessários.

   • AUTO_GENERATE_IDS: opcional. Especifica se deve automaticamente os IDs de documentos. Se definido como true, os IDs dos documentos são gerados com base em um hash do payload. Observe que gerados IDs de documentos podem não permanecer consistentes em várias importações. Se você gerar IDs automaticamente em várias importações, o Google recomenda definir reconciliationMode como FULL para manter os IDs de documentos consistentes.

     Especifique autoGenerateIds somente quando gcsSource.dataSchema estiver definido como custom ou csv. Caso contrário, um erro INVALID_ARGUMENT será retornado. Se você não especificar autoGenerateIds ou definir como false, será necessário especificar idField. Caso contrário, a importação de documentos vai falhar.

   • ID_FIELD: opcional. Especifica quais campos são os IDs de documentos. Para documentos de origem do Cloud Storage, idField especifica o nome nos campos JSON que são IDs de documentos. Para exemplo, se {"my_id":"some_uuid"} for o campo de ID do documento em uma dos documentos, especifique "idField":"my_id". Isso identifica todos os campos JSON com o nome "my_id" como IDs de documentos.

     Especifique esse campo apenas quando: (1) gcsSource.dataSchema estiver definido como custom ou csv, e (2) auto_generate_ids está definido como false ou não foi especificado. Caso contrário, será retornado um erro INVALID_ARGUMENT.

     O valor do campo JSON do Cloud Storage precisa ser do tipo string, ter entre 1 e 63 caracteres e estar em conformidade com o RFC-1034. Caso contrário, o documentos não são importados.

     O nome do campo JSON especificado por id_field precisa ser string, deve ter entre 1 e 63 caracteres e deve obedecer para RFC-1034. Caso contrário, a importação dos documentos vai falhar.

C#

Para mais informações, consulte a documentação de referência da API C# do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou do Cloud Storage em um repositório de dados.

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 mais informações, consulte a documentação de referência da API Go do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

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 mais informações, consulte a API Vertex AI Agent Builder Java documentação de referência.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou do Cloud Storage em um repositório de dados.

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 mais informações, consulte a documentação de referência da API Node.js do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou o Cloud Storage em um repositório de dados atual.

/**
 * 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 mais informações, consulte a documentação de referência da API Python do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou do Cloud Storage em um repositório de dados.

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 mais informações, consulte a documentação de referência da API Ruby do Vertex AI Agent Builder.

Para autenticar no Vertex AI Agent Builder, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Este exemplo ingere dados não estruturados do BigQuery ou do Cloud Storage em um repositório de dados.

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óximas etapas

• Para anexar seu repositório de dados a um app, crie um app e selecione o repositório seguindo as etapas Crie um app de recomendações genéricas.

• Para conferir como as recomendações vão aparecer depois que o app e o repositório de dados forem configurados, consulte Receber recomendações.

Fazer upload de dados JSON estruturados com a API

Para fazer upload direto de um documento ou objeto JSON usando a API, siga estas etapas.

Antes de importar seus dados, Preparar os dados para ingestão.

REST

Para usar a linha de comando para criar um repositório de dados e importar dados JSON estruturados, siga estas etapas:

1. Criar um repositório de dados.

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

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hifens.
   • DATA_STORE_DISPLAY_NAME: o nome de exibição do repositório de dados de recomendações que você quer criar.

2. Opcional: forneça seu próprio esquema. Quando você fornece um esquema, normalmente obtém resultados melhores. Para mais informações, consulte Fornecer ou detectar automaticamente um 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
   }'
   

   Substitua:

   • PROJECT_ID: o ID do seu projeto do Google Cloud.
   • DATA_STORE_ID: o ID do repositório de dados de recomendações.

   • JSON_SCHEMA_OBJECT: seu esquema JSON como um objeto JSON, por exemplo:

     {
       "$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. Importe dados estruturados que estejam em conformidade com o esquema definido.

   Há algumas abordagens que podem ser usadas para fazer o upload de dados, incluindo:

   • Faça upload de um 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"
     }'
     

     Substitua JSON_DOCUMENT_STRING pelo documento JSON como uma única string. Ele precisa estar em conformidade com o esquema JSON que você fornecidos na etapa anterior, por exemplo:

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

   • Faça upload de um 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
     }'
     

     Substitua JSON_DOCUMENT_OBJECT pelo documento JSON como objeto JSON. Ele precisa estar em conformidade com o esquema JSON que você forneceu na etapa anterior, por exemplo:

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

   • Atualize com um 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"
     }'
     

   • Atualize com um 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óximas etapas

• Para anexar seu repositório de dados a um app, crie um app e selecione o repositório seguindo as etapas Crie um app de recomendações genéricas.

• Para visualizar como suas recomendações aparecem depois que o app e o repositório de dados são configurar, consulte Receba recomendações.

Criar um repositório de dados usando o Terraform

É possível usar o Terraform para criar um repositório de dados vazio. Depois que o repositório de dados vazio é criado, é possível transferir dados para ele usando o console do Google Cloud ou comandos de API.

Para saber como aplicar ou remover uma configuração do Terraform, consulte Comandos básicos do Terraform.

Para criar um repositório de dados vazio usando o Terraform, consulte google_discovery_engine_data_store.