Opis
Interfejs Update API umożliwia aplikacjom klienckim pobieranie zaszyfrowanych wersji list Bezpiecznego przeglądania na potrzeby przechowywania ich w lokalnej bazie danych. Adresy URL można wtedy sprawdzać lokalnie. Dopiero po znalezieniu dopasowania w lokalnej bazie danych klient musi wysłać żądanie do serwerów Bezpiecznego przeglądania, aby sprawdzić, czy dany URL znajduje się na listach Bezpiecznego przeglądania.
Zanim użyjesz interfejsu Update API, musisz skonfigurować lokalną bazę danych. Bezpieczne przeglądanie udostępnia pakiet Go, którego możesz użyć na początku. Więcej informacji znajdziesz w sekcji Konfiguracja bazy danych w sekcji Lokalne bazy danych.
Aktualizowanie lokalnej bazy danych
Aby być na bieżąco, klienci muszą okresowo aktualizować listy Bezpiecznego przeglądania w lokalnej bazie danych. Aby oszczędzać przepustowość, klienci pobierają prefiksy skrótów adresów URL zamiast nieprzetworzonych adresów URL. Jeśli na przykład na liście Bezpiecznego przeglądania znajduje się ciąg „www.badurl.com/”, klient pobiera prefiks skrótu SHA256 tego adresu URL, a nie sam adres URL. W większości przypadków prefiksy skrótów mają 4 bajty, co oznacza, że średni koszt przepustowości pobierania jednej pozycji na liście wynosi 4 bajty przed skompresowaniem.
Aby zaktualizować listy Bezpiecznego przeglądania w lokalnej bazie danych, wyślij żądanie HTTP POST
do metody threatListUpdates.fetch:
- Żądanie HTTP
POST
zawiera nazwy list do zaktualizowania oraz różne ograniczenia klienta, aby uwzględnić ograniczenia pamięci i przepustowości. - Odpowiedź HTTP
POST
zwraca pełną lub częściową aktualizację. Odpowiedź może też zwracać minimalny czas oczekiwania.
Przykład: threatListUpdates.fetch
Żądanie POST HTTP
W poniższym przykładzie żądane są aktualizacje pojedynczej listy Bezpiecznego przeglądania.
Nagłówek żądania
Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API w adresie URL fragmentem API_KEY
.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Treść żądania
Treść żądania zawiera informacje o kliencie (identyfikator i wersja) oraz informacje o aktualizacji (nazwę listy, stan listy i ograniczenia dotyczące klienta). Więcej informacji znajdziesz w treści żądania o threatListUpdates.fetch oraz w objaśnieniach za pomocą przykładowego kodu.
{ "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"] } }] }
Informacje o kliencie
Pola clientID
i clientVersion
powinny jednoznacznie identyfikować implementację klienta, a nie użytkownika. Informacje o kliencie są używane do logowania 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 identyfikujemy jedną listę: ZŁOŚLIWE OPROGRAMOWANIE/WINDOWS/URL. Przed wysłaniem żądania upewnij się, że wybrane kombinacje typów są prawidłowe (patrz Listy Bezpiecznego przeglądania).
Stan klienta
Pole state
zawiera bieżący stan klienta listy Bezpieczne przeglądanie.
(Stany klienta są zwracane w polu newClientState
odpowiedzi threatListUpdates.fetch).
Aby przeprowadzić wstępną aktualizację, pozostaw pole state
puste.
Ograniczenia rozmiaru
Pole maxUpdateEntries
określa łączną liczbę aktualizacji, którymi może zarządzać klient (w tym przykładzie jest to 2048). Pole maxDatabaseEntries
określa łączną liczbę wpisów, którymi może zarządzać lokalna baza danych (w tym przykładzie jest to 4096). Klienty powinny ustawiać ograniczenia rozmiaru, aby chronić pamięć oraz przepustowość i uchronić się przed wzrostem liczby list. Aby dowiedzieć się więcej,
(zobacz Aktualizowanie ograniczeń).
Obsługiwane kompresje
W polu supportedCompressions
wymienione są typy kompresji obsługiwane przez klienta. W tym przykładzie klient obsługuje tylko nieprzetworzone, nieskompresowane dane. Bezpieczne przeglądanie obsługuje jednak dodatkowe typy kompresji (patrz Kompresja).
Odpowiedź HTTP POST
W tym przykładzie odpowiedź zwraca częściową aktualizację listy Bezpieczne przeglądanie korzystające z żądanego typu kompresji.
Nagłówek odpowiedzi
Nagłówek odpowiedzi zawiera kod stanu HTTP i typ treści. Klienci, którzy otrzymują kod stanu inny niż HTTP/200, muszą przejść w tryb wycofywania (patrz Częstotliwość żądań).
HTTP/1.1 200 OK Content-Type: application/json
Treść odpowiedzi
Treść odpowiedzi zawiera informacje o aktualizacji (nazwę listy, typ odpowiedzi, dodane i usunięte elementy, które mają zostać zastosowane do lokalnej bazy danych, nowy stan klienta oraz sumę kontrolną). W tym przykładzie odpowiedź zawiera też minimalny czas oczekiwania. Więcej informacji znajdziesz w treści odpowiedzi związanej z threatListUpdates.fetch oraz w objaśnieniach za pomocą przykładowego kodu.
{ "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" }
Aktualizacje bazy danych
Pole responseType
wskazuje częściową lub pełną aktualizację. W tym przykładzie zwracana jest częściowa aktualizacja, więc odpowiedź obejmuje zarówno dodanie, jak i usunięcie. Może być wiele zestawów zmian, ale tylko 1 zestaw usunięć (patrz Aktualizacje bazy danych).
Nowy stan klienta
Pole newClientState
zawiera nowy stan klienta dla niedawno zaktualizowanej listy Bezpieczne przeglądanie.
Klienty muszą zapisać nowy stan klienta na potrzeby kolejnych żądań aktualizacji (pole state
w żądaniu threatListUpdates.fetch lub clientStates
w fullHashes.find żądaniach).
Sumy kontrolne
Suma kontrolna umożliwia klientom sprawdzenie, czy lokalna baza danych nie uległa uszkodzeniu. Jeśli suma kontrolna się nie zgadza, klient musi wyczyścić bazę danych i ponownie wykonać aktualizację z pustym polem state
. W tej sytuacji klienci muszą jednak nadal przestrzegać przedziałów czasowych aktualizacji (patrz Częstotliwość żądań).
Minimalny czas oczekiwania
Pole minimumWaitDuration
wskazuje, że klient musi odczekać 593,44 sekundy (9,89 minuty) przed wysłaniem kolejnego żądania aktualizacji. Pamiętaj, że w odpowiedzi może zostać uwzględniony okres oczekiwania (patrz Częstotliwość żądań).
Sprawdzam adresy URL
Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, klient musi najpierw obliczyć prefiks i hashtagu adresu URL (patrz Adresy URL i haszowanie). Klient wysyła zapytanie do lokalnej bazy danych, aby sprawdzić, czy występuje dopasowanie. Jeśli w lokalnej bazie danych nie ma prefiksu skrótu, adres URL jest uznawany za bezpieczny (nie ma go na listach Bezpiecznego przeglądania).
Jeśli prefiks skrótu jest obecny w lokalnej bazie danych (konflikt prefiksów), klient musi wysłać go do serwerów Bezpiecznego przeglądania w celu weryfikacji. Serwery zwracają wszystkie skróty SHA256 pełnej długości zawierające podany prefiks skrótu. Jeśli jeden z tych haszów pełnej długości odpowiada haszu pełnej długości adresu URL, którego dotyczy zgłoszenie, adres URL jest uznawany za niebezpieczny. Jeśli żaden z skrótów pełnej długości nie odpowiada haszu pełnej długości adresu URL, którego dotyczy zgłoszenie, adres URL jest uznawany za bezpieczny.
W żadnym momencie Google nie uzyskuje informacji o sprawdzanych przez Ciebie adresach URL. Google rozpoznaje prefiksy skrótów adresów URL, ale nie zapewniają one wielu informacji o rzeczywistych adresach URL.
Aby sprawdzić, czy adres URL znajduje się na liście Bezpiecznego przeglądania, wyślij żądanie HTTP POST
za pomocą metody fullHashes.find:
- Żądanie HTTP
POST
może zawierać do 500 pozycji o zagrożeniu. - Żądanie HTTP
POST
zawiera prefiksy skrótu adresów URL do sprawdzenia. Zachęcamy klientów do grupowania wielu wpisów o zagrożeniach w jednym żądaniu w celu zmniejszenia wykorzystania przepustowości. - Odpowiedź HTTP
POST
zwraca pasujące hasze pełnej długości oraz dodatnie i ujemne wartości czasu trwania pamięci podręcznej. Odpowiedź może też zwracać minimalny czas oczekiwania.
Przykład: pełneHashes.find
Żądanie POST HTTP
W poniższym przykładzie nazwy 2 list Bezpiecznego przeglądania i 3 prefiksy skrótu są wysyłane do porównania i weryfikacji.
Nagłówek żądania
Nagłówek żądania zawiera adres URL żądania i typ treści. Pamiętaj, aby zastąpić klucz interfejsu API ciągiem API_KEY
w adresie URL.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Treść żądania
Treść żądania zawiera informacje o kliencie (identyfikator i wersja), stany klienta oraz informacje o zagrożeniu (nazwy list i prefiksy skrótu). W przypadku żądań JSON prefiksy skrótu muszą być wysyłane w postaci zakodowanej w formacie base64. Więcej informacji znajdziesz w treści żądania fullHashes.find oraz w wyjaśnieniach po przykładowym kodzie.
{ "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=="} ] } }
Informacje o kliencie
Pola clientID
i clientVersion
powinny jednoznacznie identyfikować implementację klienta, a nie użytkownika. Informacje o kliencie są używane do logowania po stronie serwera. Możesz wybrać dowolną nazwę identyfikatora klienta, ale zalecamy wybranie nazwy reprezentującej prawdziwą tożsamość klienta, np. nazwę firmy, przedstawione w postaci jednego słowa, małymi literami).
Wszystkie stany klientów
Pole clientStates
zawiera stany klienta wszystkich list Bezpiecznego przeglądania w lokalnej bazie danych klienta. (Stany klienta są zwracane w polu newClientState
odpowiedzi threatListUpdates.fetch).
Listy Bezpiecznego przeglądania
Pola threatTypes
, platformTypes
i threatEntryTypes
łączą się, 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).
Prefiksy skrótu zagrożenia
Tablica threatEntries zawiera prefiksy skrótów adresów URL, które chcesz sprawdzić.
Pole hash
musi zawierać dokładnie taki prefiks skrótu, który występuje w lokalnej bazie danych. Jeśli na przykład lokalny prefiks skrótu ma 4 bajty, wpis o zagrożeniu musi mieć 4 bajty. Jeśli prefiks lokalnego skrótu został wydłużony do 7 bajtów, wpis o zagrożeniu musi mieć 7 bajtów.
W przykładzie żądanie zawiera 3 prefiksy skrótu. Wszystkie 3 prefiksy są porównywane z każdą listą Bezpiecznego przeglądania w celu określenia, czy istnieje zgodny hasz o pełnej długości.
Uwaga: interfejs Update API i metoda fullHashes.find powinny zawsze używać pola hash
, a nie pola URL
(patrz ThreatEntry).
Odpowiedź HTTP POST
W poniższym przykładzie odpowiedź zwraca pasujące dane uporządkowane według listy Bezpiecznego przeglądania, wraz z pamięci podręcznej i czasem oczekiwania.
Nagłówek odpowiedzi
Nagłówek odpowiedzi zawiera kod stanu HTTP i typ treści. Klienty, które otrzymają kod stanu inny niż HTTP/200, muszą się wycofać (patrz Częstotliwość żądań).
HTTP/1.1 200 OK Content-Type: application/json
Treść odpowiedzi
Treść odpowiedzi zawiera informacje o dopasowaniu (nazwy list i skróty o pełnej długości, metadane (jeśli są dostępne) oraz czasy trwania pamięci podręcznej). W tym przykładzie treść odpowiedzi zawiera też minimalny czas oczekiwania. Więcej informacji znajdziesz w treści odpowiedzi fullHashes.find oraz w wyjaśnieniach po przykładowym kodzie.
{ "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" }
Odpowiada
Obiekt Dopasowania zwraca pasujący hasz o pełnej długości dla 2 prefiksów haszowania. Adresy URL odpowiadające tym haszom są uznawane za niebezpieczne. Nie znaleziono dopasowania dla trzeciego prefiksu skrótu, więc nie jest zwracany wynik. Adres URL odpowiadający temu prefiksowi skrótu jest uznawany za bezpieczny.
Zwróć uwagę, że w tym przykładzie 1 skrót o pełnej długości odpowiada 1 prefiksowi skrótu. Może jednak istnieć wiele pełnych haszów mapowanych na ten sam prefiks.
Metadane
Pole threatEntryMetadata
jest opcjonalne i zawiera dodatkowe informacje o dopasowaniu zagrożeń. 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
Pola cacheDuration
i negativeCacheDuration
wskazują, przez jaki czas hasze muszą zostać uznane za niebezpieczne lub bezpieczne (patrz Zapisywanie w pamięci podręcznej).
Minimalny czas oczekiwania
Pole minimumWaitDuration
wskazuje, że klient musi odczekać 300 sekund (5 minut), zanim wyśle kolejne żądanie fullHashes. Pamiętaj, że okres oczekiwania może, ale nie musi być uwzględniony w odpowiedzi (patrz Częstotliwość żądań).