Como usar a API Evaluate

Nesta página, explicamos como usar a API Evaluate para permitir que os aplicativos cliente avaliem a maliciosidade de um URL. Essa API retorna uma pontuação de confiança que indica a maliciosidade de um URL com base em listas de bloqueio, modelos de machine learning e regras heurísticas. Se você quiser um resultado binário em vez de uma pontuação de confiança, use a API Lookup.

Observação:todos os URLs enviados para a API Evaluate podem passar por processamento adicional, incluindo rastreamentos.

Antes de começar

Entre em contato com nossa equipe de vendas ou com o engenheiro de clientes para ter acesso a esse recurso.

Como avaliar URLs

Para avaliar um URL, envie uma solicitação HTTP POST para o método evaluateUri: Entenda as considerações a seguir ao avaliar URLs:

  • A API Evaluate é compatível com um URL por solicitação. Se quiser verificar vários URLs, envie uma solicitação separada para cada um.
  • O URL precisa ser válido e não precisa ser canonizado. Para saber, consulte a RFC 46485 (em inglês).
  • A API Evaluate oferece suporte a três threatTypes: SOCIAL_ENGINEERING, MALWARE e UNWANTED_SOFTWARE.
  • Obsoleto. O campo allow_scan foi usado para determinar se a Web Risk pode verificar o URL fornecido. Essa funcionalidade não pode mais ser desativada na API Evaluate. Consulte as APIs Lookup e Update para conferir opções sem rastreamento.
  • A resposta HTTP POST retorna uma pontuação de confiança para o threatType especificado. A pontuação de confiança representa o nível de confiança que indica o risco ao URL especificado.

Solicitação da API

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

URL: um URL que precisa ser avaliado.

Método HTTP e URL:

POST https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY

Corpo JSON da solicitação:

{
  "uri": "URL",
  "threatTypes": ["SOCIAL_ENGINEERING", "MALWARE", "UNWANTED_SOFTWARE"]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1eap1:evaluateUri?key=API_KEY" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "scores": [
    {
      "threatType": "MALWARE",
      "confidenceLevel": "EXTREMELY_HIGH"
    },
    {
      "threatType": "SOCIAL_ENGINEERING",
      "confidenceLevel": "SAFE"
    },
    {
      "threatType": "UNWANTED_SOFTWARE",
      "confidenceLevel": "SAFE"
    }
  ]
}