Эта страница переведена с помощью Cloud Translation API.

API обновления безопасного просмотра (v4)

Обзор

API обновления позволяет вашим клиентским приложениям загружать хешированные версии списков безопасного просмотра для хранения в локальной базе данных. URL-адреса затем можно проверить локально. Только если совпадение обнаружено в локальной базе данных, клиенту необходимо отправить запрос на серверы безопасного просмотра, чтобы проверить, включен ли URL-адрес в списки безопасного просмотра.

Прежде чем использовать API обновления, вам необходимо настроить локальную базу данных. Безопасный просмотр предоставляет пакет Go, который вы можете использовать для начала работы. Более подробную информацию см. в разделе «Настройка базы данных» в разделе «Локальные базы данных» .

Обновление локальной базы данных

Чтобы оставаться в курсе событий, клиентам необходимо периодически обновлять списки безопасного просмотра в своей локальной базе данных. Чтобы сэкономить пропускную способность, клиенты загружают хеш-префиксы URL-адресов, а не необработанные URL-адреса. Например, если www.badurl.com/ находится в списке безопасного просмотра, клиенты загружают префикс хэша SHA256 этого URL-адреса, а не сам URL-адрес. В большинстве случаев хеш-префиксы имеют длину 4 байта, что означает, что средняя стоимость полосы пропускания для загрузки одной записи списка составляет 4 байта до сжатия.

Чтобы обновить списки безопасного просмотра в локальной базе данных, отправьте HTTP-запрос POST методу ThreatListUpdates.fetch :

Запрос HTTP POST включает имена обновляемых списков, а также различные ограничения клиента для учета ограничений памяти и пропускной способности.
Ответ HTTP POST возвращает либо полное обновление, либо частичное обновление. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: ThreatListUpdates.fetch

HTTP POST-запрос

В следующем примере запрашиваются обновления для одного списка безопасного просмотра.

Заголовок запроса

Заголовок запроса включает URL-адрес запроса и тип контента. Не забудьте заменить API_KEY в URL-адресе на свой ключ API.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

Тело запроса включает информацию о клиенте (идентификатор и версию) и информацию об обновлении (имя списка, состояние списка и ограничения клиента). Дополнительные сведения см. в тексте запроса ThreatListUpdates.fetch и пояснениях, следующих за примером кода.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например, название вашей компании, представленное одним словом, во всех - строчные буквы.)

Списки безопасного просмотра

Поля threatType , platformType и threatEntryType объединяются для идентификации (именования) списков безопасного просмотра. В примере указан один список: MALWARE/WINDOWS/URL. Прежде чем отправлять запрос, убедитесь, что указанные вами комбинации типов действительны (см. Списки безопасного просмотра ).

Состояние клиента

Поле state содержит текущее состояние клиента в списке безопасного просмотра. (Состояния клиента возвращаются в поле newClientState ответа ThreatListUpdates.fetch .) Для первоначальных обновлений оставьте поле state пустым.

Ограничения по размеру

Поле maxUpdateEntries указывает общее количество обновлений, которыми может управлять клиент (в примере — 2048). Поле maxDatabaseEntries указывает общее количество записей, которыми может управлять локальная база данных (в примере — 4096). Клиенты должны устанавливать ограничения на размер, чтобы защитить ограничения памяти и пропускной способности, а также предотвратить рост списка. Дополнительные сведения см. в разделе «Ограничения обновления ».

Поддерживаемые сжатия

В поле supportedCompressions перечислены типы сжатия, поддерживаемые клиентом. В этом примере клиент поддерживает только необработанные несжатые данные. Однако безопасный просмотр поддерживает дополнительные типы сжатия (см. Сжатие ).

HTTP POST-ответ

В этом примере ответ возвращает частичное обновление списка безопасного просмотра с использованием запрошенного типа сжатия.

Заголовок ответа

Заголовок ответа включает код состояния HTTP и тип контента. Клиенты, которые получают код состояния, отличный от HTTP/200, должны войти в режим отсрочки (см. Частота запросов ).

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

