Usar ETags para controle de simultaneidade de objetos de dados

A Pesquisa de vetores 2.0 oferece suporte ao controle de simultaneidade otimista (OCC) usando ETags (tags de entidade), que são identificadores opacos que representam versões específicas de objetos de dados.

Quando vários processos operam simultaneamente no mesmo conjunto de dados, como atualizações de API em tempo real e jobs de importação em massa, há o risco de eles substituírem as mudanças uns dos outros (um cenário de última gravação vence). As ETags permitem garantir a integridade de dados e que outro processo não modificou um registro desde a última leitura.

Como as ETags funcionam

  1. Ler: ao criar ou receber um objeto de dados, o servidor retorna uma string de ETag que representa a versão exata do objeto de dados.

  2. Modificar: faça as mudanças no objeto de dados localmente.

  3. Gravar: envie a solicitação de atualização ou exclusão de volta para a Pesquisa de vetores 2.0, incluindo a ETag que você recebeu originalmente.

  4. Verificar: o servidor verifica se a ETag fornecida corresponde à ETag atual armazenada no banco de dados.

    • Se elas corresponderem, a operação será bem-sucedida e o servidor retornará uma nova ETag para o objeto de dados atualizado.
    • Se elas não corresponderem, a operação será bloqueada e o servidor retornará o erro ABORTED (HTTP 409 Conflict).

Como recuperar ETags

Antes de usar uma ETag para controle de simultaneidade, é necessário recuperar a versão mais recente do sistema.

As ETags podem ser recuperadas das seguintes maneiras:

  • Respostas da API em tempo real: ao chamar métodos de leitura ou gravação no DataObjectService (como GetDataObject, ListDataObjects, CreateDataObject, ou UpdateDataObject), o recurso de objeto de dados retornado inclui a ETag atual.

  • Saída da API de importação: ao chamar ImportDataObjects, é possível especificar um prefixo de URI para um Cloud Storage no campo GcsImportConfig output-uri. Se o job de importação for bem-sucedido, os arquivos JSONL serão criados com cada linha contendo os IDs e as ETags dos objetos de dados importados. Isso está no seguinte formato:

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

  • API de exportação (ExportDataObjects) : ao exportar dados da Pesquisa de vetores 2.0 para o Cloud Storage, os arquivos de dados JSONL canônicos resultantes contêm as ETags de todos os objetos de dados exportados.

Como criar objetos de dados

Ao chamar CreateDataObject ou BatchCreateDataObjects, qualquer ETag que você fornecer na solicitação será ignorada porque o objeto de dados ainda não existe.

Quando a solicitação de criação é bem-sucedida, o servidor inclui a ETag recém-gerada no recurso de objeto de dados retornado.

Como atualizar objetos de dados

Para atualizar um registro atual com segurança usando UpdateDataObject ou BatchUpdateDataObjects, inclua a ETag diretamente no recurso de objeto de dados na solicitação.

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

Como excluir objetos de dados

Como os métodos DeleteDataObject e BatchDeleteDataObjects não usam um recurso de objeto de dados completo como payload, a ETag precisa ser fornecida como um campo de nível superior na DeleteDataObjectRequest.

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

Como usar ETags com ingestão em massa (ImportDataObjects)

O uso da API ImportDataObjects é executado de forma assíncrona e pode entrar em conflito com atualizações em tempo real. Inclua o campo etag nos seus JSONL arquivos de importação para aplicar o controle de simultaneidade durante as importações.

A Pesquisa de vetores detecta automaticamente o modo de resolução de conflitos por registro:

  • Com ETag (OCC): se uma ETag for fornecida e não corresponder à versão atual do servidor, o registro específico não será importado. A falha será registrada no URI de erro especificado, mas o restante do job de importação continuará.

  • Sem ETag: se a ETag for omitida, o registro será ingerido, substituindo todos os dados atuais. Isso maximiza a capacidade de processamento quando o controle de simultaneidade não é necessário.

Formato JSONL

Inclua a ETag no nível raiz do objeto JSON no arquivo de importação, conforme mostrado no exemplo a seguir.

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

Como processar erros de simultaneidade

Se uma operação falhar em uma verificação de ETag, a API vai retornar um código de erro ABORTED (HTTP 409 Conflict).

Processamento de erros recomendado:

Quando você receber um erro ABORTED, seu aplicativo deverá:

  1. Buscar novamente a versão mais recente do objeto de dados no servidor.

  2. Resolver conflitos de lógica de negócios entre os dados recém-buscados e as atualizações pretendidas.

  3. Tentar novamente a operação usando a nova ETag.

A seguir