使用 Submission API

本文說明如何將疑似不安全的網址提交給安全瀏覽功能進行分析，以及如何非同步檢查這些提交內容的結果。凡是確認違反安全瀏覽政策的網址，都會加入安全瀏覽服務。

事前準備

如要取得這項功能的存取權，請聯絡銷售團隊或客戶工程師。

最佳做法

詳閱安全瀏覽政策

Web Risk Submission API 會驗證您提交的網址轉譯內容是否違反安全瀏覽政策。API 開發人員必須確保提交的網址有明確證據顯示違反這些政策。以下範例顯示違反政策的證據：

  • 模仿正當線上品牌 (品牌名稱、標誌、外觀和風格)、系統警示、使用欺騙性網址，或要求使用者輸入敏感憑證 (例如使用者名稱或密碼) 的社交工程內容。
  • 代管已知惡意軟體可執行檔的網站。

請勿提交下列類型的網址，因為這些網址不太可能加入安全瀏覽封鎖清單：

  • 假的問卷調查、購物網站或其他詐騙，但未顯示網路釣魚 (例如加密貨幣詐騙)。
  • 含有賭博、暴力或成人內容的垃圾訊息，但並非網路釣魚或惡意軟體。

改善偵測品質

建議使用 ThreatInfo 和 ThreatDiscovery 欄位，提供有關提交內容的額外資訊。這有助於提升偵測效果。詳情請參閱「使用 Submission API 的最佳做法」。

提交網址

如要提交網址，請將 HTTP POST 要求傳送至 projects.uris.submit 方法。

  • 提交 API 每個要求支援一個網址。如要檢查多個網址，請分別為每個網址提出要求。

  • 網址必須有效，但不必經過正規化。詳情請參閱 RFC 2396。

  • HTTP POST 回應會傳回 long-running operation。 如要進一步瞭解如何擷取提交結果及檢查提交狀態，請參閱「長時間執行的作業」。

範例

HTTP 方法和網址：

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

JSON 要求內文：

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/project-number/operations/operation-id",
}

查看提交狀態

使用回應中的 project-number 和 operation-id檢查提交狀態。狀態位於傳回作業的 metadata.state 欄位中。

可能的狀態包括 RUNNING、SUCCEEDED 和 CLOSED。如要進一步瞭解這些狀態，請參閱「長時間執行的作業」指南中的「瞭解作業狀態」。