API Navigazione sicura Lookup (v4)

Panoramica

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

Controllo degli URL in corso...

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

• La richiesta POST HTTP 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 e la durata della cache.

Esempio: threatMatches.find

Richiesta POST HTTP

Nell'esempio seguente, due elenchi di Navigazione sicura e tre URL vengono inviati al server a 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 tua chiave API per 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 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 del cliente

I campi clientID e clientVersion devono identificare in modo univoco un'implementazione client, non un singolo utente. (le informazioni del client vengono utilizzate per la registrazione e la contabilità lato server. Puoi scegliere un nome per l'ID client, ma ti suggeriamo di scegliere un nome che rappresenti la vera identità del cliente, ad esempio il nome dell'azienda, espresso in una sola parola e 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, vengono identificati due elenchi: MALWARE/WINDOWS/URL e SOCIAL_ENGINEERING/WINDOWS/URL. Prima di inviare una richiesta, assicurati che il tipo le combinazioni specificate siano valide (consulta l'articolo Elenchi di Navigazione sicura).

URL delle minacce

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

Nota: l'API Lookup e il metodo threatMatches devono 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 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 contenuti.

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 tali elenchi, i metadati, se disponibili, e le durate della cache). Per ulteriori dettagli, consulta Corpo della risposta athreatMatches.find e le spiegazioni che seguono l'esempio di codice.

Nota: se non viene trovata alcuna corrispondenza (ossia se nessuno degli URL specificati) presenti nella richiesta in uno degli elenchi specificati in una richiesta), la risposta POST HTTP 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, se esiste una corrispondenza. Nell'esempio, sono stati trovati due URL (urltocheck1.org e urltocheck2.org) in uno dei gli elenchi di Navigazione sicura (MALWARE/WINDOWS/URL) affinché vengano restituite le informazioni corrispondenti. Il terzo URL (urltocheck3.org) non è stato trovato in nessuno degli elenchi, quindi non viene restituita alcuna informazione per questo URL.

Metadati

Il campo threatEntryMetadata è facoltativo e fornisce informazioni aggiuntive su le minacce. Attualmente i metadati sono disponibili per l'elenco di Navigazione sicura per MALWARE/WINDOWS/URL. (vedi Metadati).

Durate della cache

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