Usar a API Lookup

Vista geral

A API Lookup permite que as suas aplicações cliente verifiquem se um URL está incluído em alguma das listas de risco na Web.

A verificar os URLs

Para verificar se um URL está numa lista do Web Risk, envie um pedido HTTP GET para o método uris.search:

• A API Lookup suporta um URL por pedido. Para verificar vários URLs, tem de enviar uma solicitação separada para cada URL.

• Pode especificar vários tipos de ameaças num único pedido repetindo o campo threatTypes. Por exemplo:

  &threatTypes=SOCIAL_ENGINEERING&threatTypes=MALWARE
  

• O URL tem de ser válido (consulte o RFC 2396), mas não tem de ser canonizado.

• Se usar a API REST, tem de codificar os parâmetros GET, como o URI.

• A resposta HTTP GET devolve os tipos de ameaças correspondentes, se existirem, juntamente com a expiração da cache.

Exemplo: uris.search

Método HTTP e URL:

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

Para enviar o seu pedido, escolha uma destas opções:

curl

Execute o seguinte comando:

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

Execute o seguinte comando:

$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

Deve receber uma resposta JSON semelhante à seguinte:

{
  "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

Se não existirem resultados correspondentes ao seu pedido, recebe uma resposta JSON vazia de {}. Isto significa que o URL que indicou não está em nenhuma lista de ameaças.

Durações da cache

O campo expireTime indica a data/hora em que a correspondência deve ser considerada expirada. Para obter detalhes, consulte a secção Colocação em cache.

O que se segue?

Saiba mais sobre a utilização da API Update.