Interfejs API Bezpiecznego przeglądania Lookup (wersja 4)

Opis

Interfejs Lookup API umożliwia aplikacjom klienckim wysyłanie żądań do serwerów Bezpiecznego przeglądania w celu sprawdzenia, czy adresy URL znajdują się na listach Bezpiecznego przeglądania. Jeśli adres URL zostanie znaleziony na co najmniej jednej liście, zwracane są pasujące informacje.

Sprawdzam adresy URL

Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, wyślij żądanie HTTP POST do metody threatMatches.find:

• Żądanie HTTP POST może zawierać do 500 adresów URL. Muszą one być prawidłowe (patrz RFC 2396), ale nie muszą być kanoniczne ani zakodowane.
• Odpowiedź HTTP POST zwraca pasujące adresy URL wraz z czasem trwania pamięci podręcznej.

Przykład: threatMatch.find

Żądanie POST HTTP

W poniższym przykładzie do serwera są wysyłane 2 listy Bezpiecznego przeglądania i 3 adresy URL w celu sprawdzenia, czy występuje dopasowanie.

Nagłówek żądania

Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API kluczem API_KEY w adresie URL.

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

Treść żądania

Treść żądania zawiera informacje o kliencie (identyfikator i wersja) oraz informacje o zagrożeniu (nazwy list i adresy URL). Więcej informacji znajdziesz w treści żądania o threatMatch.find i w wyjaśnieniach po przykładowym kodzie.

  {
    "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/"}
      ]
    }
  }

Informacje o kliencie

Pola clientID i clientVersion powinny jednoznacznie identyfikować implementację klienta, a nie użytkownika. (Informacje o kliencie są używane do logowania i księgowania po stronie serwera. Możesz wybrać dowolną nazwę identyfikatora klienta, ale zalecamy użycie nazwy reprezentującej prawdziwą tożsamość klienta, np. nazwę firmy, przedstawione w postaci jednego słowa, małymi literami).

Listy Bezpiecznego przeglądania

Pola threatType, platformType i threatEntryType są połączone, aby zidentyfikować (nazwa) listy Bezpiecznego przeglądania. W tym przykładzie zidentyfikowano 2 listy: ZŁOŚLIWE/WINDOWS/URL i SOCIAL_ENGINEERING/WINDOWS/URL. Przed wysłaniem żądania upewnij się, że określone kombinacje typów są prawidłowe (patrz Listy Bezpiecznego przeglądania).

Adresy URL zagrożeń

W przykładzie tablica threatEntries zawiera 3 adresy URL (urltocheck1.org, urltocheck2.org i urltocheck3.org), które zostaną porównane z 2 listami Bezpiecznego przeglądania.

Uwaga: interfejs Lookup API i metoda threatMatches powinny zawsze używać pola URL, a nie pola hash (patrz ThreatEntry).

Odpowiedź HTTP POST

W poniższym przykładzie odpowiedź zwraca dopasowanie. 2 z 3 adresów URL określonych w żądaniu znajdują się na jednej z dwóch list Bezpiecznego przeglądania określonych w żądaniu.

Nagłówek odpowiedzi

Nagłówek odpowiedzi zawiera kod stanu HTTP i typ treści.

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

Treść odpowiedzi

Treść odpowiedzi zawiera informacje o dopasowaniu (nazwy list i adresy URL na tych listach, metadane (jeśli są dostępne) oraz czasy trwania pamięci podręcznej). Więcej informacji znajdziesz w treści odpowiedzi o zagrożeniu.find (w języku angielskim) i wyjaśnieniach za pomocą przykładowego kodu.

Uwaga: jeśli nie ma dopasowań (czyli jeśli nie ma adresów URL określonych w żądaniu na żadnej liście określonej w żądaniu), odpowiedź HTTP POST zwraca po prostu pusty obiekt w treści odpowiedzi.

{
  "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"
  }]
}

Odpowiada

Obiekt matches zawiera nazwy list Bezpiecznego przeglądania i adresy URL, jeśli występują. W tym przykładzie na jednej z list Bezpiecznego przeglądania (MALWARE/WINDOWS/URL) znaleziono 2 adresy URL (urltocheck1.org i urltocheck2.org), więc zwracane są pasujące informacje. Trzeciego adresu URL (urltocheck3.org) nie znaleziono na żadnej liście, dlatego nie są zwracane żadne informacje.

Metadane

Pole threatEntryMetadata jest opcjonalne i zawiera dodatkowe informacje o dopasowaniu zagrożenia. Obecnie metadane są dostępne w przypadku listy Bezpieczne przeglądanie dotyczące MALWARE/WINDOWS/URL-a (patrz Metadane).

Czasy trwania pamięci podręcznej

Pole cacheDuration wskazuje, przez jaki czas adres URL musi zostać uznany za niebezpieczny (patrz Zapisywanie w pamięci podręcznej).