Creare un datastore di suggerimenti generici

Per creare un datastore e importare i dati per i consigli generici, vai alla sezione relativa all'origine che prevedi di utilizzare:

URL del sito web

Console

Per utilizzare la console Google Cloud per creare un datastore e indicizzare i dati di un sito web, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

  2. Nel menu di navigazione, fai clic su Datastore.

  3. Fai clic su Nuovo datastore.

  4. Nella pagina Seleziona un'origine dati, scegli Contenuti dei siti web.

  5. Scegli se attivare l'indicizzazione avanzata dei siti web per questo datastore. Questa opzione non può essere disattivata in un secondo momento.

    L'indicizzazione avanzata del sito web offre funzionalità aggiuntive come il riepilogo della ricerca, la ricerca con follow-up e le risposte estrattive. L'indicizzazione avanzata dei siti web comporta costi aggiuntivi e richiede di verificare la proprietà del dominio per tutti i siti web che indicizzi. Per ulteriori informazioni, consulta la sezione Indicizzazione avanzata dei siti web e Prezzi.

  6. Nel campo Siti da includere, specifica gli URL dei siti web che vuoi indicizzare. Includi un URL per riga, senza virgole.

  7. (Facoltativo) Nel campo Siti da escludere, inserisci i siti web che vuoi escludere dalla tua app.

  8. Fai clic su Continua.

  9. Inserisci un nome per il tuo datastore.

  10. Seleziona una posizione per il tuo datastore. Per selezionare una località, l'indicizzazione avanzata dei siti web deve essere attivata.

  11. Fai clic su Crea. Vertex AI Agent Builder crea il datastore e li mostra nella pagina Datastore.

  12. Per visualizzare le informazioni sul tuo datastore, fai clic sul nome del datastore nella colonna Nome. Viene visualizzata la pagina del tuo datastore.

    Se hai attivato l'indicizzazione avanzata del sito web, viene visualizzato un avviso che ti chiede di verificare la proprietà del tuo dominio. Se hai un disavanzo di quota (il numero di pagine dei siti web specificati supera la quota "Numero di documenti per progetto" per il tuo progetto), viene visualizzato un avviso aggiuntivo che ti chiede di eseguire l'upgrade della quota. I seguenti passaggi mostrano come verificare la proprietà del dominio ed eseguire l'upgrade della quota.

  13. Per verificare la proprietà del dominio, segui questi passaggi:

    1. Fai clic su Verifica in Google Search Console. Viene visualizzata la pagina Ti diamo il benvenuto in Google Search Console.
    2. Segui le istruzioni sullo schermo per verificare un dominio o un prefisso URL, a seconda che tu stia verificando un intero dominio o un prefisso URL che fa parte di un dominio. Per ulteriori informazioni, consulta la sezione Verificare la proprietà del sito nella Guida di Search Console.
    3. Al termine del flusso di lavoro di verifica del dominio, torna alla pagina Agent Builder e fai clic su Data Store nel menu di navigazione.
    4. Fai clic sul nome del tuo datastore nella colonna Nome. Viene visualizzata la pagina del datastore.
    5. Fai clic su Aggiorna stato per aggiornare i valori nella colonna Stato. La colonna Stato per il tuo sito web indica che l'indicizzazione è in corso.
    6. Ripeti i passaggi di verifica del dominio per ogni sito web che richiede la verifica del dominio finché non inizieranno a essere indicizzati tutti. Quando la colonna Stato per un URL mostra Indicizzato, le funzionalità di indicizzazione avanzata del sito web sono disponibili per quell'URL o pattern URL.

  14. Per eseguire l'upgrade della quota:

    1. Fai clic su Esegui upgrade della quota. Viene visualizzato il riquadro API Discovery Engine con la scheda Quote selezionata.
    2. Segui le istruzioni riportate in Richiedere un limite di quota più alto nella documentazione di Google Cloud. La quota da aumentare è Numero di documenti.
    3. Dopo aver inviato la richiesta di un limite di quota più elevato, torna alla pagina Agent Builder e fai clic su Datastore nel menu di navigazione.
    4. Fai clic sul nome del tuo datastore nella colonna Nome. La colonna Stato indica che l'indicizzazione è in corso per i siti web che hanno superato la quota. Quando la colonna Stato per un URL mostra Indicizzato, le funzionalità di indicizzazione avanzata del sito web sono disponibili per quell'URL o pattern URL.

