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).