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

Обзор

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

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

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

• Запрос HTTP POST может включать до 500 URL-адресов. URL-адреса должны быть действительными (см. RFC 2396 ), но их не обязательно канонизировать или кодировать.
• Ответ HTTP POST возвращает соответствующие URL-адреса вместе с продолжительностью кэша.

Пример: ThreatMatches.find

HTTP POST-запрос

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

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

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

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

Тело запроса

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

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

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

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

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

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

URL-адреса угроз

В этом примере массив threatEntries содержит три URL-адреса (urltocheck1.org, urltocheck2.org и urltocheck3.org), которые будут проверены на соответствие двум спискам безопасного просмотра.

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

HTTP POST-ответ

В следующем примере ответ возвращает совпадение; два из трех URL-адресов, указанных в запросе, находятся в одном из двух списков безопасного просмотра, указанных в запросе.

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

Заголовок ответа включает код состояния HTTP и тип контента.

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

Тело ответа

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

Примечание. Если совпадений нет (то есть если ни один из URL-адресов, указанных в запросе, не найден ни в одном из списков, указанных в запросе), ответ HTTP POST просто возвращает пустой объект в теле ответа.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Матчи

Объект matches перечисляет имена списков безопасного просмотра и URL-адреса, если они совпадают. В этом примере два URL-адреса (urltocheck1.org и urltocheck2.org) были обнаружены в одном из списков безопасного просмотра (MALWARE/WINDOWS/URL), поэтому возвращается совпадающая информация. Третий URL-адрес (urltocheck3.org) не найден ни в одном из списков, поэтому для этого URL-адреса не возвращается никакая информация.

Метаданные

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

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

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