Utiliser l'API Lookup

Présentation

L'API Lookup permet à vos applications clientes de vérifier si une URL figure sur l'une des listes Web Risk.

Vérification des URL

Pour vérifier si une URL figure sur une liste Web Risk, envoyez une requête HTTP GET à la méthode uris.search :

• L'API Lookup accepte une URL par requête. Pour vérifier plusieurs URL, vous devez envoyer une requête distincte pour chaque URL.

• Vous pouvez spécifier plusieurs types de menaces dans une seule requête en répétant le champ threatTypes. Exemple :

  &threatTypes=SOCIAL_ENGINEERING&threatTypes=MALWARE
  

• L'URL doit être valide (consulter la norme RFC 2396), mais pas canonique.

• Si vous utilisez l'API REST, vous devez encoder les paramètres GET, tels que l'URI.

• La réponse HTTP GET renvoie les types de menaces correspondants, le cas échéant, ainsi que l'expiration du cache.

Exemple : uris.search

Méthode HTTP et URL :

GET https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

exécutez la commande suivante :

curl -X GET \
    "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY"

PowerShell

exécutez la commande suivante :

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://webrisk.googleapis.com/v1/uris:search?threatTypes=MALWARE&uri=http%3A%2F%2Ftestsafebrowsing.appspot.com%2Fs%2Fmalware.html&key=API_KEY" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

{
  "threat": {
    "threatTypes": [
      "MALWARE"
    ],
    "expireTime": "2019-07-17T15:01:23.045123456Z"
  }
}

Java

import com.google.cloud.webrisk.v1.WebRiskServiceClient;
import com.google.webrisk.v1.SearchUrisRequest;
import com.google.webrisk.v1.SearchUrisResponse;
import com.google.webrisk.v1.ThreatType;
import java.io.IOException;

public class SearchUri {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // The URI to be checked for matches.
    String uri = "http://testsafebrowsing.appspot.com/s/malware.html";

    // The ThreatLists to search in. Multiple ThreatLists may be specified.
    ThreatType threatType = ThreatType.MALWARE;

    searchUri(uri, threatType);
  }

  // This method is used to check whether a URI is on a given threatList. Multiple threatLists may
  // be searched in a single query.
  // The response will list all requested threatLists the URI was found to match. If the URI is not
  // found on any of the requested ThreatList an empty response will be returned.
  public static void searchUri(String uri, ThreatType threatType) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `webRiskServiceClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (WebRiskServiceClient webRiskServiceClient = WebRiskServiceClient.create()) {

      SearchUrisRequest searchUrisRequest =
          SearchUrisRequest.newBuilder()
              .addThreatTypes(threatType)
              .setUri(uri)
              .build();

      SearchUrisResponse searchUrisResponse = webRiskServiceClient.searchUris(searchUrisRequest);

      if (!searchUrisResponse.getThreat().getThreatTypesList().isEmpty()) {
        System.out.println("The URL has the following threat: ");
        System.out.println(searchUrisResponse);
      } else {
        System.out.println("The URL is safe!");
      }
    }
  }
}

Python

from google.cloud import webrisk_v1
from google.cloud.webrisk_v1 import SearchUrisResponse

def search_uri(
    uri: str, threat_type: webrisk_v1.ThreatType.MALWARE
) -> SearchUrisResponse:
    """Checks whether a URI is on a given threatList.

    Multiple threatLists may be searched in a single query. The response will list all
    requested threatLists the URI was found to match. If the URI is not
    found on any of the requested ThreatList an empty response will be returned.

    Args:
        uri: The URI to be checked for matches
            Example: "http://testsafebrowsing.appspot.com/s/malware.html"
        threat_type: The ThreatLists to search in. Multiple ThreatLists may be specified.
            Example: threat_type = webrisk_v1.ThreatType.MALWARE

    Returns:
        SearchUrisResponse that contains a threat_type if the URI is present in the threatList.
    """
    webrisk_client = webrisk_v1.WebRiskServiceClient()

    request = webrisk_v1.SearchUrisRequest()
    request.threat_types = [threat_type]
    request.uri = uri

    response = webrisk_client.search_uris(request)
    if response.threat.threat_types:
        print(f"The URI has the following threat: {response}")
    else:
        print("The URL is safe!")
    return response

Si aucun résultat ne correspond à votre requête, vous obtiendrez une réponse JSON vide {}. Cela signifie que l'URL que vous avez fournie ne figure dans aucune liste de menaces.

Durée du cache

Le champ expireTime contient un horodatage en fonction duquel la correspondance doit être considérée comme ayant expiré. Pour en savoir plus, consultez la section Mise en cache.

Étape suivante

Découvrez comment utiliser l'API Update.