Passaggi successivi

  • Per collegare il tuo datastore a un'app, crea un'app e seleziona il datastore seguendo i passaggi descritti in Creare un'app di suggerimenti generica.

  • Per visualizzare l'anteprima di come vengono visualizzati i consigli dopo la configurazione dell'app e dell'datastore, consulta Ricevere consigli.

BigQuery

Per importare i dati da BigQuery, segui questi passaggi per creare un datastore e importare i dati utilizzando la console Google Cloud o l'API.

Prima di importare i dati, consulta Preparare i dati per l'importazione.

Console

Per utilizzare la console Google Cloud per importare i dati da BigQuery:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

  2. Vai alla pagina Datastore.

  3. Fai clic su Nuovo datastore.

  4. Nella pagina Tipo, seleziona BigQuery.

  5. Nel campo Percorso BigQuery, fai clic su Sfoglia, seleziona una tabella che hai preparato per l'importazione e poi fai clic su Seleziona. In alternativa, inserisci la posizione della tabella direttamente nel campo Percorso BigQuery.

  6. Seleziona il tipo di dati che stai importando.

  7. Fai clic su Continua.

  8. Se esegui l'importazione una tantum dei dati strutturati:

    1. Mappa i campi alle proprietà chiave.

    2. Se nello schema mancano campi importanti, utilizza Aggiungi nuovo campo per aggiungerli.

      Per saperne di più, consulta Informazioni sul rilevamento automatico e sull'editing.

    3. Fai clic su Continua.

  9. Scegli una regione per il tuo datastore.

  10. Inserisci un nome per il tuo datastore.

  11. Fai clic su Crea.

  12. Per verificare che il datastore sia stato creato, vai alla pagina Datastore e fai clic sul nome del datastore per visualizzarne i dettagli nella pagina Dati.

  13. Per controllare lo stato dell'importazione, vai alla pagina Datastore e fai clic sul nome del datastore per visualizzarne i dettagli nella pagina Dati. Quando la colonna dello stato nella scheda Attività passa da In corso a Importazione completata, l'importazione è completata.

    A seconda delle dimensioni dei dati, l'importazione può richiedere diversi minuti o diverse ore.

REST

