Этот документ относится к следующему методу: API обновления (v4) : ThreatListUpdates.fetch .
Настройка базы данных
Клиентам, использующим API обновления, необходимо настроить локальную базу данных и выполнить первоначальную загрузку списков безопасного просмотра, с которыми они хотят работать. Чтобы приступить к работе, вы можете собрать и развернуть пакет Go safebrowsing (или использовать его для моделирования собственной реализации). Для получения дополнительной информации см. https://github.com/google/safebrowsing/ .
Обновления базы данных
Чтобы обеспечить защиту от новейших угроз, клиентам настоятельно рекомендуется регулярно обновлять свои локальные списки безопасного просмотра с помощью метода ThreatListUpdates.fetch . Запрос ThreatListUpdates.fetch указывает списки, которые необходимо обновить. Если у клиентов есть ограничения по памяти или пропускной способности, они также могут использовать запрос для установки ограничений обновления (см. Ограничения обновления ). Ответ ThreatListUpdates.fetch возвращает либо полное, либо частичное обновление для каждого списка, как описано ниже.Полные обновления
Полные обновления возвращаются, когда клиент оставляет поле state в запросе ThreatListUpdates.fetch пустым или когда сервер определяет, что требуется полное обновление. Для полных обновлений возвращаются только дополнения . Ожидается, что клиент очистит локальную базу данных перед применением обновлений и выполнением проверки .
Полные обновления возвращаются, когда клиент отправляет первоначальный запрос списка. В этом случае поле state в запросе остается пустым (поскольку нет значения для предоставления), а поле newClientState в ответе возвращает исходное состояние для локального списка. Полные обновления также возвращаются, когда клиент намеренно оставляет поле state пустым при последующих запросах. Это приведет к полному обновлению и возврату нового состояния в поле newClientState ответа.
Иногда сервер безопасного просмотра возвращает полное обновление, когда клиент запрашивает только частичное обновление. Это может произойти, когда клиент сначала загружает небольшую версию списка, а затем обновляет его до более крупной версии; сервер просто вернет полное обновление со всем списком. Это также может произойти, если клиент долгое время не загружал данные и запрашивает частичное обновление; опять же, сервер просто вернет полное обновление со всем списком.
Частичные обновления
Частичные обновления возвращаются, когда клиент предоставляет значение для поля state в запросе ThreatListUpdates.fetch (исключением, как отмечалось выше, является ситуация, когда сервер определяет, что требуется полное обновление). При частичных обновлениях возвращаются как дополнения , так и удаления . Клиент обновляет списки в локальной базе данных (применяя удаления перед добавлением), а затем выполняет проверку .
Дополнения
Дополнения — это хеш-префиксы SHA256, которые следует добавить в локальную базу данных. Подавляющее большинство префиксов хеша имеют длину 4 байта, но некоторые префиксы хеша могут иметь длину от 4 до 32 байтов. Следовательно, можно вернуть несколько наборов дополнений; например, один, содержащий 4-байтовые префиксы, и другой, содержащий 5-байтовые префиксы.
Если клиент поддерживает сжатие, ответ может быть сжат с использованием сжатия Райса. Однако сжимаются только 4-байтовые хэш-префиксы. Более длинные хэш-префиксы всегда передаются в несжатом необработанном формате (см. Сжатие ).
Переезды
Удаление — это индекс, начинающийся с нуля, в клиентской базе данных с лексикографической сортировкой, указывающий на записи, которые следует удалить из локальной базы данных. Будет возвращен только один комплект удалений.
Если клиент поддерживает сжатие, возвращаются «хеши риса» и «индексы риса». Если сжатие не поддерживается, возвращаются «необработанные хэши» и «необработанные индексы» (см. Сжатие ).
Проверки валидации
Когда возвращается ответ ThreatListUpdates.fetch — с полным или частичным обновлением — ожидается, что клиент выполнит проверку.
Клиент сначала обновляет списки в локальной базе данных (удаления применяются перед добавлением). Затем клиент вычисляет хэш SHA256 (лексикографически отсортированного) локального списка и сравнивает его с контрольной суммой, возвращенной в ответе. Если эти два значения равны, список безопасного просмотра считается «правильным».
Если эти два значения не равны, список безопасного просмотра считается «поврежденным». Клиент должен удалить список из базы данных и повторно выпустить второе обновление, установив в поле state пустую строку; это приведет к полному обновлению и возврату совершенно нового списка и состояния.