Этот документ распространяется на следующие методы:
О кэшировании
Чтобы уменьшить использование пропускной способности клиента и защитить Google от всплесков трафика, клиенты API поиска и API обновления должны создавать и поддерживать локальный кэш данных об угрозах. В API поиска кэш используется для уменьшения количества запросов threatMatches , которые клиенты отправляют в Google. В API обновления кеш используется для уменьшения количества запросов fullHashes , которые клиенты отправляют в Google. Протокол кэширования для каждого API описан ниже.
API поиска
Клиенты API поиска должны кэшировать каждый возвращаемый элемент ThreatMatch в течение периода, определенного его полем кэшДурион. Затем клиентам необходимо просмотреть кэш, прежде чем отправлять последующий запрос threatMatches на сервер. Если срок кэширования ранее возвращенного ThreatMatch еще не истек, клиент должен предположить, что элемент все еще небезопасен. Кэширование элементов ThreatMatch может сократить количество запросов API, выполняемых клиентом.
Пример: ThreatMatches.find
Нажмите на ссылки запроса и ответа в заголовке таблицы, чтобы просмотреть полные примеры.
| Проверка URL-адреса Запрос на соответствие угрозе | URL-адрес совпадения угроза соответствует ответу | Поведение кэширования |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
| Соответствовать. Клиент должен подождать 5 минут, прежде чем отправлять новый запрос threatMatches , включающий URL-адрес http://www.urltocheck.org/. |
Обновить API
Чтобы уменьшить общее количество запросов fullHashes , отправляемых в Google с помощью API обновления, клиентам необходимо поддерживать локальный кеш. API устанавливает два типа кэширования: положительное и отрицательное.
Позитивное кеширование
Чтобы клиенты не могли повторно запрашивать состояние определенного небезопасного полного хэша, каждый возвращенный ThreatMatch содержит положительную продолжительность кэша (определяемую полем cacheDuration ), которая указывает, в течение какого времени полный хэш считается небезопасным.
Отрицательное кеширование
Чтобы клиенты не могли повторно запрашивать состояние конкретного безопасного полного хеша, каждый ответ fullHashes определяет отрицательную длительность кэша для запрошенного префикса (определяемую полем negativeCacheDuration ). Эта продолжительность указывает, как долго все полные хеши с запрошенным префиксом будут считаться безопасными для запрошенных списков, за исключением тех, которые возвращаются сервером как небезопасные. Такое кэширование особенно важно, поскольку оно предотвращает перегрузку трафика, которая может быть вызвана конфликтом хэш-префикса с безопасным URL-адресом, который получает большой трафик.
Консультация по кешу
Когда клиент хочет проверить состояние URL-адреса, он сначала вычисляет его полный хэш. Если префикс полного хеша присутствует в локальной базе данных, клиент должен просмотреть свой кеш, прежде чем отправлять запрос fullHashes на сервер.
Во-первых, клиенты должны проверить наличие положительного попадания в кэш. Если существует неистекшая положительная запись в кэше для полного интересующего хэша, ее следует считать небезопасной. Если срок действия положительной записи кэша истек, клиент должен отправить запрос fullHashes для соответствующего локального префикса. Согласно протоколу, если сервер возвращает полный хэш, это считается небезопасным; в противном случае это считается безопасным.
Если для полного хеша нет положительных записей в кэше, клиент должен проверить наличие отрицательного попадания в кэш. Если для соответствующего локального префикса существует отрицательная запись кэша с истекшим сроком действия, полный хэш считается безопасным. Если срок действия отрицательной записи кэша истек или она не существует, клиент должен отправить запрос fullHashes для соответствующего локального префикса и интерпретировать ответ как обычно.
Обновление кеша
Кэш клиента должен обновляться каждый раз при получении ответа fullHashes . Положительная запись в кэше должна быть создана или обновлена для полного хэша в поле cacheDuration . Отрицательная продолжительность кэша хеш-префикса также должна создаваться или обновляться в соответствии с полем negativeCacheDuration ответа.
Если последующий запрос fullHashes не возвращает полный хеш, который в данный момент положительно кэширован, клиенту не требуется удалять положительную запись кэша. На практике это не вызывает беспокойства, поскольку длительность положительного кэша обычно невелика (несколько минут), что позволяет быстро исправить ложные срабатывания.
Пример сценария
В следующем примере предположим, что h(url) — это хеш-префикс URL-адреса, а H(url) — это полный хэш URL-адреса. То есть h(url) = SHA256(url).substr(4), H(url) = SHA256(url).
Теперь предположим, что клиент (с пустым кешем) посещает example.com/ и видит, что h(example.com/) находится в локальной базе данных. Клиент запрашивает полноразмерные хэши для префикса хэша h(example.com/) и получает обратно полноразмерный хеш H(example.com/) вместе с положительной продолжительностью кэширования 5 минут и отрицательной продолжительностью кэширования 1 час. .
Положительная продолжительность кэша в 5 минут сообщает клиенту, как долго полноразмерный хэш H(example.com/) должен считаться небезопасным без отправки еще одного запроса fullHashes . Через 5 минут клиент должен отправить еще один запрос fullHashes для этого префикса h(example.com/), если клиент снова посетит example.com/. Клиент должен сбросить отрицательную длительность кэша хэш-префикса для каждого нового ответа.
Отрицательная продолжительность кэша, равная 1 часу, сообщает клиенту, как долго все остальные полноразмерные хеши, кроме H(example.com/), которые имеют тот же префикс h(example.com/), должны считаться безопасными. В течение 1 часа каждый URL-адрес, такой как h(URL) = h(example.com/), должен считаться безопасным и, следовательно, не приводить к запросу fullHashes (при условии, что H(URL) != H(example.com) /)).
Если ответ fullHashes содержит ноль совпадений и установлена отрицательная продолжительность кэша, то клиент не должен выдавать какие-либо запросы fullHashes для любого из запрошенных префиксов в течение заданной отрицательной продолжительности кэша.
Если ответ fullHashes содержит одно или несколько совпадений, для всего ответа по-прежнему устанавливается отрицательная длительность кэша. В этом случае продолжительность кэширования одного полного хеша указывает, как долго этот конкретный полноразмерный хеш должен считаться клиентом небезопасным. По истечении срока действия кэша ThreatMatch клиент должен обновить полноразмерный хеш, выдав запрос fullHashes для этого префикса хэша, если запрошенный URL-адрес соответствует существующему полноразмерному хешу в кеше. В этом случае отрицательная длительность кэша не применяется. Отрицательная длительность кэша ответа применяется только к полноразмерным хешам, которые не присутствовали в ответе fullHashes . Для полноразмерных хешей, которые отсутствуют в ответе, клиент должен воздерживаться от выдачи каких-либо запросов fullHashes до тех пор, пока не истечет отрицательная длительность кэша.
Пример: fullHashes.find
Нажмите на ссылки запроса и ответа в заголовке таблицы, чтобы просмотреть полные примеры.
| Хэш-префиксы Запрос FullHashes | Полноразмерные хэш-соответствия Полный ответHashes | Поведение кэширования |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
| "matches": [], "negativeCacheDuration": "3600.000s" | Не совпадает. Клиент не должен отправлять запросы fullHashes для хеш-префикса 0xaaaaaaaa в течение как минимум одного часа. Любой хеш с префиксом 0xaaaaaaaaa считается безопасным в течение одного часа. |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
| Возможные совпадения. Клиент должен считать URL-адрес с полным хешем 0xbbbbbbbb0000… небезопасным в течение 10 минут. Клиент должен считать все остальные URL-адреса с хэш-префиксом 0xbbbbbbbb безопасными в течение 5 минут. Через 5 минут срок действия отрицательной записи кэша хэш-префиксов истечет. Поскольку срок действия положительной записи кэша для 0xbbbbbbbb0000… еще не истек, клиент должен отправлять запросы fullHashes для всех хэшей, кроме этого. |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
| Возможные совпадения. Клиент не должен отправлять запросы fullHashes для хеш-префикса 0xcccccccc в течение как минимум 1 часа и считать, что этот префикс безопасен — за исключением случаев, когда полный хэш URL-адреса соответствует кэшированному полному хешу 0xccccccccdddd.... В этом случае клиент должен учитывать этот URL-адрес. быть небезопасным в течение 10 минут. Через 10 минут срок действия полного хеша истекает. Любые последующие поиски этого полного хеша должны вызывать новый запрос fullHashes . |