Per utilizzare la riga di comando per creare un datastore e importare i dati da BigQuery, segui questi passaggi:

  1. Crea un datastore.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.
    • DATA_STORE_DISPLAY_NAME: il nome visualizzato del datastore dei consigli che vuoi creare.

  2. (Facoltativo) Se carichi dati strutturati con il tuo schema, puoi fornire lo schema. Quando fornisci lo schema, in genere ottieni risultati migliori. In caso contrario, lo schema viene rilevato automaticamente. Per ulteriori informazioni, consulta Fornire o rilevare automaticamente uno schema.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli.

    • JSON_SCHEMA_OBJECT: lo schema JSON come oggetto JSON, ad esempio:

      {
  "$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 i dati da BigQuery.

    Se hai definito uno schema, assicurati che i dati siano conformi.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli.
    • DATASET_ID: l'ID del set di dati BigQuery.
    • TABLE_ID: l'ID della tabella BigQuery.
      • Se la tabella BigQuery non è in PROJECT_ID, devi concedere all'account di servizio service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com l'autorizzazione "Visualizzatore dei dati BigQuery" per la tabella BigQuery. Ad esempio, se importi una tabella BigQuery dal progetto di origine "123" al progetto di destinazione "456", concedi service-456@gcp-sa-discoveryengine.iam.gserviceaccount.com le autorizzazioni per la tabella BigQuery nel progetto "123".
    • DATA_SCHEMA: facoltativo. I valori sono document e custom. Il valore predefinito è document.
      • document: la tabella BigQuery da utilizzare deve essere conforme allo schema BigQuery predefinito fornito in Preparare i dati per l'importazione. Puoi definire autonomamente l'ID di ogni documento, inserendo tutti i dati nella stringa jsonData.
      • custom: è accettato qualsiasi schema di tabella BigQuery e Recommendations genera automaticamente gli ID per ogni documento importato.
    • ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione, ad esempio gs://<your-gcs-bucket>/directory/import_errors. Google consiglia di lasciare vuoto questo campo per consentire a Consigli di creare automaticamente una directory temporanea.
    • RECONCILIATION_MODE: facoltativo. I valori sono FULL e INCREMENTAL. Il valore predefinito è INCREMENTAL. La specifica di INCREMENTAL provoca un aggiornamento incrementale dei dati da BigQuery al tuo datastore. Viene eseguita un'operazione di upsert, che aggiunge nuovi documenti e sostituisce quelli esistenti con documenti aggiornati con lo stesso ID. Se specifichi FULL, viene eseguita una rebase completa dei documenti nel tuo datastore. In altre parole, i documenti nuovi e aggiornati vengono aggiunti al tuo datastore e quelli non presenti in BigQuery vengono rimossi. La modalità FULL è utile se vuoi eliminare automaticamente i documenti che non ti servono più.

    • AUTO_GENERATE_IDS: facoltativo. Specifica se generare automaticamente gli ID documento. Se impostato su true, gli ID documento vengono generati in base a un hash del payload. Tieni presente che gli ID documento generati potrebbero non rimanere coerenti in più importazioni. Se generi automaticamente gli ID in più importazioni, Google consiglia vivamente di impostare reconciliationMode su FULL per mantenere ID documento coerenti.

      Specifica autoGenerateIds solo quando bigquerySource.dataSchema è impostato su custom. In caso contrario, viene restituito un errore INVALID_ARGUMENT. Se non specifichi autoGenerateIds o lo imposti su false, devi specificare idField. In caso contrario, l'importazione dei documenti non andrà a buon fine.

    • ID_FIELD: facoltativo. Specifica quali campi sono gli ID documento. Per i file di origine BigQuery, idField indica il nome della colonna nella tabella BigQuery che contiene gli ID documento.

      Specifica idField solo se: (1) bigquerySource.dataSchema è impostato su custom e (2) auto_generate_ids è impostato su false o non è specificato. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

      Il valore del nome della colonna BigQuery deve essere di tipo stringa, deve essere compreso tra 1 e 63 caratteri e deve essere conforme a RFC-1034. In caso contrario, l'importazione dei documenti non andrà a buon fine.

C#

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.


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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.



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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Passaggi successivi

  • Per collegare il tuo datastore a un'app, crea un'app e seleziona il datastore seguendo i passaggi descritti in Creare un'app di suggerimenti generica.

  • Per visualizzare l'anteprima di come vengono visualizzati i consigli dopo la configurazione dell'app e dell'datastore, consulta Ricevere consigli.

Cloud Storage

Per importare i dati da Cloud Storage, segui questi passaggi per creare un datastore e importare i dati utilizzando la console Google Cloud o l'API.

Prima di importare i dati, consulta Preparare i dati per l'importazione.

Console

Per utilizzare la console per importare i dati da un bucket Cloud Storage, segui questi passaggi:

  1. Nella console Google Cloud, vai alla pagina Agent Builder.

    Agent Builder

  2. Vai alla pagina Datastore.

  3. Fai clic su Nuovo datastore.

  4. Nella pagina Tipo, seleziona Cloud Storage.

  5. Nella sezione Seleziona una cartella o un file da importare, seleziona Cartella o File.

  6. Fai clic su Sfoglia e scegli i dati che hai preparato per l'importazione, poi fai clic su Seleziona. In alternativa, inserisci la località direttamente nel campo gs://.

  7. Seleziona il tipo di dati che stai importando.

  8. Fai clic su Continua.

  9. Se esegui l'importazione una tantum dei dati strutturati:

    1. Mappa i campi alle proprietà chiave.

    2. Se nello schema mancano campi importanti, utilizza Aggiungi nuovo campo per aggiungerli.

      Per saperne di più, consulta Informazioni sul rilevamento automatico e sull'editing.

    3. Fai clic su Continua.

  10. Scegli una regione per il tuo datastore.

  11. Inserisci un nome per il tuo datastore.

  12. Fai clic su Crea.

  13. Per verificare che il datastore sia stato creato, vai alla pagina Datastore e fai clic sul nome del datastore per visualizzarne i dettagli nella pagina Dati.

  14. Per controllare lo stato dell'importazione, vai alla pagina Datastore e fai clic sul nome del datastore per visualizzarne i dettagli nella pagina Dati. Quando la colonna dello stato nella scheda Attività passa da In corso a Importazione completata, l'importazione è completata.

    A seconda delle dimensioni dei dati, l'importazione può richiedere diversi minuti o diverse ore.

REST

Per utilizzare la riga di comando per creare un datastore e importare i dati da Cloud Storage:

  1. Crea un datastore.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.
    • DATA_STORE_DISPLAY_NAME: il nome visualizzato del datastore dei consigli che vuoi creare.

  2. Importa i dati da 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"
    }
  }'

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli.

    • INPUT_FILE_PATTERN: un pattern di file in Cloud Storage contenente i tuoi documenti.

      Per i dati strutturati o per i dati non strutturati con metadati per i documenti non strutturati, un esempio di pattern del file di input è gs://<your-gcs-bucket>/directory/object.json o un pattern corrispondente a uno o più file, ad esempio gs://<your-gcs-bucket>/directory/*.json.

      Per i documenti non strutturati, un esempio è gs://<your-gcs-bucket>/directory/*.pdf. Ogni file corrispondente al pattern diventa un documento.

      Se <your-gcs-bucket> non è in PROJECT_ID, devi concedere all'account di servizio service-<project number>@gcp-sa-discoveryengine.iam.gserviceaccount.com le autorizzazioni "Visualizzatore oggetti Storage" per il bucket Cloud Storage. Ad esempio, se importi un bucket Cloud Storage dal progetto di origine "123" al progetto di destinazione "456", concedi le autorizzazioni service-456@gcp-sa-discoveryengine.iam.gserviceaccount.com al bucket Cloud Storage nel progetto "123".

    • DATA_SCHEMA: facoltativo. I valori sono document, custom, csv e content. Il valore predefinito è document.

      • document: carica i dati non strutturati con i metadati per i documenti non strutturati. Ogni riga del file deve seguire uno dei seguenti formati. Puoi definire l'ID di ogni 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: carica il file JSON per i documenti strutturati. I dati sono organizzati in base a uno schema. Puoi specificare lo schema; altrimenti viene rilevato automaticamente. Puoi inserire la stringa JSON del documento in un formato coerente direttamente in ogni riga e Recommendations genera automaticamente gli ID per ogni documento importato.

      • content: carica i documenti non strutturati (PDF, HTML, DOC, TXT, PPTX). L'ID di ogni documento viene generato automaticamente come primi 128 bit di SHA256(GCS_URI) codificati come stringa esadecimale. Puoi specificare più pattern di file di input, a condizione che i file corrispondenti non superino il limite di 100.000 file.

      • csv: includi una riga di intestazione nel file CSV, con ogni intestazione mappata a un campo del documento. Specifica il percorso del file CSV utilizzando il campo inputUris.

    • ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relativi all'importazione, ad esempio gs://<your-gcs-bucket>/directory/import_errors. Google consiglia di lasciare vuoto questo campo per consentire ai consigli di creare automaticamente una directory temporanea.

    • RECONCILIATION_MODE: facoltativo. I valori sono FULL e INCREMENTAL. Il valore predefinito è INCREMENTAL. La specifica di INCREMENTAL provoca un aggiornamento incrementale dei dati da Cloud Storage al tuo datastore. Viene eseguita un'operazione di upsert, che aggiunge nuovi documenti e sostituisce quelli esistenti con documenti aggiornati con lo stesso ID. Se specifichi FULL, viene eseguita una rebase completa dei documenti nel datastore. In altre parole, i documenti nuovi e aggiornati vengono aggiunti al tuo datastore e quelli che non sono presenti in Cloud Storage vengono rimossi. La modalità FULL è utile se vuoi eliminare automaticamente i documenti che non ti servono più.

    • AUTO_GENERATE_IDS: facoltativo. Specifica se generare automaticamente gli ID documento. Se impostato su true, gli ID documento vengono generati in base a un hash del payload. Tieni presente che gli ID documento generati potrebbero non rimanere coerenti in più importazioni. Se generi automaticamente gli ID in più importazioni, Google consiglia vivamente di impostare reconciliationMode su FULL per mantenere gli ID documento coerenti.

      Specifica autoGenerateIds solo quando gcsSource.dataSchema è impostato su custom o csv. In caso contrario, viene restituito un errore INVALID_ARGUMENT. Se non specifichi autoGenerateIds o lo imposti su false, devi specificare idField. In caso contrario, l'importazione dei documenti non andrà a buon fine.

    • ID_FIELD: facoltativo. Specifica quali campi sono gli ID documento. Per i documenti di origine Cloud Storage, idField specifica il nome nei campi JSON che sono gli ID documento. Ad esempio, se {"my_id":"some_uuid"} è il campo ID documento in uno dei tuoi documenti, specifica "idField":"my_id". In questo modo, tutti i campi JSON con il nome "my_id" vengono identificati come ID documento.

      Specifica questo campo solo se: (1) gcsSource.dataSchema è impostato su custom o csv e (2) auto_generate_ids è impostato su false o non è specificato. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

      Tieni presente che il valore del campo JSON di Cloud Storage deve essere di tipo stringa, deve essere compreso tra 1 e 63 caratteri e deve essere conforme a RFC-1034. In caso contrario, l'importazione dei documenti non andrà a buon fine.

      Tieni presente che il nome del campo JSON specificato da id_field deve essere di tipo stringa, deve essere compreso tra 1 e 63 caratteri e deve essere conforme allo standard RFC-1034. In caso contrario, l'importazione dei documenti non andrà a buon fine.

