Update API の使用
概要
Update API を使用すると、クライアントアプリケーションで、Web Risk リストのハッシュバージョンをダウンロードして、ローカルデータベースまたはメモリ内データベースに保存できます。その後、URL をローカルで確認できます。ローカル データベースで一致が見つかった場合、クライアントは Web Risk サーバーにリクエストを送信して、その URL が Web Risk リストに含まれているかどうかを確認します。
ローカル データベースの更新
最新の状態を維持するため、クライアントはローカル データベースの Web Risk リストを定期的に更新する必要があります。帯域幅を節約するために、クライアントは未加工の URL ではなく URL のハッシュ プレフィックスをダウンロードします。たとえば、Web Risk に「www.badurl.com/」が含まれている場合、クライアントは URL そのものではなく、その URL の SHA256 ハッシュ プレフィックスをダウンロードします。ほとんどの場合、ハッシュ プレフィックスの長さは 4 バイトです。つまり、1 つのリストエントリをダウンロードするための平均帯域幅コストは圧縮前の 4 バイトです。
ローカル データベース内のWeb Risk リストを更新するには、HTTP GET
リクエストを threatLists.computeDiff
メソッドに送信します。
- HTTP
GET
リクエストには、メモリと帯域幅の制限を考慮して、更新されるリストの名前とクライアントの制約が含まれます。 - HTTP
GET
レスポンスは、完全な更新または部分的な更新を返します。 レスポンスは、次のコンピューティング差分演算を計算するまでの推奨待ち時間も返します。
例: threatLists.computeDiff
HTTP GET リクエスト
次の例では、MALware Web Risk リストの差分がリクエストされます。詳細については、threatLists.computeDiff
クエリ パラメータとコード例に続く説明をご覧ください。
HTTP メソッドと URL:
GET https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
次のコマンドを実行します。
curl -X GET \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY"
PowerShell
次のコマンドを実行します。
$headers = @{ }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z", "responseType": "RESET", "additions": { "rawHashes": [ { "prefixSize": 4, "rawHashes": "AArQMQAMoUgAPn8lAE..." } ] }, "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL", "checksum": { "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI=" } }
Java
Python
Web Risk リスト
threatType
フィールドは、Web Risk リストを識別します。この例では、MALware Web Risk リストの差分がリクエストされます。
バージョン トークン
versionToken
フィールドには、Web Risk リストの現在のクライアントの状態が保持されます。バージョン トークンは、TheatLists.computeDiff レスポンスの newVersionToken
フィールドで返されます。最初の更新では、versionToken
フィールドは空のままにします。
サイズ制限
maxDiffEntries
フィールドは、クライアントが管理できる更新の合計数を指定します(この例では 2,048)。maxDatabaseEntries
フィールドは、ローカルデータベースが管理できるエントリの合計数を指定します(この例では 4,096)。クライアントは、メモリと帯域幅の制限を保護し、リストの増加を防ぐために、サイズの制約を設定する必要があります。詳しくは、更新の制約をご覧ください。
サポートされている圧縮
supportedCompressions
フィールドには、クライアントでサポートされる圧縮タイプが一覧表示されます。この例のクライアントでは、未加工の非圧縮データのみがサポートされています。ただし、Web Risk では、他の圧縮タイプもサポートされています。詳細については、圧縮をご覧ください。
HTTP GET レスポンス
この例では、レスポンスはリクエストされた圧縮タイプを使用してWeb Risk リストの部分更新を返します。
レスポンスの本文
レスポンスの本文には、差分情報(レスポンスタイプ、ローカルデータベースに適用される追加と削除、新しいバージョン トークン、チェックサム)が含まれます。
この例では、推奨される次の差分時間もレスポンスに含まれています。詳細については、threatLists.computeDiff
レスポンスの本文とコード例に続く説明をご覧ください。
{ "responseType" : "DIFF", "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z", "additions": { "compressionType": "RAW", "rawHashes": [{ "prefixSize": 4, "rawHashes": "rnGLoQ==" }] }, "removals": { "rawIndices": { "indices": [0, 2, 4] } }, "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" }, "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z" }
データベースの差分
responseType
フィールドは、部分的(DIFF
)または完全な更新(RESET
)を示します。この例では、部分差分が返されるため、レスポンスには追加と削除の両方が含まれます複数の追加が返される可能性がありますが、削除は 1 つだけです。詳細については、データベースの差分をご覧ください。
新しいバージョン トークン
newVersionToken
フィールドには、新しく更新されたWeb Risk リストの新しいバージョン トークンが格納されます。クライアントは、後続の更新リクエスト(threatLists.computeDiff
リクエストの versionToken
フィールド)のために新しいクライアント状態を保存する必要があります。
チェックサム
チェックサムを使用すると、クライアントはローカル データベースが破損していないことを確認できます。チェックサムが一致しない場合、クライアントはデータベースを消去し、空の versionToken
フィールドを使用して更新を再発行する必要があります。ただし、この場合でも、クライアントは更新の間隔に従う必要があります。詳細については、リクエスト頻度をご覧ください。
推奨される次の差分
recommendedNextDiff
フィールドは、クライアントが別の更新リクエストを送信するまで待機する時点までのタイムスタンプを示します。推奨される待ち時間は、レスポンスに含まれる場合もあれば、含まれない場合もあります。詳細については、リクエスト頻度をご覧ください。
URL の確認
URL が Web Risk リストに含まれているかどうかを確認するには、クライアントはまず URL のハッシュとハッシュ プレフィックスを計算する必要があります。詳細については、URL とハッシュ化をご覧ください。次に、クライアントはローカル データベースにクエリを行い、一致するものがあるかどうかを判断します。ハッシュ プレフィックスがローカル データベースに存在しない場合、URL は安全と見なされます(つまり、Web Risk リストにはありません)。
ハッシュプレフィックスがローカルデータベースに存在する場合(ハッシュプレフィックスの競合)、クライアントは検証のためにハッシュプレフィックスを Web Risk サーバーに送信する必要があります。サーバーは、指定されたハッシュ プレフィックスを含むすべてのフルレングスの SHA 256 ハッシュを返します。これらのフルレングスのハッシュのいずれかが、問題の URL のフルレングスのハッシュと一致する場合、その URL は安全でないとみなされます。問題の URL のフルレングスのハッシュと一致するフルレングスのハッシュがない場合、その URL は安全と見なされます。
Google は、調査している URL をまったく認識しません。Google は URL のハッシュ プレフィックスを認識しますが、ハッシュ プレフィックスは実際の URL に関する情報を提供しません。
URL が Web Risk リストに含まれているかどうかを確認するには、HTTP GET
リクエストを hashes.search
メソッドに送信します。
- HTTP
GET
リクエストには、確認する URL のハッシュ プレフィックスが含まれます。 - HTTP
GET
レスポンスは、一致するフルレングスのハッシュをポジティブとネガティブの有効期限とともに返します。
例: hashes.search
HTTP GET リクエスト
次の例では、比較と確認のために 2 つの Web Risk リストの名前とハッシュ プレフィックスが送信されます。詳細については、hashes.search
クエリ パラメータとコード例に続く説明をご覧ください。
curl \ -H "Content-Type: application/json" \ "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"
Java
Python
Web Risk リスト
threatTypes
フィールドは、Web Risk リストを示します。この例では、MALWARE
と SOCIAL_ENGINEERING
の 2 つのリストが識別されます。
脅威のハッシュ プレフィックス
hashPrefix
フィールドには、確認する URL のハッシュ プレフィックスが含まれます。このフィールドには、ローカル データベースに存在する正確なハッシュ プレフィックスを含める必要があります。たとえば、ローカル ハッシュ プレフィックスが 4 バイトの場合、hashPrefix
フィールドは 4 バイトにする必要があります。ローカル ハッシュ プレフィックスが 7 バイトに延長されている場合、hashPrefix
フィールドは 7 バイトにする必要があります。
HTTP GET レスポンス
次の例では、レスポンスは一致した Web Risk リストを含む一致する脅威と有効期限を返します。
レスポンスの本文
レスポンスの本文には、一致情報(リスト名、フルレングスのハッシュ、キャッシュ期間)が含まれます。詳細については、hashes.search
レスポンスの本文とコード例に続く説明をご覧ください。
{ "threats": [{ "threatTypes": ["MALWARE"], "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, }], "negativeExpireTime": "2019-07-17T15:01:23.045123456Z" }
一致する
threats
フィールドには、ハッシュ プレフィックスに一致するフルレングスのハッシュが返されます。これらのハッシュに対応する URL は安全でないとみなされます。ハッシュ プレフィックスに一致するものが見つからない場合は、何も返されません。そのハッシュ プレフィックスに対応する URL は安全と見なされます。
有効期限
expireTime
フィールドと negativeExpireTime
フィールドは、ハッシュが安全でないか安全かを判断する必要があるタイミングをそれぞれ示します。詳しくは、キャッシュ保存をご覧ください。