API Navigazione sicura Lookup (v4)

Panoramica

L'API Lookup consente alle applicazioni client di inviare richieste ai server di Navigazione sicura per verificare se gli URL sono inclusi in uno qualsiasi degli elenchi di Navigazione sicura. Se viene trovato un URL in uno o più elenchi, vengono restituite le informazioni corrispondenti.

Verifica degli URL

Per verificare se un URL è presente in un elenco di Navigazione sicura, invia una richiesta HTTP POST al metodo threatMatches.find:

• La richiesta HTTP POST può includere fino a 500 URL. Gli URL devono essere validi (vedi RFC 2396), ma non è necessario che siano canonicalizzati o codificati.
• La risposta HTTP POST restituisce gli URL corrispondenti insieme alla durata della cache.

Esempio: ThreatMatches.find

Richiesta POST HTTP

Nell'esempio che segue, due elenchi di Navigazione sicura e tre URL vengono inviati al server per determinare se esiste una corrispondenza.

Intestazione della richiesta

L'intestazione della richiesta include l'URL della richiesta e il tipo di contenuti. Ricordati di sostituire la chiave API con API_KEY nell'URL.

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json
  

Corpo della richiesta

Il corpo della richiesta include le informazioni sul client (ID e versione) e le informazioni sulla minaccia (i nomi degli elenchi e gli URL). Per ulteriori dettagli, consulta il corpo della richiestathreatMatches.find e le spiegazioni che seguono l'esempio di codice.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

Dati cliente

I campi clientID e clientVersion devono identificare in modo univoco un'implementazione client, non un singolo utente. (le informazioni sul client vengono utilizzate per il logging e la contabilità lato server. Puoi scegliere qualsiasi nome per l'ID client, ma ti suggeriamo di scegliere un nome che rappresenti l'identità reale del client, ad esempio il nome dell'azienda, presentato come un'unica parola, in lettere minuscole.

Elenchi di Navigazione sicura

I campi threatType, platformType e threatEntryType vengono combinati per identificare gli elenchi di Navigazione sicura (nome). Nell'esempio sono identificati due elenchi: MALWARE/WINDOWS/URL e SOCIAL_ENGINEERING/WINDOWS/URL. Prima di inviare una richiesta, assicurati che le combinazioni di tipi specificate siano valide (consulta la sezione Elenchi di Navigazione sicura).

URL minaccia

Nell'esempio, l'array threatEntries contiene tre URL (urltocheck1.org, urltocheck2.org e urltocheck3.org) che verranno verificati rispetto ai due elenchi di Navigazione sicura.

Nota: l'API Lookup e il metodo threatMatches dovrebbero utilizzare sempre il campo URL, mai il campo hash (vedi ThreatEntry).

Risposta POST HTTP

Nell'esempio seguente, la risposta restituisce una corrispondenza; due dei tre URL specificati nella richiesta vengono trovati in uno dei due elenchi di Navigazione sicura specificati nella richiesta.

Intestazione della risposta

L'intestazione della risposta include il codice di stato HTTP e il tipo di contenuto.

HTTP/1.1 200 OK
Content-Type: application/json

Corpo della risposta

Il corpo della risposta include le informazioni sulla corrispondenza (i nomi degli elenchi e gli URL trovati in questi elenchi, i metadati, se disponibili e le durate della cache). Per ulteriori dettagli, consulta il corpo della rispostathreatMatches.find e le spiegazioni che seguono l'esempio di codice.

Nota: se non ci sono corrispondenze (ovvero, se nessuno degli URL specificati nella richiesta viene trovato in uno degli elenchi specificati in una richiesta), la risposta HTTP POST restituisce semplicemente un oggetto vuoto nel corpo della risposta.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Corrisponde a

L'oggetto matches elenca i nomi degli elenchi di Navigazione sicura e gli URL, in caso di corrispondenza. Nell'esempio, sono stati trovati due URL (urltocheck1.org e urltocheck2.org) in uno degli elenchi di Navigazione sicura (MALWARE/WINDOWS/URL), quindi vengono restituite le informazioni corrispondenti. Il terzo URL (urltocheck3.org) non è stato trovato in nessuno degli elenchi, pertanto non vengono restituite informazioni per questo URL.

Metadati

Il campo threatEntryMetadata è facoltativo e fornisce ulteriori informazioni sulla corrispondenza delle minacce. Al momento, i metadati sono disponibili per l'elenco di Navigazione sicura MALWARE/WINDOWS/URL (consulta la sezione Metadati).

Durate della cache

Il campo cacheDuration indica per quanto tempo l'URL deve essere considerato non sicuro (consulta la sezione Memorizzazione nella cache).