Тело ответа включает информацию об обновлении (имя списка, тип ответа, добавления и удаления, которые будут применены к локальной базе данных, новое состояние клиента и контрольную сумму). В этом примере ответ также включает минимальную продолжительность ожидания. Дополнительные сведения см. в тексте ответа ThreatListUpdates.fetch и пояснениях, следующих за примером кода.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Обновления базы данных

Поле responseType будет указывать частичное или полное обновление. В этом примере возвращается частичное обновление, поэтому ответ включает как добавления, так и удаления. Может быть несколько наборов добавлений, но только один набор удалений (см. Обновления базы данных ).

Новое состояние клиента

Поле newClientState содержит новое состояние клиента для недавно обновленного списка безопасного просмотра. Клиенты должны сохранить новое состояние клиента для последующих запросов на обновление (поле state в запросе ThreatListUpdates.fetch или поле clientStates в запросе fullHashes.find ).

Контрольные суммы

Контрольная сумма позволяет клиентам убедиться, что локальная база данных не повреждена. Если контрольная сумма не совпадает, клиент должен очистить базу данных и повторно выпустить обновление с пустым полем state . Однако клиенты в этой ситуации все равно должны соблюдать временные интервалы обновлений (см. Частота запросов ).

Минимальная продолжительность ожидания

Поле minimumWaitDuration указывает, что клиент должен подождать 593,44 секунды (9,89 минуты) перед отправкой следующего запроса на обновление. Обратите внимание, что период ожидания может быть включен или не включен в ответ (см. Частота запросов ).

Проверка URL-адресов

Чтобы проверить, находится ли URL-адрес в списке безопасного просмотра, клиент должен сначала вычислить хэш и префикс хеш-адреса URL-адреса (см. URL-адреса и хеширование ). Затем клиент запрашивает локальную базу данных, чтобы определить, есть ли совпадение. Если префикс хеша отсутствует в локальной базе данных, URL-адрес считается безопасным (не в списках безопасного просмотра).

Если префикс хеш-функции присутствует в локальной базе данных (конфликт префикса хеш-функции), клиент должен отправить префикс хеш-функции на серверы безопасного просмотра для проверки. Серверы вернут все полноразмерные хеши SHA 256, содержащие заданный префикс хеша. Если один из этих полноразмерных хешей совпадает с полноразмерным хешем рассматриваемого URL-адреса, то URL-адрес считается небезопасным. Если ни один из полноразмерных хешей не соответствует полному хешу рассматриваемого URL-адреса, этот URL-адрес считается безопасным.

Google ни в коем случае не узнает об URL-адресах, которые вы проверяете. Google запоминает хэш-префиксы URL-адресов, но они не предоставляют много информации о реальных URL-адресах.

Чтобы проверить, находится ли URL-адрес в списке безопасного просмотра, отправьте HTTP-запрос POST методу fullHashes.find :

Запрос HTTP POST может включать до 500 записей об угрозах.
Запрос HTTP POST включает хэш-префиксы проверяемых URL-адресов. Клиентам рекомендуется объединять несколько записей об угрозах в один запрос, чтобы снизить использование полосы пропускания.
Ответ HTTP POST возвращает соответствующие полноразмерные хеши, а также положительную и отрицательную длительность кэша. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: fullHashes.find

HTTP POST-запрос

В следующем примере имена двух списков безопасного просмотра и трех префиксов хеша отправляются для сравнения и проверки.

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

Тело запроса включает информацию о клиенте (идентификатор и версию), состояния клиента и информацию об угрозах (имена списков и хеш-префиксы). Для запросов JSON префиксы хэша должны отправляться в форме, закодированной в формате Base64. Дополнительные сведения см. в теле запроса fullHashes.find и пояснениях, следующих за примером кода.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например название вашей компании, представленное одним словом, в только строчные буквы.)

Все состояния клиента

Поле clientStates содержит состояния клиента для всех списков безопасного просмотра в локальной базе данных клиента. (Состояния клиента возвращаются в поле newClientState ответа ThreatListUpdates.fetch .)

