Questa pagina è stata tradotta dall'API Cloud Translation.

Aggiorna uno schema

Puoi aggiornare lo schema per qualsiasi dato contenente dati che supportano uno schema, come dati strutturati, dati del sito web con dati strutturati o altri dati non strutturati con metadati.

Puoi aggiornare lo schema nella console Google Cloud o utilizzando il metodo dell'API schemas.patch. L'aggiornamento dello schema di un sito web è supportato solo tramite l'API REST.

Per aggiornare lo schema, puoi aggiungere nuovi campi, modificare le annotazioni indicizzabili, cercabili e recuperabili per un campo o contrassegnare un campo come proprietà chiave, ad esempio title, uri e description.

Aggiorna lo schema

Puoi aggiornare lo schema nella console Google Cloud o utilizzando l'API.

Console

Per aggiornare uno schema nella console Google Cloud:

Esamina la sezione Requisiti e limitazioni per verificare che l'aggiornamento dello schema sia valido.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzati, recuperabili, con tabelle dinamiche, disponibili per la ricerca o compilabili), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Verifica di aver completato l'importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per la modifica.
Nella console Google Cloud, vai alla pagina Agent Builder.

Agent Builder
Nel menu di navigazione, fai clic su Datastore.
Nella colonna Nome, fai clic sul datastore con lo schema da aggiornare.
Fai clic sulla scheda Schema per visualizzare lo schema dei dati.

Questa scheda potrebbe essere vuota se è la prima volta che modifichi i campi.
Fai clic sul pulsante Edit (Modifica).
Aggiorna lo schema:
- Mappa le proprietà chiave:nella colonna Proprietà chiave dello schema, seleziona una proprietà chiave a cui mappare un campo. Ad esempio, se un campo chiamato details contiene sempre la descrizione di un documento, mappalo alla proprietà chiave Descrizione.
- Aggiorna numero di dimensioni (avanzato): puoi aggiornare questa impostazione se utilizzi incorporamenti vettoriali personalizzati con Vertex AI Search. Consulta Avanzate: utilizzare incorporamenti personalizzati.
- Aggiorna le annotazioni dei campi:per aggiornare le annotazioni di un campo, seleziona o deseleziona l'impostazione di annotazione di un campo. Le annotazioni disponibili sono Recupero, Indirizzabilità, Suddivisione in facet dinamica, Ricercabile e Completabile. Alcune impostazioni dei campi presentano limitazioni. Consulta Configurare le impostazioni dei campi per le descrizioni e i requisiti di ciascun tipo di annotazione.
- Aggiungi un nuovo campo:l'aggiunta di nuovi campi allo schema prima di importare nuovi documenti con questi campi può ridurre il tempo necessario a Vertex AI Agent Builder per eseguire nuovamente l'indicizzazione dei dati dopo l'importazione.
  1. Fai clic su Aggiungi nuovi campi per espandere la sezione.
  2. Fai clic su add_box Aggiungi nodo e specifica le impostazioni per il nuovo campo.
    
    Per indicare un array, imposta Array su Sì. Ad esempio, per aggiungere un array di stringhe, imposta type su string e Array su Yes.
    
    Per un indice datastore di un sito web, tutti i campi aggiunti sono array per impostazione predefinita.
Fai clic su Salva per applicare le modifiche allo schema.

La modifica dello schema attiva la reindicizzazione. Per i datastore di grandi dimensioni, la reindicizzazione può richiedere ore.

REST

Per utilizzare l'API per aggiornare lo schema:

Esamina le sezioni Requisiti e limitazioni e Esempi di limitazioni (solo REST) per verificare che le modifiche allo schema siano valide.

Per aggiornare lo schema per i datastore con siti web o dati non strutturati con metadati, vai al passaggio 5 per chiamare il metodo schema.patch.
Se stai aggiornando le annotazioni dei campi (impostando i campi come indicizzati, recuperabili, come tabelle dinamiche o come campi in cui è possibile eseguire ricerche), consulta Configurare le impostazioni dei campi per conoscere le limitazioni e i requisiti di ogni tipo di annotazione.
Se stai modificando uno schema rilevato automaticamente, assicurati di aver completato l'importazione dati. In caso contrario, lo schema potrebbe non essere ancora disponibile per l'editing.
Trova l'ID del tuo datastore. Se hai già l'ID del tuo datastore, vai al passaggio successivo.
1. Nella console Google Cloud, vai alla pagina Agent Builder e nel menu di navigazione fai clic su Data Store.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella pagina Dati del tuo datastore, ottieni l'ID datastore.

Utilizza il metodo dell'API schemas.patch per fornire il nuovo schema JSON come 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/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 dello datastore di Vertex AI Search.

JSON_SCHEMA_OBJECT: il tuo nuovo 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"
    }
  }
}

Comando e risultato di esempio

curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema" -d '{
"structSchema": {
"$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"
}
}
}
}'

{
"name": "projects/123456/locations/global/collections/default_collection/dataStores/my-data-store/schemas/default_schema/operations/update-schema-10569824819404198922",
"metadata": {
"@type": "type.googleapis.com/google.cloud.discoveryengine.v1.UpdateSchemaMetadata"
}
}

