Présentation
L'API Lookup permet à vos applications clientes d'envoyer des requêtes aux serveurs de navigation sécurisée pour vérifier si les URL figurent sur l'une des listes de navigation sécurisée. Si une URL figure sur une ou plusieurs listes, les informations correspondantes sont renvoyées.
Vérification des URL
Pour vérifier si une URL figure sur une liste de navigation sécurisée, envoyez une requête HTTP POST à la méthode threatMatches.find:
- La requête HTTP
POSTpeut inclure jusqu'à 500 URL. Celles-ci doivent être valides (voir la section RFC 2396), mais elles n'ont pas besoin d'être canoniques ni encodées. - La réponse HTTP
POSTrenvoie les URL correspondantes, ainsi que la durée du cache.
Exemple: ThreatMatchs.find
Requête HTTP POST
Dans l'exemple suivant, deux listes de navigation sécurisée et trois URL sont envoyées au serveur pour déterminer s'il existe une correspondance.
En-tête de requête
L'en-tête de requête inclut l'URL de la requête et le type de contenu. N'oubliez pas de remplacer votre clé API par API_KEY dans l'URL.
POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Corps de la requête
Le corps de la requête comprend les informations sur le client (ID et version) et les informations sur la menace (les noms des listes et les URL). Pour en savoir plus, consultez le corps de la requête ThratMatchs.find et les explications qui suivent l'exemple de code.
{
"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/"}
]
}
}
Informations sur le client
Les champs clientID et clientVersion doivent identifier de manière unique une implémentation client, et non un utilisateur individuel. (Les informations client sont utilisées pour la journalisation et la traçabilité côté serveur. Vous pouvez choisir n'importe quel nom pour l'ID client. Toutefois, nous vous recommandons de choisir un nom qui représente la véritable identité du client, tel que le nom de votre entreprise, présenté comme un seul mot, tout en minuscules.)
Listes de navigation sécurisée
Les champs threatType, platformType et threatEntryType sont combinés pour identifier les listes de navigation sécurisée (nom). Dans l'exemple, deux listes sont identifiées : MALWARE/WINDOWS/URL et SOCIAL_ENGINEERING/WINDOWS/URL. Avant d'envoyer une requête, assurez-vous que les combinaisons de types que vous spécifiez sont valides (consultez la section Listes de navigation sécurisée).
URL des menaces
Dans cet exemple, le tableau threatEntries contient trois URL (urltocheck1.org, urltocheck2.org et urltocheck3.org) qui seront comparées aux deux listes de navigation sécurisée.
Remarque:L'API Lookup et la méthode threatMatches doivent toujours utiliser le champ URL, et non le champ hash (voir ThreatEntry).
Réponse HTTP POST
Dans l'exemple suivant, la réponse renvoie une correspondance. Deux des trois URL spécifiées dans la requête figurent sur l'une des deux listes de navigation sécurisée spécifiées dans la requête.
En-tête de réponse
L'en-tête de réponse inclut le code d'état HTTP et le type de contenu.
HTTP/1.1 200 OK Content-Type: application/json
Corps de la réponse
Le corps de la réponse inclut les informations de correspondance (noms des listes et URL figurant sur ces listes, métadonnées, le cas échéant, et durées de mise en cache). Pour en savoir plus, consultez le corps de la réponse ThreatMatchs.find et les explications qui suivent l'exemple de code.
Remarque:En l'absence de correspondance (c'est-à-dire, si aucune des URL spécifiées dans la requête ne se trouve sur l'une des listes spécifiées dans une requête), la réponse HTTP POST renvoie simplement un objet vide dans le corps de la réponse.
{
"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"
}]
}
Correspond à
L'objet matches répertorie les noms des listes de navigation sécurisée et les URL, le cas échéant. Dans l'exemple, deux URL (urltocheck1.org et urltocheck2.org) ont été trouvées sur l'une des listes de navigation sécurisée (MALWARE/WINDOWS/URL). Les informations correspondantes sont donc renvoyées. La troisième URL (urltocheck3.org) n'a été trouvée dans aucune des deux listes. Aucune information n'est donc renvoyée pour cette URL.
Métadonnées
Le champ threatEntryMetadata est facultatif et fournit des informations supplémentaires sur la mise en correspondance des menaces. Les métadonnées sont actuellement disponibles pour la liste de navigation sécurisée MALWARE/WINDOWS/URL (voir Métadonnées).
Durées du cache
Le champ cacheDuration indique la durée pendant laquelle l'URL doit être considérée comme non sécurisée (voir Mise en cache).