Списки безопасного просмотра

Поля threatTypes , platformTypes и threatEntryTypes объединяются для идентификации (именования) списков безопасного просмотра. В примере идентифицируются два списка: MALWARE/WINDOWS/URL и SOCIAL_ENGINEERING/WINDOWS/URL. Прежде чем отправлять запрос, убедитесь, что указанные вами комбинации типов действительны (см. Списки безопасного просмотра ).

Префиксы хэшей угроз

Массив ThreatEntries содержит хеш-префиксы URL-адресов, которые вы хотите проверить. Поле hash должно содержать точный префикс хэша, который присутствует в локальной базе данных. Например, если длина локального хеш-префикса составляет 4 байта, то длина записи об угрозе должна составлять 4 байта. Если префикс локального хэша был увеличен до 7 байт, то длина записи об угрозе должна составлять 7 байт.

В примере запрос включает три префикса хеша. Все три префикса будут сравниваться с каждым из списков безопасного просмотра, чтобы определить, существует ли соответствующий полный хэш.

Примечание. API обновления и метод fullHashes.find всегда должны использовать поле hash , а не поле URL (см. ThreatEntry ).

HTTP POST-ответ

В следующем примере ответ возвращает соответствующие данные, организованные по списку безопасного просмотра, а также длительность кэша и ожидания.

Заголовок ответа

Заголовок ответа включает код состояния HTTP и тип контента. Клиенты, получившие код состояния, отличный от HTTP/200, должны отключиться (см. Частота запросов ).

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

Тело ответа включает информацию о совпадении (имена списков и полные хэши, метаданные, если они доступны, и длительность кэша). В этом примере тело ответа также включает минимальную продолжительность ожидания. Дополнительные сведения см. в теле ответа fullHashes.find и пояснениях, следующих за примером кода.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Матчи

Объект Matches возвращает соответствующий полный хэш для двух префиксов хеша. URL-адреса, соответствующие этим хешам, считаются небезопасными. Для третьего префикса хеш-функции не найдено совпадений, поэтому ничего не возвращается; URL-адрес, соответствующий этому хеш-префиксу, считается безопасным.

Обратите внимание, что в этом примере один полный хеш соответствует одному хэш-префиксу; однако может быть несколько полных хешей, которые соответствуют одному и тому же префиксу хеша.

Метаданные

Поле threatEntryMetadata является необязательным и предоставляет дополнительную информацию о совпадении угрозы. В настоящее время метаданные доступны для списка безопасного просмотра MALWARE/WINDOWS/URL (см. Метаданные ).

Длительность кэша

Поля cacheDuration и negativeCacheDuration указывают время, в течение которого хэши должны считаться небезопасными или безопасными (см. Кэширование ).

Минимальная продолжительность ожидания

Поле minimumWaitDuration указывает, что клиент должен подождать 300 секунд (5 минут) перед отправкой еще одного запроса FullHashes. Обратите внимание, что период ожидания может быть включен или не включен в ответ (см. Частота запросов ).

Обзор

Обновление локальной базы данных

Запрос HTTP POST включает имена обновляемых списков, а также различные ограничения клиента для учета ограничений памяти и пропускной способности.
Ответ HTTP POST возвращает либо полное обновление, либо частичное обновление. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: ThreatListUpdates.fetch

HTTP POST-запрос

В следующем примере запрашиваются обновления для одного списка безопасного просмотра.

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Информация о клиенте

Списки безопасного просмотра

Состояние клиента

Ограничения по размеру

Поддерживаемые сжатия

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Обновления базы данных

Новое состояние клиента

Контрольные суммы

Минимальная продолжительность ожидания

Проверка URL-адресов

Запрос HTTP POST может включать до 500 записей об угрозах.
Запрос HTTP POST включает хэш-префиксы проверяемых URL-адресов. Клиентам рекомендуется объединять несколько записей об угрозах в один запрос, чтобы снизить использование полосы пропускания.
Ответ HTTP POST возвращает соответствующие полноразмерные хеши, а также положительную и отрицательную длительность кэша. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: fullHashes.find

