Method: hashes.search

Cerca gli hash completi corrispondenti ai prefissi specificati.

Si tratta di un metodo personalizzato come definito da https://google.aip.dev/136 (il metodo personalizzato si riferisce a questo metodo che ha un nome personalizzato all'interno della nomenclatura generale di sviluppo dell'API di Google; non si riferisce all'utilizzo di un metodo HTTP personalizzato).

Richiesta HTTP

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

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri di query

Parametri
hashPrefixes[]

string (bytes format)

Obbligatorio. I prefissi degli hash da cercare. I client NON DEVONO inviare più di 1000 prefissi hash. Tuttavia, seguendo la procedura di elaborazione dell'URL, i client NON DOVREBBERO dover inviare più di 30 prefissi hash.

Attualmente è necessario che ogni prefisso di hash abbia una lunghezza di esattamente 4 byte. Questa limitazione POTREBBE essere allentata in futuro.

Una stringa con codifica Base64.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

La risposta restituita dopo la ricerca degli hash delle minacce.

Se non viene trovato nulla, il server restituirà uno stato OK (codice di stato HTTP 200) con il campo fullHashes vuoto, anziché uno stato NOT_FOUND (codice di stato HTTP 404).

Novità della versione 5: è presente una separazione tra FullHash e FullHashDetail. Se un hash rappresenta un sito con più minacce (ad es. sia MALWARE che SOCIAL_ENGINEERING), non è necessario inviare l'hash completo due volte come nella versione 4. Inoltre, la durata della cache è stata semplificata in un unico campo cacheDuration.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Campi
fullHashes[]

object (FullHash)

Elenco non ordinato. L'elenco non ordinato degli hash completi trovati.
cacheDuration

string (Duration format)

La durata della cache lato client. Il client DEVE aggiungere questa durata all'ora corrente per determinare l'ora di scadenza. La data e l'ora di scadenza si applicano a ogni prefisso di hash interrogato dal client nella richiesta, indipendentemente dal numero di hash completi restituiti nella risposta. Anche se il server non restituisce hash completi per un determinato prefisso di hash, questo fatto DEVE essere memorizzato nella cache anche dal client.

Se e solo se il campo fullHashes è vuoto, il client PUÒ aumentare il valore cacheDuration per determinare una nuova scadenza successiva a quella specificata dal server. In ogni caso, la durata della cache aumentata non deve superare le 24 ore.

Importante: il client NON DEVE presumere che il server restituirà la stessa durata della cache per tutte le risposte. Il server PUÒ scegliere durate della cache diverse per risposte diverse a seconda della situazione.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

FullHash

L'hash completo identificato con una o più corrispondenze.

Rappresentazione JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Campi
fullHash

string (bytes format)

L'hash completo corrispondente. Si tratta dell'hash SHA256. La lunghezza sarà esattamente di 32 byte.

Una stringa con codifica Base64.
fullHashDetails[]

object (FullHashDetail)

Elenco non ordinato. Un campo ripetuto che identifica i dettagli pertinenti a questo hash completo.

FullHashDetail

Dettagli su un hash completo corrispondente.

Una nota importante sulla compatibilità futura: il server può aggiungere nuovi tipi di minacce e attributi delle minacce in qualsiasi momento; queste aggiunte sono considerate modifiche minori alla versione. È norma di Google non esporre i numeri delle versioni secondarie nelle API (consulta https://cloud.google.com/apis/design/versioning per le norme relative al controllo delle versioni), pertanto i client DEVONO essere preparati a ricevere messaggi FullHashDetail contenenti valori enumerati ThreatType o ThreatAttribute considerati non validi dal client. Pertanto, è responsabilità del cliente verificare la validità di tutti i valori enumerati ThreatType e ThreatAttribute. Se un valore è considerato non valido, il cliente DEVE ignorare l'intero messaggio FullHashDetail.

Rappresentazione JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Campi
threatType

enum (ThreatType)

Il tipo di minaccia. Questo campo non sarà mai vuoto.
attributes[]

enum (ThreatAttribute)

Elenco non ordinato. Attributi aggiuntivi relativi a questi hash completi. Questo campo può essere vuoto.

ThreatAttribute

Attributi delle minacce. Questi attributi possono conferire un significato aggiuntivo a una determinata minaccia, ma non influiscono sul tipo di minaccia. Ad esempio, un attributo può specificare una confidenza inferiore, mentre un altro attributo può specificare una confidenza superiore. In futuro è possibile che vengano aggiunti altri attributi.

Enum
THREAT_ATTRIBUTE_UNSPECIFIED Attributo sconosciuto. Se viene restituito dal server, il client deve ignorare del tutto il FullHashDetail che lo racchiude.
CANARY Indica che threatType non deve essere utilizzato per l'applicazione.
FRAME_ONLY Indica che threatType deve essere utilizzato solo per l'applicazione delle norme nei frame.