Method: hashes.search

Wyszukuje pełne hasze pasujące do określonych prefiksów.

Jest to metoda niestandardowa zdefiniowana na stronie https://google.aip.dev/136 (metoda niestandardowa ma niestandardową nazwę w ogólnej nomenklaturze tworzenia interfejsów API Google; nie odnosi się do używania niestandardowej metody HTTP).

Żądanie HTTP

GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search

Adres URL używa składni transkodowania gRPC.

Parametry zapytania

Parametry
hashPrefixes[]

string (bytes format)

Wymagane. Prefiksy wartości hash do wyszukania. Klienci NIE MOGĄ wysyłać więcej niż 1000 prefiksów skrótu. Jednak po wykonaniu procedury przetwarzania adresów URL klienci NIE POWINNI wysyłać więcej niż 30 prefiksów skrótów.

Obecnie każdy prefiks skrótu musi mieć dokładnie 4 bajty. W przyszłości MOŻE to zostać złagodzone.

Ciąg zakodowany w formacie Base64.
filter

string

Opcjonalnie. Jeśli klient jest zainteresowany filtrowaniem, np. pobieraniem tylko określonych rodzajów zagrożeń, może to określić. Jeśli zostanie pominięty, zwracane są wszystkie pasujące zagrożenia. Zdecydowanie zalecamy pominięcie tego kroku, aby uzyskać najpełniejszą ochronę, jaką może zapewnić Bezpieczne przeglądanie.

Filtr jest określany za pomocą języka Common Expression Language od Google, który wraz z ogólnymi przykładami znajdziesz na stronie https://github.com/google/cel-spec. Oto kilka konkretnych przykładów, które można tu wykorzystać:

Filtr "threatType == ThreatType.SOCIAL_ENGINEERING" wymaga, aby w ramach FullHashDetail typ zagrożenia był równy SOCIAL_ENGINEERING. Identyfikator "threatType" odnosi się do bieżącego typu zagrożenia. Identyfikator "ThreatType" odnosi się do zbioru wszystkich możliwych typów zagrożeń.

Filtr "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" wymaga, aby typ zagrożenia miał wartość UNWANTED_SOFTWARE lub MALWARE.

Treść żądania

Treść żądania musi być pusta.

Treść odpowiedzi

Odpowiedź zwracana po wyszukaniu skrótów zagrożeń.

Jeśli nic nie zostanie znalezione, serwer zwróci stan OK (kod stanu HTTP 200) z pustym polem fullHashes, a nie stan NOT_FOUND (kod stanu HTTP 404).

Nowości w wersji 5: nastąpiło rozdzielenie FullHash i FullHashDetail. Jeśli skrót reprezentuje witrynę, w której występuje wiele zagrożeń (np. MALWARE i SOCIAL_ENGINEERING), nie trzeba go wysyłać 2 razy, jak w przypadku wersji 4. Dodatkowo czas trwania pamięci podręcznej został uproszczony do jednego pola cacheDuration.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Pola
fullHashes[]

object (FullHash)

Lista nieuporządkowana. Nieuporządkowana lista znalezionych pełnych skrótów.
cacheDuration

string (Duration format)

Czas trwania pamięci podręcznej po stronie klienta. Klient MUSI dodać ten czas do bieżącego czasu, aby określić czas wygaśnięcia. Czas wygaśnięcia dotyczy wtedy każdego prefiksu skrótu, o który klient wysyła zapytanie w żądaniu, niezależnie od tego, ile pełnych skrótów jest zwracanych w odpowiedzi. Nawet jeśli serwer nie zwróci pełnych skrótów dla danego prefiksu skrótu, klient MUSI zapisać tę informację w pamięci podręcznej.

Jeśli pole fullHashes jest puste, klient MOŻE zwiększyć wartość cacheDuration, aby określić nowy termin ważności, który jest późniejszy niż ten określony przez serwer. W każdym przypadku wydłużony czas trwania pamięci podręcznej nie może przekraczać 24 godzin.

Ważne: klient NIE MOŻE zakładać, że serwer zwróci ten sam czas trwania pamięci podręcznej dla wszystkich odpowiedzi. Serwer MOŻE wybrać różne czasy trwania pamięci podręcznej dla różnych odpowiedzi w zależności od sytuacji.

Czas trwania w sekundach z maksymalnie 9 miejscami po przecinku, zakończony znakiem „s”. Przykład: "3.5s".

FullHash

Pełny hash zidentyfikowany z co najmniej 1 dopasowaniem.

Zapis JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Pola
fullHash

string (bytes format)

Pasujący pełny skrót. Jest to identyfikator SHA256. Długość będzie wynosić dokładnie 32 bajty.

Ciąg zakodowany w formacie Base64.
fullHashDetails[]

object (FullHashDetail)

Lista nieuporządkowana. Powtarzające się pole zawierające szczegóły dotyczące tego pełnego skrótu.

FullHashDetail

Szczegóły pasującego pełnego skrótu.

Ważna uwaga dotycząca zgodności z przyszłymi wersjami: serwer może w dowolnym momencie dodawać nowe typy zagrożeń i ich atrybuty. Takie dodatki są traktowane jako zmiany w wersji podrzędnej. Zgodnie z zasadami Google nie udostępnia w interfejsach API numerów wersji podrzędnych (zasady dotyczące wersji znajdziesz na stronie https://cloud.google.com/apis/design/versioning), więc klienty MUSZĄ być przygotowane na odbieranie wiadomości FullHashDetail zawierających wartości wyliczeniowe ThreatType lub ThreatAttribute, które są przez nie uznawane za nieprawidłowe. Dlatego klient jest odpowiedzialny za sprawdzanie ważności wszystkich wartości wyliczeniowych ThreatType i ThreatAttribute. Jeśli jakakolwiek wartość zostanie uznana za nieprawidłową, klient MUSI zignorować całą wiadomość FullHashDetail.

Zapis JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Pola
threatType

enum (ThreatType)

Rodzaj zagrożenia. To pole nigdy nie będzie puste.
attributes[]

enum (ThreatAttribute)

Lista nieuporządkowana. Dodatkowe atrybuty tych pełnych skrótów. To pole może być puste.

ThreatAttribute

Atrybuty zagrożeń. Atrybuty te mogą nadawać dodatkowe znaczenie konkretnemu zagrożeniu, ale nie wpływają na jego typ. Na przykład jeden atrybut może określać niższy poziom ufności, a inny – wyższy. W przyszłości możemy dodać więcej atrybutów.

Wartości w polu enum
THREAT_ATTRIBUTE_UNSPECIFIED Nieznany atrybut. Jeśli serwer zwróci ten kod, klient całkowicie zignoruje otaczający go znak FullHashDetail.
CANARY Wskazuje, że typu zagrożenia nie należy używać do egzekwowania zasad.
FRAME_ONLY Wskazuje, że threatType powinien być używany tylko do egzekwowania zasad w przypadku ramek.