このページは Cloud Translation API によって翻訳されました。

Safe Browsing Lookup API（v4）

概要

Lookup API を使用すると、クライアントアプリケーションからセーフブラウジングサーバーにリクエストを送信して、セーフブラウジングリストに URL が含まれているかどうかを確認できます。1 つ以上のリストで URL が見つかった場合は、一致する情報が返されます。

URL の確認

URL がセーフブラウジングリストに含まれているかどうかを確認するには、HTTP POST リクエストを threatMatches.find メソッドに送信します。

HTTP POST リクエストには、最大 500 個の URL を含めることができます。有効な URL（RFC 2396 を参照）である必要がありますが、正規化やエンコードを行う必要はありません。
HTTP POST レスポンスでは、一致する URL とキャッシュ期間が返されます。

例: ThreatMatches.find

HTTP POST リクエスト

次の例では、2 つのセーフブラウジングリストと 3 つの URL がサーバーに送信され、一致するものがあるかどうかが確認されています。

リクエストヘッダー

リクエストヘッダーには、リクエスト URL とコンテンツタイプが含まれます。URL の API_KEY は、実際の API キーで置き換えてください。

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

リクエスト本文

リクエストの本文には、クライアント情報（ID とバージョン）と脅威情報（リスト名と URL）が含まれます。詳細については、threatMatches.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 の 2 つのリストが識別されます。リクエストを送信する前に、指定したタイプの組み合わせが有効であることを確認してください（セーフブラウジングリストをご覧ください）。

脅威の URL

この例では、threatEntries 配列に 3 つの URL（urltocheck1.org、urltocheck2.org、urltocheck3.org）が含まれ、2 つのセーフブラウジングリストと照合されます。

注: Lookup API と threatMatches メソッドでは、hash フィールドではなく、常に URL フィールドを使用する必要があります（ThreatEntry を参照）。

HTTP POST レスポンス

次の例では、レスポンスで一致が返されます。リクエストで指定された 3 つの URL のうち 2 つが、リクエストで指定された 2 つのセーフブラウジングリストのいずれかに含まれています。

レスポンスヘッダー

レスポンスヘッダーには、HTTP ステータスコードとコンテンツタイプが含まれます。

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

レスポンスの本文

レスポンスの本文には一致情報（リスト名とリストで見つかった URL、メタデータ（利用可能な場合）、キャッシュ期間）が含まれます。詳細については、threatMatches.find レスポンスの本文と、サンプルコードに続く説明をご覧ください。

注: 一致するものがない場合（つまり、リクエストで指定された URL がリクエストで指定されたリストのどれにも一致しない場合）は、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 オブジェクトは、セーフブラウジングリストの名前と URL（存在する場合）のリストを示します。この例では、セーフブラウジングリスト（MALWARE/WINDOWS/URL）の 1 つで 2 つの URL（urltocheck1.org と urltocheck2.org）が見つかったため、一致する情報が返されます。3 番目の URL（urltocheck3.org）はどちらのリストでも見つからなかったため、この URL の情報は返されません。

メタデータ

threatEntryMetadata フィールドはオプションで、脅威一致に関する追加情報を提供します。現在、メタデータは MALWARE、WINDOWS、URL のセーフブラウジングリストで使用できます（メタデータを参照）。

キャッシュ期間

cacheDuration フィールドは、URL を安全でないとみなす時間を示します（キャッシュを参照）。