ETags für die Nebenläufigkeitserkennung von Datenobjekten verwenden

Vector Search 2.0 unterstützt die optimistische Nebenläufigkeitserkennung (Optimistic Concurrency Control, OCC) mit ETags (Entitäts-Tags). Das sind undurchsichtige IDs, die bestimmte Datenobjekt-Versionen darstellen.

Wenn mehrere Prozesse gleichzeitig auf dasselbe Dataset zugreifen, z. B. API-Updates in Echtzeit und Bulk-Importjobs, besteht das Risiko, dass sie die Änderungen des jeweils anderen überschreiben (Last-Write-Wins-Szenario). Mit ETags können Sie die Datenintegrität garantieren und sicherstellen, dass ein Datensatz seit dem letzten Lesen nicht von einem anderen Prozess geändert wurde.

Funktionsweise von ETags

  1. Lesen: Wenn Sie ein Datenobjekt erstellen oder abrufen, gibt der Server einen ETag-String zurück, der die genaue Version des Datenobjekts darstellt.

  2. Ändern: Sie nehmen die Änderungen am Datenobjekt lokal vor.

  3. Schreiben: Sie senden die Aktualisierungs- oder Löschanfrage zurück an Vector Search 2.0, einschließlich des ursprünglich empfangenen ETags.

  4. Überprüfen: Der Server prüft, ob das angegebene ETag mit dem aktuellen ETag in der Datenbank übereinstimmt.

    • Wenn sie übereinstimmen, ist der Vorgang erfolgreich und der Server gibt ein neues ETag für das aktualisierte Datenobjekt zurück.
    • Wenn sie nicht übereinstimmen, wird der Vorgang blockiert und der Server gibt den ABORTED Fehler (HTTP 409 Conflict) zurück.

ETags abrufen

Bevor Sie ein ETag für die Nebenläufigkeitserkennung verwenden können, müssen Sie die neueste Version aus dem System abrufen.

ETags können auf folgende Weise abgerufen werden:

  • API-Antworten in Echtzeit: Wenn Sie Lese- oder Schreibmethoden für den DataObjectService aufrufen (z. B. GetDataObject, ListDataObjects, CreateDataObject oder UpdateDataObject), enthält die zurückgegebene Datenobjektressource das aktuelle ETag.

  • Ausgabe der Import API: Wenn Sie ImportDataObjects aufrufen, können Sie im Feld GcsImportConfig von output-uri ein URI-Präfix für einen Cloud Storage-Bucket angeben. Wenn der Importjob erfolgreich ist, werden JSONL-Dateien erstellt , wobei jede Zeile die IDs und ETags für importierte Datenobjekte enthält. Das Format sieht so aus:

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

  • Export API (ExportDataObjects) : Wenn Sie Daten aus Vector Search 2.0 in Cloud Storage exportieren, enthalten die resultierenden kanonischen JSONL-Datendateien die ETags für alle exportierten Datenobjekte.

Datenobjekte erstellen

Wenn Sie CreateDataObject oder BatchCreateDataObjects aufrufen, wird jedes ETag, das Sie in der Anfrage angeben, ignoriert, da das Datenobjekt noch nicht vorhanden ist.

Wenn die Erstellungsanfrage erfolgreich ist, fügt der Server das neu generierte ETag in die zurückgegebene Datenobjektressource ein.

Datenobjekte aktualisieren

Wenn Sie einen vorhandenen Datensatz mit UpdateDataObject oder BatchUpdateDataObjects sicher aktualisieren möchten, fügen Sie das ETag direkt in die Datenobjekt ressource in Ihrer Anfrage ein.

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

Datenobjekte löschen

Da die Methoden DeleteDataObject und BatchDeleteDataObjects keine vollständige Datenobjektressource als Nutzlast verwenden, muss das ETag als Feld der obersten Ebene in der DeleteDataObjectRequest angegeben werden.

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

ETags mit Bulk-Ingestion verwenden (ImportDataObjects)

Die Verwendung der ImportDataObjects API erfolgt asynchron und kann zu Konflikten mit Echtzeit-Updates führen. Fügen Sie das Feld etag in Ihre JSONL Importdateien ein, um die Nebenläufigkeitserkennung während des Imports zu erzwingen.

Vector Search erkennt den Modus zur Konfliktlösung automatisch pro Datensatz:

  • Mit ETag (OCC): Wenn ein ETag angegeben wird und nicht mit der aktuellen Version des Servers übereinstimmt, kann der jeweilige Datensatz nicht importiert werden. Der Fehler wird dann im angegebenen Fehler-URI protokolliert, der Rest des Importjobs wird jedoch fortgesetzt.

  • Ohne ETag: Wenn das ETag nicht angegeben wird, wird der Datensatz aufgenommen und alle vorhandenen Daten werden überschrieben. Dadurch wird der Durchsatz maximiert, wenn keine Nebenläufigkeitserkennung erforderlich ist.

JSONL-Format

Fügen Sie das ETag auf der Stammebene des JSON-Objekts in Ihrer Importdatei ein, wie im folgenden Beispiel gezeigt.

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

Fehler bei der Nebenläufigkeitserkennung beheben

Wenn bei einem Vorgang die ETag-Prüfung fehlschlägt, gibt die API den Fehlercode ABORTED (HTTP 409 Conflict) zurück.

Empfohlene Fehlerbehandlung:

Wenn Sie einen ABORTED-Fehler erhalten, sollte Ihre Anwendung so vorgehen:

  1. Die neueste Version des Datenobjekts vom Server abrufen.

  2. Alle Konflikte in der Geschäftslogik zwischen den neu abgerufenen Daten und den beabsichtigten Updates beheben.

  3. Den Vorgang mit dem neuen ETag wiederholen.

Nächste Schritte