Utilizzare gli ETag per il controllo della contemporaneità degli oggetti dati

La ricerca vettoriale 2.0 supporta il controllo della contemporaneità ottimistico (OCC) utilizzando gli ETag (tag di entità), che sono identificatori opachi che rappresentano versioni specifiche degli oggetti dati.

Quando più processi operano contemporaneamente sullo stesso set di dati, ad esempio aggiornamenti API in tempo reale e job di importazione collettiva, esiste il rischio che si sovrascrivano a vicenda le modifiche (uno scenario di last-write-wins). Gli ETag consentono di garantire l'integrità dei dati e assicurarsi che un altro processo non abbia modificato un record dall'ultima volta che l'hai letto.

Come funzionano gli ETag

  1. Lettura: quando crei o recuperi un oggetto dati, il server restituisce una stringa ETag che rappresenta la versione esatta dell'oggetto dati.

  2. Modifica: apporti le modifiche all'oggetto dati localmente.

  3. Scrittura: invii la richiesta di aggiornamento o eliminazione alla ricerca vettoriale 2.0, incluso l'ETag che hai ricevuto originariamente.

  4. Verifica: il server controlla se l'ETag fornito corrisponde all'ETag corrente memorizzato nel database.

    • Se corrispondono, l'operazione va a buon fine e il server restituisce un nuovo ETag per l'oggetto dati aggiornato.
    • Se non corrispondono, l'operazione viene bloccata e il server restituisce l'errore ABORTED (HTTP 409 Conflict).

Recupero degli ETag

Prima di poter utilizzare un ETag per il controllo della contemporaneità, devi recuperare la versione più recente dal sistema.

Gli ETag possono essere recuperati nei seguenti modi:

  • Risposte API in tempo reale: quando chiami i metodi di lettura o scrittura su DataObjectService (ad esempio GetDataObject, ListDataObjects, CreateDataObject, o UpdateDataObject), la risorsa oggetto dati restituita include l'ETag corrente.

  • Output dell'API di importazione: quando chiami ImportDataObjects, puoi specificare un prefisso URI per un Cloud Storage nel campo GcsImportConfig output-uri. Se il job di importazione va a buon fine, vengono creati file JSONL in cui ogni riga contiene gli ID e gli ETag degli oggetti dati importati. Ha il seguente formato:

    { "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}

  • API di esportazione (ExportDataObjects) : quando esporti i dati dalla ricerca vettoriale 2.0 a Cloud Storage, i file di dati JSONL canonici risultanti contengono gli ETag di tutti gli oggetti dati esportati.

Creazione di oggetti dati

Quando chiami CreateDataObject o BatchCreateDataObjects, qualsiasi ETag che fornisci nella richiesta viene ignorato perché l'oggetto dati non esiste ancora.

Quando la richiesta di creazione va a buon fine, il server include l'ETag appena generato nella risorsa oggetto dati restituita.

Aggiornamento degli oggetti dati

Per aggiornare in sicurezza un record esistente utilizzando UpdateDataObject o BatchUpdateDataObjects, includi l'ETag direttamente nella risorsa oggetto dati nella richiesta.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
  "data": {
    "genre": ["science-fiction", "thriller", "action"]
  }
}

Eliminazione di oggetti dati

Poiché i metodi DeleteDataObject e BatchDeleteDataObjects non accettano una risorsa oggetto dati completa come payload, l'ETag deve essere fornito come campo di primo livello in DeleteDataObjectRequest.

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}

Utilizzo degli ETag con l'inserimento collettivo (ImportDataObjects)

L'utilizzo dell'API ImportDataObjects viene eseguito in modo asincrono e può potenzialmente entrare in conflitto con gli aggiornamenti in tempo reale. Includi il campo etag nei tuoi JSONL file di importazione per applicare controllo della contemporaneità durante le importazioni.

La ricerca vettoriale rileva automaticamente la modalità di risoluzione dei conflitti per ogni record:

  • Con ETag (OCC): se viene fornito un ETag che non corrisponde alla versione corrente del server, l'importazione del record specifico non andrà a buon fine. L'errore viene quindi registrato nell'URI di errore specificato, ma il resto del job di importazione continua.

  • Senza ETag: se l'ETag viene omesso, il record viene inserito, sovrascrivendo eventuali dati esistenti. In questo modo si massimizza il throughput quando controllo della contemporaneità non è necessario.

Formato JSONL

Includi l'ETag a livello di root dell'oggetto JSON nel file di importazione, come mostrato nell'esempio seguente.

{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }

Gestione degli errori di contemporaneità

Se un'operazione non supera un controllo ETag, l'API restituisce un codice di errore ABORTED (HTTP 409 Conflict).

Gestione degli errori consigliata:

Quando ricevi un errore ABORTED, la tua applicazione deve:

  1. Recuperare di nuovo la versione più recente dell'oggetto dati dal server.

  2. Risolvere eventuali conflitti di logica di business tra i dati appena recuperati e gli aggiornamenti previsti.

  3. Riprovare l'operazione utilizzando il nuovo ETag.

Passaggi successivi