Method: hashes.search

Wyszukaj pełne wartości skrótu pasujące do określonych prefiksów.

Jest to metoda niestandardowa zdefiniowana w dokumentacji https://google.aip.dev/136 (metoda niestandardowa odnosi się do tej metody mającej niestandardową nazwę w ogólnej nomenklaturze Google dotyczącej tworzenia interfejsów API; nie odnosi się do korzystania z niestandardowej metody HTTP).

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Parametry zapytania

Parametry
hashPrefixes[]

string (bytes format)

Wymagane. Prefiksy haszy do wyszukania. Klienci NIE MOGĄ wysyłać więcej niż 1000 prefiksów haszowanych. Jednak zgodnie z procedurą przetwarzania adresów URL klienci NIE powinni wysyłać więcej niż 30 prefiksów haszowania.

Obecnie każdy prefiks hasha musi mieć dokładnie 4 bajty. W przyszłości możemy złagodzić te wymagania.

Ciąg znaków zakodowany w formacie Base64.

Treść żądania

Treść żądania musi być pusta.

Treść odpowiedzi

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

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

Co nowego w wersji 5: występuje rozdział między FullHash a FullHashDetail. W przypadku, gdy hasz reprezentuje witrynę z wieloma zagrożeniami (np. MALWARE i SOCIAL_ENGINEERING), nie trzeba wysyłać pełnego hasza dwukrotnie, jak w wersji 4. Ponadto czas trwania pamięci podręcznej został uproszczony i przeniesiony do pojedynczego 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 haszy.
cacheDuration

string (Duration format)

Czas trwania pamięci podręcznej po stronie klienta. Aby określić czas wygaśnięcia, klient MUSI dodać ten czas do bieżącego czasu. Czas wygaśnięcia dotyczy każdego prefiksu hasha zapytanego przez klienta w żądaniu, niezależnie od tego, ile pełnych hashy zwraca odpowiedź. Nawet jeśli serwer nie zwróci pełnych haszy dla konkretnego prefiksu hasza, klient MUSI przechowywać ten fakt w pamięci podręcznej.

Jeśli i tylko jeśli pole fullHashes jest puste, klient MOŻE zwiększyć cacheDuration, aby określić nowy czas wygaśnięcia, który jest późniejszy niż ten określony przez serwer. W każdym razie wydłużony czas przechowywania w 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. W zależności od sytuacji serwer MOŻE wybrać różne czasy przechowywania w pamięci podręcznej dla różnych odpowiedzi.

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

FullHash

Pełny skrót identyfikujący co najmniej 1 pasowanie.

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

string (bytes format)

Dopasowany pełny ciąg znaków. Jest to identyfikator SHA256. Długość będzie wynosić dokładnie 32 bajty.

Ciąg znaków zakodowany w formacie Base64.
fullHashDetails[]

object (FullHashDetail)

Lista nieuporządkowana. Powtarzające się pole z informacjami dotyczącymi tego pełnego hasha.

FullHashDetail

Szczegóły pasującego pełnego hasza.

Ważna uwaga dotycząca zgodności wstecznej: serwer może w dowolnym momencie dodać nowe typy zagrożeń i atrybuty zagrożeń. Te dodatki są uważane za drobne zmiany wersji. Zgodnie z zasadami Google nie należy ujawniać numerów wersji podrzędnych w interfejsach API (zasady dotyczące wersji znajdziesz na stronie https://cloud.google.com/apis/design/versioning), więc klienci MUSZĄ być gotowi do odbierania wiadomości FullHashDetail zawierających wartości wyliczenia ThreatType lub ThreatAttribute, które są uważane za nieprawidłowe przez klienta. Dlatego klient musi sprawdzić poprawność wszystkich wartości wyliczenia 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)

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

enum (ThreatAttribute)

Lista nieuporządkowana. dodatkowe atrybuty dotyczące pełnych haszy; To pole może być puste.

ThreatAttribute

Atrybuty zagrożeń. Te atrybuty mogą nadawać dodatkowe znaczenie określonym zagrożeniom, ale nie mają wpływu na ich typ. Na przykład atrybut może określać mniejsze prawdopodobieństwo, a inny – większe. 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 powinien całkowicie zignorować otoczkę FullHashDetail.
CANARY Wskazuje, że typu threatType nie należy używać do egzekwowania zasad.
FRAME_ONLY Oznacza, że typ zagrożenia powinien być używany tylko do egzekwowania zasad w ramkach.