HTTP POST-запрос

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например название вашей компании, представленное одним словом, в только строчные буквы.)

Все состояния клиента

Списки безопасного просмотра

Префиксы хэшей угроз

Примечание. API обновления и метод fullHashes.find всегда должны использовать поле hash , а не поле URL (см. ThreatEntry ).

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Матчи

Метаданные

Длительность кэша

Минимальная продолжительность ожидания

Обзор

Обновление локальной базы данных

Запрос HTTP POST включает имена обновляемых списков, а также различные ограничения клиента для учета ограничений памяти и пропускной способности.
Ответ HTTP POST возвращает либо полное обновление, либо частичное обновление. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: ThreatListUpdates.fetch

HTTP POST-запрос

В следующем примере запрашиваются обновления для одного списка безопасного просмотра.

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Информация о клиенте

Списки безопасного просмотра

Состояние клиента

Ограничения по размеру

Поддерживаемые сжатия

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Обновления базы данных

Новое состояние клиента

Контрольные суммы

Минимальная продолжительность ожидания

Проверка URL-адресов

Запрос HTTP POST может включать до 500 записей об угрозах.
Запрос HTTP POST включает хэш-префиксы проверяемых URL-адресов. Клиентам рекомендуется объединять несколько записей об угрозах в один запрос, чтобы снизить использование полосы пропускания.
Ответ HTTP POST возвращает соответствующие полноразмерные хеши, а также положительную и отрицательную длительность кэша. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: fullHashes.find

HTTP POST-запрос

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например название вашей компании, представленное одним словом, в только строчные буквы.)

Все состояния клиента

Списки безопасного просмотра

Префиксы хэшей угроз

Примечание. API обновления и метод fullHashes.find всегда должны использовать поле hash , а не поле URL (см. ThreatEntry ).

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Матчи

Метаданные

Длительность кэша

Минимальная продолжительность ожидания

Обзор

Обновление локальной базы данных

Запрос HTTP POST включает имена обновляемых списков, а также различные ограничения клиента для учета ограничений памяти и пропускной способности.
Ответ HTTP POST возвращает либо полное обновление, либо частичное обновление. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: ThreatListUpdates.fetch

HTTP POST-запрос

В следующем примере запрашиваются обновления для одного списка безопасного просмотра.

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Информация о клиенте

Списки безопасного просмотра

Состояние клиента

Ограничения по размеру

Поддерживаемые сжатия

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Обновления базы данных

Новое состояние клиента

Контрольные суммы

Минимальная продолжительность ожидания

Проверка URL-адресов

Запрос HTTP POST может включать до 500 записей об угрозах.
Запрос HTTP POST включает хэш-префиксы проверяемых URL-адресов. Клиентам рекомендуется объединять несколько записей об угрозах в один запрос, чтобы снизить использование полосы пропускания.
Ответ HTTP POST возвращает соответствующие полноразмерные хеши, а также положительную и отрицательную длительность кэша. Ответ также может возвращать минимальную продолжительность ожидания.

Пример: fullHashes.find

HTTP POST-запрос

Заголовок запроса

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Тело запроса

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Информация о клиенте

Поля clientID и clientVersion должны однозначно идентифицировать реализацию клиента, а не отдельного пользователя. (Информация о клиенте используется при регистрации на стороне сервера. Вы можете выбрать любое имя для идентификатора клиента, но мы предлагаем вам выбрать имя, которое отражает истинную личность клиента, например название вашей компании, представленное одним словом, в только строчные буквы.)

Все состояния клиента

Списки безопасного просмотра

Префиксы хэшей угроз

Примечание. API обновления и метод fullHashes.find всегда должны использовать поле hash , а не поле URL (см. ThreatEntry ).

HTTP POST-ответ

Заголовок ответа

HTTP/1.1 200 OK
Content-Type: application/json

Тело ответа

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}