Method: hashes.search

Wyszukiwanie pełnych haszy pasujących do określonych prefiksów.

Jest to metoda niestandardowa zdefiniowana na stronie https://google.aip.dev/136. Jest to metoda, która odnosi się do metody mającej niestandardową nazwę w ogólnym nomenklaturze programistycznego Google dotyczącej interfejsów API; nie odnosi się do korzystania z 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 skrótu do wyszukania. Klienty NIE MOGĄ wysyłać więcej niż 1000 prefiksów skrótu. Jednak zgodnie z procedurą przetwarzania adresów URL klienci NIE POWINNY wysyłać więcej niż 30 prefiksów skrótu.

Obecnie każdy prefiks skrótu musi mieć dokładnie 4 bajty długości. W przyszłości MOŻESZ odpocząć.

Ciąg zakodowany w formacie base64.
filter

string

Opcjonalnie: Możesz określić tę opcję, jeśli klient jest zainteresowany filtrowaniem, na przykład pobieraniem tylko określonych rodzajów zagrożeń. Jeśli zostanie pominięty, zwracane są wszystkie pasujące zagrożenia. Zdecydowanie zalecamy pominięcie tego ustawienia w celu uzyskania pełniejszej ochrony, jaką Bezpieczne przeglądanie może zapewnić.

Filtr jest określony przy użyciu języka Google Common Expression Language, który znajdziesz na https://github.com/google/cel-spec wraz z ogólnymi przykładami. Oto kilka konkretnych przykładów:

Filtr "threatType == ThreatType.SOCIAL_ENGINEERING" wymaga, aby w obrębie FullHashDetail typem zagrożenia było 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 typem zagrożenia był UNWANTED_SOFTWARE lub MALWARE.

Treść żądania

Treść żądania musi być pusta.

Treść odpowiedzi

Odpowiedź zwrócona po przeszukaniu haszy zagrożeń.

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

Nowości w wersji 5: FullHash i FullHashDetail są rozdzielone. W przypadku, gdy hasz reprezentuje witrynę z wieloma zagrożeniami (np. zarówno MALWARE, jak i SOCIAL_ENGINEERING), pełny hasz nie musi być przesyłany dwukrotnie niż w wersji 4. Ponadto czas przechowywania w pamięci podręcznej został uproszczony do umieszczenia w jednym polu 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 haszów.
cacheDuration

string (Duration format)

Czas trwania pamięci podręcznej po stronie klienta. Aby określić czas ważności, klient MUSI dodać ten czas do bieżącego czasu. Okres ważności jest następnie stosowany do każdego prefiksu skrótu, którego klient zażąda w żądaniu, niezależnie od tego, ile pełnych haszów zostało zwróconych w odpowiedzi. Nawet jeśli serwer nie zwraca pełnych haszów dla określonego prefiksu skrótu, ten fakt MUSI również być zapisany w pamięci podręcznej klienta.

Jeśli pole fullHashes jest puste, klient MOŻE zwiększyć wartość cacheDuration, aby określić nową datę ważności, która jest późniejsza niż ta określona przez serwer. W żadnym przypadku wydłużenie czasu przechowywania w pamięci podręcznej nie może przekraczać 24 godzin.

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

Czas trwania w sekundach składający się z maksymalnie 9 cyfr po przecinku, kończący się cyfrą „s”. Przykład: "3.5s".

FullHash

Pełny hasz identyfikowany z co najmniej jednym dopasowaniem.

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

string (bytes format)

Pasujący pełny hasz. Jest to identyfikator SHA256. Będzie on miał dokładnie 32 bajty.

Ciąg zakodowany w formacie base64.
fullHashDetails[]

object (FullHashDetail)

Lista nieuporządkowana. Pole powtarzane identyfikujące szczegóły dotyczące tego pełnego hasza.

FullHashDetail

Szczegółowe informacje o pasującym pełnym haszie.

Ważna uwaga na temat zgodności z przekierowywaniem: serwer w dowolnym momencie może dodawać nowe typy zagrożeń i atrybuty zagrożeń. takie dodatki są uznawane za drobne zmiany w wersji. Zasadą obsługi wersji jest zasady Google, które nie ujawniają numerów wersji podrzędnych w interfejsach API (zasady obsługi wersji znajdziesz na stronie https://cloud.google.com/apis/design/versioning), dlatego klienty MUSZĄ być przygotowane na otrzymywanie komunikatów typu FullHashDetail zawierających wartości wyliczeniowe ThreatType lub ThreatAttribute wartości wyliczeniowe uznane przez klienta za nieprawidłowe. Dlatego to klient odpowiada za sprawdzenie poprawności wszystkich wartości wyliczeniowych ThreatType i ThreatAttribute. Jeśli którakolwiek wartość zostanie uznana za nieprawidłową, klient MUSI zignorować całą wiadomość FullHashDetail.

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

enum (ThreatType)

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

enum (ThreatAttribute)

Lista nieuporządkowana. Dodatkowe atrybuty związane z tymi pełnymi haszami. To pole może być puste.

ThreatAttribute

Atrybuty zagrożeń. Te atrybuty mogą nadawać konkretnemu zagrożeniu dodatkowe znaczenie, ale nie mają wpływu na jego typ. Na przykład atrybut może określać niższy poziom ufności, a inny atrybut – wyższy poziom ufności. 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 taką wartość, klient całkowicie zignoruje zamykający element FullHashDetail.
CANARY Wskazuje, że obiekt threatType nie powinien być używany do egzekwowania.
FRAME_ONLY Wskazuje, że threatType powinien być używany tylko do egzekwowania zasad w ramkach.