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 por tipo de ameaça que indica a probabilidade de o URL ser malicioso. Essa probabilidade é calculada com base em listas de bloqueio da Navegação Segura, modelos de IA generativa, 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 à API Evaluate podem passar por processamento adicional, incluindo rastreamentos.

Antes de começar

Esse recurso está disponível em prévia particular para um conjunto limitado de clientes cujo caso de uso se alinha diretamente aos recursos dele. Entre em contato com nossa equipe de vendas para pedir uma análise do seu caso de uso pelas equipes de produto e engenharia.

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 é compatível com 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. Não é mais possível desativar essa funcionalidade na API Evaluate. Consulte as APIs Lookup e Update para 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"
    }
  ]
}