Database locali
Questo documento si applica al seguente metodo: API Update.
Configurazione del database
I client che utilizzano l'API Update devono configurare un database locale ed eseguire un download iniziale degli elenchi Web Risk con cui vogliono lavorare. Consulta la sezione Aggiornamenti completi di seguito per ulteriori informazioni su come eseguire il recupero iniziale.
Aggiornamenti del database
Per garantire la protezione dalle minacce più recenti, i client sono fortemente incoraggiati ad aggiornare regolarmente i loro elenchi Web Risk locali utilizzando il metodo threatLists.computeDiff
.
La richiesta threatLists.computeDiff
specifica l'elenco da aggiornare. Se i client hanno limitazioni di memoria o larghezza di banda, possono anche utilizzare la richiesta per impostare vincoli di aggiornamento (consulta la sezione Vincoli di aggiornamento).
threatLists.computeDiff response
restituisce
un aggiornamento completo o parziale per ogni elenco, come spiegato di seguito.
Aggiornamenti completi
Gli aggiornamenti completi vengono restituiti quando il client lascia vuoto il campo versionToken
nella richiestathreatLists.computeDiff o quando il server determina che è necessario un aggiornamento completo. Per gli aggiornamenti completi, vengono restituite solo le integrazioni. Il client deve cancellare il database locale prima di applicare gli aggiornamenti ed eseguire il controllo di convalida.
Stato vuoto
Gli aggiornamenti completi vengono restituiti quando il client invia la richiesta iniziale di un elenco.
In questo caso, il campo versionToken
nella richiesta viene lasciato vuoto (perché non è presente alcun valore da fornire) e il campo newVersionToken
nella risposta restituisce lo stato iniziale dell'elenco locale. Gli aggiornamenti completi vengono restituiti anche quando il client lascia volutamente vuoto il campo versionToken
per le richieste successive. Questa operazione forzerà un aggiornamento completo e restituirà un nuovo stato nel campo newVersionToken
della risposta.
Decisione del server
A volte, il server Web Risk restituisce un aggiornamento completo quando il client richiede solo un aggiornamento parziale. Questo può accadere quando il client inizialmente scarica una versione ridotta dell'elenco e poi esegue l'aggiornamento a una versione più ampia dell'elenco. Il server restituisce semplicemente un aggiornamento completo con l'intero elenco. Questa situazione può verificarsi anche se il client non ha scaricato dati da molto tempo e richiede un aggiornamento parziale. Anche in questo caso, il server restituirà semplicemente un aggiornamento completo con l'intero elenco.
Aggiornamenti parziali
Gli aggiornamenti parziali vengono restituiti quando il client fornisce un valore per il campo versionToken
nella richiesta threatLists.computeDiff
(l'eccezione, come indicato sopra, si verifica quando il server determina che è necessario un aggiornamento completo). Per gli aggiornamenti parziali, vengono restituite sia le addizioni che le rimozioni. Il client aggiorna gli elenchi nel database locale (applicando le
rimozioni prima delle aggiunte) e poi esegue il
controllo di convalida.
Aggiunte
Le aggiunte sono prefissi hash SHA256 che devono essere aggiunti al database locale. La maggior parte dei prefissi hash ha una lunghezza di 4 byte, ma alcuni potrebbero avere una lunghezza compresa tra 4 e 32 byte. È stato quindi possibile restituire più insiemi di aggiunte; ad esempio, uno contenente i prefissi da 4 byte e l'altro uno contenente i prefissi da 5 byte.
Se il client supporta la compressione, la risposta può essere compressa utilizzando la compressione Rice. Tuttavia, vengono compressi solo i prefissi hash da 4 byte. I prefissi hash più lunghi vengono sempre inviati in formato non compresso e non elaborato. Per maggiori dettagli, consulta la sezione Compressione.
Rimozioni
Le rimozioni sono indici in base zero nel database client ordinato lessicograficamente che puntano a voci che devono essere rimosse dal database locale. Verrà restituito un solo insieme di rimozioni.
Se il cliente supporta la compressione, vengono restituiti "hash di riso" e "indici di riso". Se la compressione non è supportata, vengono restituiti "hash non elaborati" e "indici non elaborati". Per maggiori dettagli, vedi Compressione/web-risk/docs/compression.
Controlli di convalida
Quando viene restituita la risposta threatLists.computeDiff
, con un aggiornamento completo o parziale, il client deve eseguire un controllo di convalida.
Il client aggiorna in primo luogo gli elenchi nel database locale (applicando le rimozioni prima delle aggiunte). Il client calcola quindi l'hash SHA256 dell'elenco locale (ordinato lessicograficamente) e lo confronta con il checksum restituito nella risposta. Se i due valori sono uguali, l'elenco Web Risk viene considerato "corretto".
Se i due valori non sono uguali, l'elenco Web Risk viene considerato "corrotto". Il client deve cancellare l'elenco dal database ed emettere un secondo aggiornamento con il campo versionToken
impostato sulla stringa vuota; in questo modo verrà forzata un aggiornamento completo e verranno restituiti un nuovo elenco e uno stato.