概要
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 を安全でないとみなす時間を示します(キャッシュを参照)。