Bases de dados locais

Este documento aplica-se ao seguinte método: API Update.

Configuração da base de dados

Os clientes que usam a API Update têm de configurar uma base de dados local e fazer um carregamento inicial das listas do Web Risk com as quais querem trabalhar. Consulte a secção Atualizações completas abaixo para ver mais informações sobre como realizar a obtenção inicial.

Atualizações da base de dados

Para garantir a proteção contra as ameaças mais recentes, recomendamos vivamente que os clientes atualizem regularmente as respetivas listas de risco na Web locais através do método threatLists.computeDiff.

O pedido threatLists.computeDiff especifica a lista a ser atualizada. Se os clientes tiverem limitações de memória ou largura de banda, também podem usar o pedido para definir restrições de atualização (consulte Restrições de atualização).

O elemento threatLists.computeDiff response devolve uma atualização completa ou parcial para cada lista, conforme explicado abaixo.

Atualizações completas

As atualizações completas são devolvidas quando o cliente deixa o campo versionToken no threatLists.computeDiff request vazio ou quando o servidor determina que é necessária uma atualização completa. Para atualizações completas, só são devolvidas adições. Espera-se que o cliente limpe a base de dados local antes de aplicar as atualizações e realizar a verificação de validação.

Estado vazio

As atualizações completas são devolvidas quando o cliente envia o pedido inicial de uma lista. Neste caso, o campo versionToken no pedido fica vazio (porque não existe nenhum valor a indicar) e o campo newVersionToken na resposta devolve o estado inicial da lista local. As atualizações completas também são devolvidas quando o cliente deixa intencionalmente o campo versionToken vazio em pedidos subsequentes. Esta ação força uma atualização completa e devolve um novo estado no campo newVersionToken da resposta.

Decisão do servidor

Ocasionalmente, o servidor do Web Risk devolve uma atualização completa quando o cliente pediu apenas uma atualização parcial. Isto pode acontecer quando o cliente transfere inicialmente uma versão pequena da lista e, em seguida, atualiza para uma versão maior da lista. O servidor devolve simplesmente uma atualização completa com a lista inteira. Isto também pode acontecer se o cliente não tiver transferido dados durante muito tempo e pedir uma atualização parcial. Mais uma vez, o servidor devolve simplesmente uma atualização completa com a lista inteira.

Atualizações parciais

As atualizações parciais são devolvidas quando o cliente fornece um valor para o campo versionToken no pedido threatLists.computeDiff (a exceção, conforme indicado acima, é quando o servidor determina que é necessária uma atualização completa). Para atualizações parciais, são devolvidas as adições e as remoções. O cliente atualiza as listas na base de dados local (aplicando as remoções antes das adições) e, em seguida, realiza a verificação de validação.

Adições

As adições são prefixos de hash SHA256 que devem ser adicionados à base de dados local. A maioria dos prefixos de hash tem 4 bytes, mas alguns prefixos de hash podem ter qualquer comprimento entre 4 e 32 bytes. Por conseguinte, podem ser devolvidos vários conjuntos de adições; por exemplo, um que contenha os prefixos de 4 bytes e outro que contenha os prefixos de 5 bytes.

Se o cliente suportar a compressão, a resposta pode ser comprimida através da compressão Rice. No entanto, apenas os prefixos de hash de 4 bytes são comprimidos. Os prefixos de hash mais longos são sempre enviados no formato não comprimido e não processado. Para mais detalhes, consulte a secção Compressão.

Remoções

As remoções são índices baseados em zero na base de dados do cliente ordenada lexicograficamente, que apontam para entradas que devem ser removidas da base de dados local. Apenas é devolvido um conjunto de remoções.

Se o cliente suportar a compressão, são devolvidos "hashes de arroz" e "índices de arroz". Se a compressão não for suportada, são devolvidos "hashes brutos" e "índices brutos". Para mais detalhes, consulte Compressão/web-risk/docs/compression).

Verificações de validação

Quando a resposta threatLists.computeDiff é devolvida, com uma atualização completa ou parcial, espera-se que o cliente faça uma verificação de validação.

Primeiro, o cliente atualiza as listas na base de dados local (aplicando as remoções antes das adições). Em seguida, o cliente calcula o hash SHA256 da lista local (ordenada lexicograficamente) e compara-o com a soma de verificação devolvida na resposta. Se os dois valores forem iguais, a lista do Web Risk é considerada "correta".

Se os dois valores não forem iguais, a lista do Web Risk é considerada "danificada". O cliente tem de limpar a lista da base de dados e emitir uma segunda atualização com o campo versionToken definido como a string vazia. Isto força uma atualização completa e devolve uma lista e um estado totalmente novos.