C#

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Go Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.


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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.



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

Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Vertex AI Agent Builder.

Per autenticarti in Vertex AI Agent Builder, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

Questo sample importa dati non strutturati da BigQuery o Cloud Storage in un datastore esistente.

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

Passaggi successivi

  • Per collegare il tuo datastore a un'app, crea un'app e seleziona il datastore seguendo i passaggi descritti in Creare un'app di suggerimenti generica.

  • Per visualizzare l'anteprima di come vengono visualizzati i consigli dopo la configurazione dell'app e dell'datastore, consulta Ricevere consigli.

Carica dati JSON strutturati con l'API

Per caricare direttamente un documento o un oggetto JSON utilizzando l'API, segui questi passaggi.

Prima di importare i dati, preparali per l'importazione.

REST

Per utilizzare la riga di comando per creare un datastore e importare dati JSON strutturati:

  1. Crea un datastore.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.
    • DATA_STORE_DISPLAY_NAME: il nome visualizzato del datastore dei consigli che vuoi creare.

  2. (Facoltativo) Fornisci il tuo schema. Quando fornisci uno schema, in genere ottieni risultati migliori. Per saperne di più, consulta Fornire o rilevare automaticamente uno schema.

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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID del datastore dei consigli.

    • JSON_SCHEMA_OBJECT: lo schema JSON come oggetto JSON, ad esempio:

      {
  "$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 dati strutturati conformi allo schema definito.

    Esistono diversi approcci che puoi utilizzare per caricare i dati, tra cui:

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

      Sostituisci JSON_DOCUMENT_STRING con il documento JSON come singola stringa. Deve essere conforme allo schema JSON fornito nel passaggio precedente, ad esempio:

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

    • Carica un oggetto 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
}'

      Sostituisci JSON_DOCUMENT_OBJECT con il documento JSON come oggetto JSON. Deve essere conforme allo schema JSON fornito nel passaggio precedente, ad esempio:

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

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

    • Aggiorna con un oggetto 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
}'

Passaggi successivi

  • Per collegare il tuo datastore a un'app, crea un'app e seleziona il datastore seguendo i passaggi descritti in Creare un'app di consigli generica.

  • Per visualizzare l'anteprima di come vengono visualizzati i consigli dopo la configurazione dell'app e dell'datastore, consulta Ricevere consigli.

Creare un datastore utilizzando Terraform

Puoi utilizzare Terraform per creare un datastore vuoto. Dopo aver creato il datastore vuoto, puoi importare i dati utilizzando i comandi della console o dell'API Google Cloud.

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base.

Per creare un datastore vuoto utilizzando Terraform, consulta google_discovery_engine_data_store.