Utiliser des ETags pour le contrôle de simultanéité des objets de données

Vector Search 2.0 est compatible avec le contrôle de simultanéité optimiste à l'aide d' ETags (tags d'entité), qui sont des identifiants opaques représentant des versions spécifiques d' objets de données.

Lorsque plusieurs processus fonctionnent simultanément sur le même ensemble de données, comme les mises à jour d'API en temps réel et les tâches d'importation groupée, ils risquent d'écraser leurs modifications respectives (scénario de dernière écriture gagnante). Les ETags vous permettent de garantir l'intégrité des données et de vous assurer qu'un autre processus n'a pas modifié un enregistrement depuis votre dernière lecture.

Fonctionnement des ETags

  1. Lecture : lorsque vous créez ou obtenez un objet de données, le serveur renvoie une chaîne ETag représentant la version exacte de l'objet de données.

  2. Modification : vous apportez vos modifications à l'objet de données localement.

  3. Écriture : vous renvoyez la requête de mise à jour ou de suppression à Vector Search 2.0, y compris l'ETag que vous avez reçu à l'origine.

  4. Vérification : le serveur vérifie si l'ETag fourni correspond à l'ETag actuel stocké dans la base de données.

    • S'ils correspondent, l'opération réussit et le serveur renvoie un nouvel ETag pour l'objet de données mis à jour.
    • S'ils ne correspondent pas, l'opération est bloquée et le serveur renvoie l'erreur ABORTED (HTTP 409 Conflict).

Récupérer des ETags

Avant de pouvoir utiliser un ETag pour le contrôle de simultanéité, vous devez récupérer la dernière version du système.

Les ETags peuvent être récupérés de différentes manières :

  • Réponses d'API en temps réel : lorsque vous appelez des méthodes de lecture ou d'écriture sur le DataObjectService (telles que GetDataObject, ListDataObjects, CreateDataObject, ou UpdateDataObject), la ressource d'objet de données renvoyée inclut son ETag actuel.

  • Sortie de l'API d'importation : lorsque vous appelez ImportDataObjects, vous pouvez spécifier un préfixe d'URI dans un Cloud Storage dans le champ GcsImportConfig output-uri. Si la tâche d'importation réussit, des fichiers JSONL sont créés chaque ligne contenant les ID et les ETags des objets de données importés. Le format est le suivant :

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

  • API d'exportation (ExportDataObjects) : lorsque vous exportez des données de Vector Search 2.0 vers Cloud Storage, les fichiers de données JSONL canoniques résultants contiennent les ETags de tous les objets de données exportés.

Créer des objets de données

Lorsque vous appelez CreateDataObject ou BatchCreateDataObjects, tout ETag que vous fournissez dans la requête est ignoré, car l'objet de données n'existe pas encore.

Lorsque la requête de création réussit, le serveur inclut l'ETag nouvellement généré dans la ressource d'objet de données renvoyée.

Mettre à jour des objets de données

Pour mettre à jour en toute sécurité un enregistrement existant à l'aide de UpdateDataObject ou BatchUpdateDataObjects, incluez l'ETag directement dans la ressource d'objet de données de votre requête.

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

Supprimer des objets de données

Étant donné que les méthodes DeleteDataObject et BatchDeleteDataObjects ne prennent pas une ressource d'objet de données complète comme charge utile, l'ETag doit être fourni en tant que champ de premier niveau dans le DeleteDataObjectRequest.

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

Utiliser des ETags avec l'ingestion groupée (ImportDataObjects)

L'API ImportDataObjects s'exécute de manière asynchrone et peut potentiellement entrer en conflit avec des mises à jour en temps réel. Incluez le etag champ dans vos JSONL fichiers d'importation pour appliquer le contrôle de simultanéité lors des importations.

Vector Search détecte automatiquement le mode de résolution des conflits pour chaque enregistrement :

  • Avec ETag (OCC) : si un ETag est fourni et ne correspond pas à la version actuelle du serveur, l'importation de l'enregistrement spécifique échoue. L'échec est ensuite consigné dans l'URI d'erreur spécifié, mais le reste de la tâche d'importation se poursuit.

  • Sans ETag : si l'ETag est omis, l'enregistrement est ingéré, ce qui remplace toutes les données existantes. Cela maximise le débit lorsque le contrôle de simultanéité n'est pas nécessaire.

Format JSONL

Incluez l'ETag au niveau racine de l'objet JSON dans votre fichier d'importation, comme illustré dans l'exemple suivant.

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

Gérer les erreurs de simultanéité

Si une opération échoue à une vérification ETag, l'API renvoie un code d'erreur ABORTED (HTTP 409 Conflict).

Gestion des erreurs recommandée :

Lorsque vous recevez une erreur ABORTED, votre application doit :

  1. Récupérer la dernière version de l'objet de données sur le serveur.

  2. Résoudre les conflits de logique métier entre les données nouvellement récupérées et les mises à jour prévues.

  3. Réessayer l'opération à l'aide du nouvel ETag.

Étape suivante