Cette page a été traduite par l'API Cloud Translation.

API Safe Browsing Lookup (v4)

Présentation

L'API Lookup permet à vos applications clientes d'envoyer des requêtes au système de navigation sécurisée pour vérifier si des URL figurent sur l'une des listes de navigation sécurisée. Si une URL est détectée sur un ou plus de 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 au threatMatches.find méthode:

La requête HTTP POST peut inclure jusqu'à 500 URL. Les URL doivent être valides (voir le document RFC 2396). mais ils n'ont pas besoin d'être canonisés ni encodés.
La réponse HTTP POST renvoie les URL correspondantes ainsi que la durée de mise en cache.

Exemple: menaceCorrespondances.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 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 pour 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 inclut les informations sur le client (ID et version) et les informations sur les menaces. (les noms des listes et les URL). Pour en savoir plus, consultez les Corps de la requête mintMatchs.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 une 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, mais nous vous suggérons de choisir un nom qui représente la véritable identité du client, tel que le nom de votre entreprise, s'affichant en un seul mot, tout en minuscules.)

Listes de navigation sécurisée

Les champs threatType, platformType et threatEntryType sont combinés pour identifier (nom) des listes de navigation sécurisée. Dans l'exemple, deux listes sont identifiées: MALWARE/WINDOWS/URL et SOCIAL_ENGINEERING/WINDOWS/URL. Avant d'envoyer une demande, assurez-vous que le type que vous spécifiez sont valides (voir la section Listes de navigation sécurisée).

URL des menaces

Dans l'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, jamais dans 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 le figure dans l'une des deux listes de navigation sécurisée spécifiées dans la demande.

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 trouvées sur ces listes, les métadonnées, le cas échéant, et les durées de mise en cache). Pour en savoir plus, consultez les Corps de la réponse (threatMatchs.find) et les explications qui suivent l'exemple de code.

Remarque:Si aucune correspondance n'est trouvée (c'est-à-dire, si aucune des URL spécifiées dans la requête se trouvent sur n'importe laquelle 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. Si il y a une correspondance. Dans l'exemple, deux URL (urltocheck1.org et urltocheck2.org) ont été trouvées sur l'un des la liste de navigation sécurisée (MALWARE/WINDOWS/URL) afin que les informations correspondantes soient renvoyées. La troisième URL (urltocheck3.org) n'a été trouvé dans aucune des deux listes. Par conséquent, aucune information n'est renvoyée pour cette URL.

Métadonnées

Le champ threatEntryMetadata est facultatif et fournit des informations supplémentaires sur la menace. Actuellement, les métadonnées sont disponibles pour la liste de navigation sécurisée LOGICIELS MALVEILLANTS/FENÊTRES/URL (voir Métadonnées).

Durées de 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).