Bases de données locales

Ce document s'applique à la méthode suivante : API Update.

Configuration de la base de données

Les clients qui utilisent l'API Update doivent configurer une base de données locale et effectuer un téléchargement initial des listes Web Risk avec lesquelles ils souhaitent travailler. Consultez la section Mises à jour complètes ci-dessous pour savoir comment effectuer la récupération initiale.

Mises à jour de la base de données

Pour assurer leur protection contre les menaces les plus récentes, les clients sont vivement encouragés à mettre à jour régulièrement leurs listes Web Risk locales à l'aide de la méthode threatLists.computeDiff.

La requête threatLists.computeDiff spécifie la liste à mettre à jour. Si les clients ont des limites de mémoire ou de bande passante, ils peuvent également utiliser la requête pour définir des contraintes de mise à jour (voir Contraintes de mise à jour).

La fonction threatLists.computeDiff response renvoie une mise à jour complète ou partielle pour chaque liste, comme expliqué ci-dessous.

Mises à jour complètes

Les mises à jour complètes sont renvoyées lorsque le client ne renseigne pas le champ versionToken dans la requête threatLists.computeDiff ou lorsque le serveur détermine qu'une mise à jour complète est requise. Pour les mises à jour complètes, seuls les ajouts sont renvoyés. Le client doit effacer la base de données locale avant d'appliquer les mises à jour et d'effectuer le contrôle de validation.

État vide

Les mises à jour complètes sont renvoyées lorsque le client envoie la demande initiale de liste. Dans ce cas, le champ versionToken de la requête n'est pas renseigné (car il n'y a pas de valeur à fournir) et le champ newVersionToken de la réponse renvoie l'état initial de la liste locale. Des mises à jour complètes sont également renvoyées lorsque le client laisse intentionnellement le champ versionToken vide lors des requêtes suivantes. Cela entraînera une mise à jour complète et renverra un nouvel état dans le champ newVersionToken de la réponse.

Décision du serveur

Il arrive que le serveur Web Risk renvoie une mise à jour complète alors que le client n'a demandé qu'une mise à jour partielle. Cela peut se produire lorsque le client télécharge initialement une version réduite de la liste, puis met à jour une version plus étendue de cette liste. Le serveur renverra simplement une mise à jour complète de la liste complète. Cela peut également se produire si le client n'a pas téléchargé de données depuis longtemps et demande une mise à jour partielle. Encore une fois, le serveur renverra simplement une mise à jour complète de la liste complète.

Mises à jour partielles

Les mises à jour partielles sont renvoyées lorsque le client indique une valeur dans le champ versionToken de la requête threatLists.computeDiff (comme indiqué ci-dessus, il y a exception lorsque le serveur détermine qu'une mise à jour complète est requise). Pour les mises à jour partielles, les ajouts et les suppressions sont renvoyés. Le client met à jour les listes dans la base de données locale (en appliquant les suppressions avant les ajouts), puis effectue le contrôle de validation.

Ajouts

Les ajouts sont des préfixes de hachage SHA256 qui doivent être ajoutés à la base de données locale. La plupart des préfixes de hachage comportent 4 octets, mais certains d'entre eux peuvent avoir une taille comprise entre 4 et 32 octets. Par conséquent, plusieurs ensembles d'ajouts peuvent être renvoyés ; par exemple, les uns contenant des préfixes de 4 octets et les autres des préfixes de 5 octets.

Si le client est compatible avec la compression, la réponse peut être compressée à l'aide de la compression RICE. Toutefois, seuls les préfixes de hachage de 4 octets sont compressés. Les préfixes de hachage plus longs sont toujours envoyés au format RAW non compressé. Pour en savoir plus, consultez la section Compression.

Suppressions

Les suppressions sont des index basés sur zéro dans la base de données client triée de façon lexicographique, pointant vers les entrées à supprimer de la base de données locale. Un seul ensemble de suppressions sera renvoyé.

Si le client est compatible avec la compression, les "hachages RICE" et les "index RICE" sont renvoyés. Si la compression n'est pas compatible, les "hachages RAW" et les "index RAW" sont renvoyés. Pour en savoir plus, consultez la section Compression/web-risque/docs/compression).

Contrôles de validation

Lorsque la réponse threatLists.computeDiff est renvoyée avec une mise à jour complète ou partielle, le client doit effectuer un contrôle de validation.

Le client met d'abord à jour les listes dans la base de données locale (en appliquant les suppressions avant les ajouts). Le client calcule ensuite le hachage SHA256 de la liste locale (triée de façon lexicographique) et le compare à la somme de contrôle renvoyée dans la réponse. Si les deux valeurs sont égales, la liste Web Risk est considérée comme "correcte".

Si les deux valeurs ne sont pas égales, la liste Web Risk est considérée comme "corrompue". Le client doit effacer la liste de la base de données et renvoyer une deuxième mise à jour avec le champ versionToken défini sur la chaîne vide. Cela entraînera une mise à jour complète et renverra une nouvelle liste et un nouvel état.