Method: hashes.search

Recherche les hachages complets correspondant aux préfixes spécifiés.

Il s'agit d'une méthode personnalisée, telle que définie dans https://google.aip.dev/136 (la méthode personnalisée fait référence à une méthode ayant un nom personnalisé dans la nomenclature générale de développement d'API de Google. Elle ne fait pas référence à l'utilisation d'une méthode HTTP personnalisée).

Requête HTTP

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

L'URL utilise la syntaxe de transcodage gRPC.

Paramètres de requête

Paramètres
hashPrefixes[]

string (bytes format)

Obligatoire. Préfixes de hachage à rechercher. Les clients NE DOIVENT PAS envoyer plus de 1 000 préfixes de hachage. Toutefois, en suivant la procédure de traitement des URL, les clients NE DEVRAIENT PAS avoir besoin d'envoyer plus de 30 préfixes de hachage.

Actuellement, chaque préfixe de hachage doit comporter exactement quatre octets. Cette règle POURRAIT être assouplie à l'avenir.

Chaîne encodée en base64.

Corps de la requête

Le corps de la requête doit être vide.

Corps de la réponse

Réponse renvoyée après la recherche de hachages de menaces.

Si aucun résultat n'est trouvé, le serveur renvoie un état OK (code d'état HTTP 200) avec le champ fullHashes vide, au lieu de renvoyer un état NOT_FOUND (code d'état HTTP 404).

Nouveautés de la version 5 : FullHash et FullHashDetail sont désormais séparés. Dans le cas où un hachage représente un site présentant plusieurs menaces (par exemple, MALWARE et SOCIAL_ENGINEERING), le hachage complet n'a pas besoin d'être envoyé deux fois comme dans la version 4. De plus, la durée du cache a été simplifiée en un seul champ cacheDuration.

Si la requête aboutit, le corps de la réponse contient des données qui ont la structure suivante :

Représentation JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Champs
fullHashes[]

object (FullHash)

Liste non triée. Liste non ordonnée des hachages complets trouvés.
cacheDuration

string (Duration format)

Durée du cache côté client. Le client DOIT ajouter cette durée à l'heure actuelle pour déterminer l'heure d'expiration. Le délai d'expiration s'applique ensuite à chaque préfixe de hachage demandé par le client dans la requête, quel que soit le nombre de hachages complets renvoyés dans la réponse. Même si le serveur ne renvoie aucun hachage complet pour un préfixe de hachage particulier, ce fait DOIT également être mis en cache par le client.

Si et seulement si le champ fullHashes est vide, le client PEUT augmenter cacheDuration pour définir une nouvelle date d'expiration ultérieure à celle spécifiée par le serveur. Dans tous les cas, la durée de mise en cache ne doit pas dépasser 24 heures.

Important : Le client NE DOIT PAS partir du principe que le serveur renverra la même durée de cache pour toutes les réponses. Le serveur PEUT choisir des durées de cache différentes pour différentes réponses en fonction de la situation.

Durée en secondes avec neuf chiffres au maximum après la virgule et se terminant par "s". Exemple : "3.5s"

FullHash

Hash complet identifié avec une ou plusieurs correspondances.

Représentation JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Champs
fullHash

string (bytes format)

Hachage complet correspondant. Il s'agit du hachage SHA256. La longueur sera exactement de 32 octets.

Chaîne encodée en base64.
fullHashDetails[]

object (FullHashDetail)

Liste non triée. Champ répété identifiant les détails pertinents pour ce hachage complet.

FullHashDetail

Informations sur un hachage complet correspondant.

Remarque importante concernant la compatibilité ascendante : le serveur peut ajouter de nouveaux types et attributs de menaces à tout moment. Ces ajouts sont considérés comme des modifications de version mineures. La règle de Google est de ne pas exposer les numéros de version mineure dans les API (consultez https://cloud.google.com/apis/design/versioning pour connaître la règle de gestion des versions). Les clients DOIVENT donc être prêts à recevoir des messages FullHashDetail contenant des valeurs d'énumération ThreatType ou des valeurs d'énumération ThreatAttribute considérées comme non valides par le client. Il incombe donc au client de vérifier la validité de toutes les valeurs d'énumération ThreatType et ThreatAttribute. Si une valeur est considérée comme non valide, le client DOIT ignorer l'intégralité du message FullHashDetail.

Représentation JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Champs
threatType

enum (ThreatType)

Type de menace. Ce champ ne sera jamais vide.
attributes[]

enum (ThreatAttribute)

Liste non triée. Attributs supplémentaires concernant ces hachages complets. Ce champ peut être vide.

ThreatAttribute

Attributs des menaces. Ces attributs peuvent donner un sens supplémentaire à une menace particulière, mais n'affectent pas le type de menace. Par exemple, un attribut peut spécifier un niveau de confiance plus faible, tandis qu'un autre peut spécifier un niveau de confiance plus élevé. D'autres attributs pourront être ajoutés à l'avenir.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Attribut inconnu. Si le serveur renvoie cette valeur, le client doit ignorer complètement le FullHashDetail qui l'entoure.
CANARY Indique que le threatType ne doit pas être utilisé pour l'application.
FRAME_ONLY Indique que le threatType ne doit être utilisé que pour l'application des règles sur les frames.