(Facoltativo) Esamina lo schema seguendo la procedura Visualizzare una definizione di schema.

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.

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

public sealed partial class GeneratedSchemaServiceClientSnippets
{
    /// <summary>Snippet for UpdateSchema</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 UpdateSchemaRequestObject()
    {
        // Create client
        SchemaServiceClient schemaServiceClient = SchemaServiceClient.Create();
        // Initialize request argument(s)
        UpdateSchemaRequest request = new UpdateSchemaRequest
        {
            Schema = new Schema(),
            AllowMissing = false,
        };
        // Make the request
        Operation<Schema, UpdateSchemaMetadata> response = schemaServiceClient.UpdateSchema(request);

        // Poll until the returned long-running operation is complete
        Operation<Schema, UpdateSchemaMetadata> completedResponse = response.PollUntilCompleted();
        // Retrieve the operation result
        Schema 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<Schema, UpdateSchemaMetadata> retrievedResponse = schemaServiceClient.PollOnceUpdateSchema(operationName);
        // Check if the retrieved long-running operation has completed
        if (retrievedResponse.IsCompleted)
        {
            // If it has completed, then access the result
            Schema retrievedResult = retrievedResponse.Result;
        }
    }
}

Go

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


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.NewSchemaClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &discoveryenginepb.UpdateSchemaRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/discoveryengine/apiv1/discoveryenginepb#UpdateSchemaRequest.
	}
	op, err := c.UpdateSchema(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.

import com.google.cloud.discoveryengine.v1.Schema;
import com.google.cloud.discoveryengine.v1.SchemaServiceClient;
import com.google.cloud.discoveryengine.v1.UpdateSchemaRequest;

public class SyncUpdateSchema {

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

  public static void syncUpdateSchema() 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 (SchemaServiceClient schemaServiceClient = SchemaServiceClient.create()) {
      UpdateSchemaRequest request =
          UpdateSchemaRequest.newBuilder()
              .setSchema(Schema.newBuilder().build())
              .setAllowMissing(true)
              .build();
      Schema response = schemaServiceClient.updateSchemaAsync(request).get();
    }
  }
}

Python

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

# 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://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import discoveryengine_v1


def sample_update_schema():
    # Create a client
    client = discoveryengine_v1.SchemaServiceClient()

    # Initialize request argument(s)
    request = discoveryengine_v1.UpdateSchemaRequest(
    )

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

    print("Waiting for operation to complete...")

    response = operation.result()

    # Handle the response
    print(response)

Ruby

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

require "google/cloud/discovery_engine/v1"

##
# Snippet for the update_schema call in the SchemaService 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::SchemaService::Client#update_schema.
#
def update_schema
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DiscoveryEngine::V1::SchemaService::Client.new

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

  # Call the update_schema method.
  result = client.update_schema 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

Requisiti e limitazioni

Quando aggiorni uno schema, assicurati che il nuovo schema sia compatibile con quello precedente. Per aggiornare uno schema con un nuovo schema non compatibile con le versioni precedenti, devi eliminare tutti i documenti nel datastore, eliminare lo schema e crearne uno nuovo.

L'aggiornamento di uno schema attiva la reindicizzazione di tutti i documenti. Questa operazione può richiedere del tempo e comportare costi aggiuntivi:

Ora. La reindicizzazione di un datastore di grandi dimensioni può richiedere ore o giorni.
Spese. La ridefinizione dell'indice può comportare dei costi, a seconda dell'interprete. Ad esempio, la reindicizzazione degli store di dati che utilizzano l'analisi logica OCR o l'analisi logica del layout comporta costi. Per ulteriori informazioni, consulta Prezzi delle funzionalità di Document AI.

Gli aggiornamenti dello schema non supportano quanto segue:

Modifica di un tipo di campo. Un aggiornamento dello schema non supporta la modifica del tipo del campo. Ad esempio, un campo mappato a un numero intero non può essere modificato in stringa.
Rimozione di un campo. Una volta definito, un campo non può essere rimosso. Puoi continuare ad aggiungere nuovi campi, ma non puoi rimuovere un campo esistente.

Esempi di limitazioni (solo REST)

Questa sezione mostra esempi di tipi di aggiornamenti dello schema validi e non validi. Questi esempi utilizzano lo schema JSON di esempio seguente:

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

Esempi di aggiornamenti supportati

Sono supportati i seguenti aggiornamenti allo schema di esempio.

Aggiunta di un campo. In questo esempio, il campo properties.uri è stato aggiunto allo schema.

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

Aggiunta o rimozione di annotazioni delle proprietà chiave per title, description o uri. In questo esempio, keyPropertyMapping è stato aggiunto al title campo.

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

Esempi di aggiornamenti dello schema non validi

I seguenti aggiornamenti allo schema di esempio non sono supportati.

Modifica di un tipo di campo. In questo esempio, il tipo di campo title è stato cambiato da stringa a numero. Questa opzione non è supportata.

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "title": {
        "type": "number" // Changed from string. Not allowed.
      },
      "description": {
        "type": "string",
        "keyPropertyMapping": "description"
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string",
          "keyPropertyMapping": "category"
        }
      }
    }
  }

Rimozione di un campo. In questo esempio, il campo title è stato rimosso. Questa opzione non è supportata.

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