本頁面由 Cloud Translation API 翻譯而成。

Safe Browsing Lookup API (第 4 版)

總覽

Lookup API 可讓用戶端應用程式傳送要求給安全瀏覽伺服器，檢查網址是否列於任何安全瀏覽清單中。如果在一或多份清單上找到網址，就會傳回相符的資訊。

檢查網址

如要檢查網址是否列在安全瀏覽清單上，請將 HTTP POST 要求傳送至 threatMatches.find 方法：

HTTP POST 要求最多可以包含 500 個網址。網址必須是有效網址 (請參閱 RFC 2396)，但不需要經過標準化或編碼。
HTTP POST 回應會傳回相符的網址以及快取持續時間。

範例： ThreatMatch.find

HTTP POST 要求

在以下範例中，系統會傳送兩份安全瀏覽清單和三個網址傳送至伺服器，以判斷相符項目。

要求標頭

要求標頭包含要求網址和內容類型。請記得將網址中的 API_KEY 替換成您的 API 金鑰。

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json

要求主體

要求主體包含用戶端資訊 (ID 和版本) 和威脅資訊 (清單名稱和網址)。詳情請參閱 threatMatch.find 要求主體和程式碼範例遵循的說明。

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

客戶資訊

clientID 和 clientVersion 欄位應用於識別用戶端實作，而非個別使用者。(用戶端資訊會用於伺服器端記錄和會計作業。您可以為用戶端 ID 選擇任何名稱，但我們建議您選擇能代表客戶真實身分的名稱，例如您的公司名稱，以全大寫的字母顯示，且只用一個字。)

安全瀏覽清單

系統會將 threatType、platformType 和 threatEntryType 欄位合併，以識別 (名稱) 安全瀏覽清單。此範例有兩個清單：MALWARE/WINDOWS/URL 和 SOCIAL_ENGINEERING/WINDOWS/URL。傳送要求之前，請先確認您指定的類型組合有效 (請參閱安全瀏覽清單)。

威脅網址

在這個範例中，threatEntries 陣列包含三個網址 (urltocheck1.org、urltocheck2.org 和 urltocheck3.org)，系統會將這兩個網址用於檢查兩份安全瀏覽清單。

注意：Lookup API 和 threatMatches 方法應一律使用 URL 欄位，切勿使用 hash 欄位 (請參閱 ThreatEntry)。

HTTP POST 回應

在以下範例中，回應傳回比對結果；要求中指定的三個「安全瀏覽」清單列有其中兩個網址。

回應標頭

回應標頭包含 HTTP 狀態碼和內容類型。

HTTP/1.1 200 OK
Content-Type: application/json

回應主體

回應主體包含比對資訊，包括清單名稱和這些清單中找到的網址、中繼資料 (如有)，以及快取持續時間。詳情請參閱 threatmatch.find 回應主體和程式碼範例下方的說明。

注意：如果沒有相符結果 (也就是如果在要求中指定的「任何」清單中找到要求中指定的網址「沒有任何」)，HTTP POST 回應只會傳回回應主體中的空白物件。

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

相符

matches 物件會列出安全瀏覽清單的名稱和網址 (如果相符)。在範例中，系統在其中一個安全瀏覽清單 (MALWARE/WINDOWS/URL) 發現兩個網址 (urltocheck1.org 和 urltocheck2.org)，因此會傳回相符的資訊。系統在任一清單中找不到第三個網址 (urltocheck3.org)，因此不會傳回這個網址的資訊。

Metadata

threatEntryMetadata 為選填欄位，可提供威脅比對的額外資訊。目前，MALWARE/WINDOWS/網址安全瀏覽清單可以使用中繼資料 (請參閱中繼資料)。

快取持續時間

cacheDuration 欄位表示將網址視為不安全的時間 (請參閱快取)。