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

Safe Browsing Update API（v4）

概要

Update API を使用すると、クライアントアプリケーションでセーフブラウジングリストのハッシュバージョンをダウンロードして、ローカルデータベースに保存できます。URL をローカルでチェックできるようになります。ローカルデータベースで一致するものが見つかった場合のみ、クライアントはセーフブラウジングサーバーにリクエストを送信して、URL がセーフブラウジングリストに含まれているかどうかを確認する必要があります。

Update API を使用する前に、ローカルデータベースを設定する必要があります。セーフブラウジングでは、すぐに使用できる Go パッケージが提供されます。詳細については、ローカルデータベースの「データベース設定」セクションをご覧ください。

ローカルデータベースの更新

最新の状態を維持するために、クライアントはローカルデータベース内のセーフブラウジングリストを定期的に更新する必要があります。帯域幅を節約するために、クライアントは元の URL ではなく URL のハッシュプレフィックスをダウンロードします。たとえば、「www.badurl.com/」がセーフブラウジングリストにある場合、クライアントは URL 自体ではなく、その URL の SHA256 ハッシュプレフィックスをダウンロードします。ほとんどの場合、ハッシュプレフィックスの長さは 4 バイトです。つまり、1 つのリストエントリをダウンロードする場合の平均帯域幅コストは、圧縮前の 4 バイトです。

ローカルデータベースのセーフブラウジングリストを更新するには、HTTP POST リクエストを threatListUpdates.fetch メソッドに送信します。

HTTP POST リクエストには、更新するリストの名前と、メモリと帯域幅の制限を考慮したさまざまなクライアント制約が含まれます。
HTTP POST レスポンスは、完全な更新または部分的な更新のいずれかを返します。レスポンスは最小待機時間を返す場合もあります。

例: ThreatListUpdates.fetch

HTTP POST リクエスト

次の例では、1 つのセーフブラウジングリストの更新をリクエストしています。

リクエストヘッダー

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

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

リクエスト本文

リクエストの本文には、クライアント情報（ID とバージョン）と更新情報（リスト名、リストの状態、クライアントの制約）が含まれます。詳細については、threatListUpdates.fetch リクエストの本文と、サンプルコードに続く説明をご覧ください。

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

クライアント情報

clientID フィールドと clientVersion フィールドは、個々のユーザーではなく、クライアント実装を一意に識別する必要があります。（クライアント情報はサーバーサイドのロギングで使用されます。クライアント ID には任意の名前を選択できますが、会社名など、クライアントの身元を表す名前をすべて小文字で指定することをおすすめします）。

セーフブラウジングリスト

threatType、platformType、threatEntryType のフィールドを組み合わせて、セーフブラウジングリストを識別（名前を付ける）ことができます。この例では、MALWARE/WINDOWS/URL のリストが 1 つ識別されます。リクエストを送信する前に、指定したタイプの組み合わせが有効であることを確認してください（セーフブラウジングリストをご覧ください）。

クライアントの状態

state フィールドには、セーフブラウジングリストの現在のクライアントの状態が格納されます。（クライアントの状態は、threatListUpdates.fetch レスポンスの newClientState フィールドに返されます）。最初の更新では、state フィールドは空のままにします。

サイズ制限

maxUpdateEntries フィールドには、クライアントが管理できる更新の合計数（この例では 2, 048）を指定します。maxDatabaseEntries フィールドには、ローカルデータベースで管理できるエントリの合計数（例: 4, 096）を指定します。クライアントは、メモリと帯域幅の制限を保護し、リストの増加を防ぐために、サイズの制約を設定する必要があります。詳細については、制約の更新をご覧ください。

サポートされている圧縮

supportedCompressions フィールドには、クライアントがサポートする圧縮タイプが一覧表示されます。この例では、クライアントは未加工の非圧縮データのみをサポートしています。ただし、セーフブラウジングでは、追加の圧縮形式がサポートされています（圧縮をご覧ください）。

HTTP POST レスポンス

この例では、リクエストされた圧縮タイプを使用して、セーフブラウジングリストの部分更新が返されます。

レスポンスヘッダー

レスポンスヘッダーには、HTTP ステータスコードとコンテンツタイプが含まれます。HTTP/200 以外のステータスコードを受信するクライアントは、バックオフモードにする必要があります（リクエストの頻度を参照）。

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

レスポンスの本文

レスポンスの本文には、更新情報（リスト名、レスポンスタイプ、ローカルデータベースに適用される追加と削除、新しいクライアントの状態、チェックサム）が含まれます。この例では、レスポンスに最小待機時間も含まれています。詳細については、threatListUpdates.fetch レスポンスの本文と、サンプルコードに続く説明をご覧ください。

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

データベースの更新

responseType フィールドは、部分的な更新または完全な更新を示します。この例では部分的な更新が返されるため、レスポンスには追加と削除の両方が含まれます。追加セットが複数あっても構いませんが、削除セットは 1 つだけです（データベースの更新をご覧ください）。

新しいクライアントの状態

newClientState フィールドには、新しく更新されたセーフブラウジングリストに対応する新しいクライアントの状態が格納されます。クライアントは、後続の更新リクエストのために新しいクライアントの状態を保存する必要があります（threatListUpdates.fetch リクエストの state フィールド、または fullHashes.find リクエストの clientStates フィールド）。

チェックサム

このチェックサムにより、クライアントはローカルデータベースに破損が発生していないことを確認できます。チェックサムが一致しない場合、クライアントはデータベースをクリアし、空の state フィールドで更新を再発行する必要があります。ただし、このような場合でも、クライアントは更新の時間間隔に従う必要があります（リクエストの頻度をご覧ください）。

最小待機時間

minimumWaitDuration フィールドは、クライアントが別の更新リクエストを送信するまでに 593.44 秒（9.89 分）待機する必要があることを示します。レスポンスに待機時間が含まれる場合と含まれない場合があります（リクエストの頻度をご覧ください）。

URL の確認

URL がセーフブラウジングリストに登録されているかどうかを確認するには、まず URL のハッシュとハッシュプレフィックスを計算する必要があります（URL とハッシュ化をご覧ください）。クライアントはローカルデータベースにクエリを実行して、一致するものがあるかどうか判断します。ハッシュプレフィックスがローカルデータベースに存在しない場合、その URL は安全とみなされます（セーフブラウジングリストには表示されません）。

ハッシュプレフィックスがローカルデータベースに存在する（ハッシュプレフィックスの競合）場合、クライアントは確認のためにハッシュプレフィックスをセーフブラウジングサーバーに送信する必要があります。サーバーは、指定されたハッシュプレフィックスを含むすべての完全長の SHA 256 ハッシュを返します。このフルレングスハッシュのいずれかが、該当する URL のフルレングスハッシュと一致する場合、その URL は安全でないと見なされます。フルレングスのハッシュが当該 URL のフルレングスのハッシュと一致しない場合、その URL は安全であるとみなされます。

Google は、調査している URL をまったく認識しません。Google は URL のハッシュプレフィックスを学習しますが、ハッシュプレフィックスから実際の URL に関する情報を入手することはできません。

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

HTTP POST リクエストには、最大 500 個の脅威エントリを含めることができます。
HTTP POST リクエストに、チェックする URL のハッシュプレフィックスが含まれている。クライアントには、複数の脅威エントリを 1 つのリクエストにまとめて、帯域幅の使用量を減らすことをおすすめします。
HTTP POST レスポンスは、一致する全長ハッシュと、正と負のキャッシュ期間を返します。レスポンスでは最小待機時間も返される場合があります。

例: fullHashes.find

HTTP POST リクエスト

次の例では、比較と検証のために 2 つのセーフブラウジングリストの名前と 3 つのハッシュプレフィックスが送信されます。

リクエストヘッダー

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

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

リクエスト本文

リクエストの本文には、クライアント情報（ID とバージョン）、クライアントの状態、脅威情報（リスト名とハッシュプレフィックス）が含まれます。JSON リクエストの場合、ハッシュプレフィックスは base64 エンコード形式で送信する必要があります。詳細については、fullHashes.find リクエストの本文と、サンプルコードに続く説明をご覧ください。

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

クライアント情報

すべてのクライアントの状態

clientStates フィールドには、クライアントのローカルデータベース内にあるすべてのセーフブラウジングリストについて、クライアントの状態が保持されます。（クライアントの状態は、threatListUpdates.fetch レスポンスの newClientState フィールドに返されます）。

セーフブラウジングリスト

threatTypes、platformTypes、threatEntryTypes の各フィールドを組み合わせることで、セーフブラウジングリストが識別（命名）されます。この例では、MALWARE/WINDOWS/URL と SOCIAL_ENGINEERING/WINDOWS/URL の 2 つのリストが識別されます。リクエストを送信する前に、指定したタイプの組み合わせが有効であることを確認してください（セーフブラウジングリストをご覧ください）。

脅威のハッシュプレフィックス

ThreatEntries 配列には、チェックする URL のハッシュプレフィックスが含まれます。 hash フィールドには、ローカルデータベースに存在する正確なハッシュプレフィックスを含める必要があります。たとえば、ローカルハッシュプレフィックスが 4 バイトの場合、脅威エントリの長さは 4 バイトである必要があります。ローカルハッシュプレフィックスが 7 バイトに延長された場合、脅威エントリは 7 バイトでなければなりません。

この例では、リクエストに 3 つのハッシュプレフィックスが含まれています。これら 3 つのプレフィックスがすべてセーフブラウジングリストと比較され、一致する全長のハッシュがあるかどうかが判断されます。

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

HTTP POST レスポンス

次の例では、レスポンスとして、セーフブラウジングリスト別に整理された一致データ、キャッシュ、待機時間が返されます。

レスポンスヘッダー

レスポンスヘッダーには、HTTP ステータスコードとコンテンツタイプが含まれます。HTTP/200 以外のステータスコードを受け取ったクライアントは、バックオフを行う必要があります（リクエストの頻度を参照）。

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

レスポンスの本文

レスポンスの本文には一致情報（リスト名と全長のハッシュ、メタデータ（利用可能な場合）、キャッシュ期間）が含まれます。この例では、レスポンスの本文に最小待機時間も含まれています。詳細については、fullHashes.find レスポンスの本文と、サンプルコードに続く説明をご覧ください。

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

一致

Matches オブジェクトは、2 つのハッシュプレフィックスについて一致する完全長のハッシュを返します。これらのハッシュに対応する URL は安全でないと見なされます。3 番目のハッシュプレフィックスに一致する URL が見つからなかったため、何も返されません。このハッシュプレフィックスに対応する URL は安全と見なされます。

この例では、1 つの完全長ハッシュと 1 つのハッシュプレフィックスがマッチングされることに注意してください。ただし、同じハッシュプレフィックスにマッピングされる複数の完全ハッシュが存在することは可能です。

メタデータ

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

キャッシュ期間

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

最小待機時間

minimumWaitDuration フィールドは、クライアントが 300 秒（5 分）待ってから次の fullHashes リクエストを送信することを示します。レスポンスに待機時間が含まれる場合と含まれない場合があります（リクエストの頻度をご覧ください）。

Safe Browsing Update API（v4）

概要

ローカル データベースの更新

例: ThreatListUpdates.fetch

HTTP POST リクエスト

リクエスト ヘッダー

リクエスト本文

クライアント情報

セーフ ブラウジング リスト

クライアントの状態

サイズ制限

サポートされている圧縮

HTTP POST レスポンス

レスポンス ヘッダー

レスポンスの本文

データベースの更新

新しいクライアントの状態

チェックサム

最小待機時間

URL の確認

例: fullHashes.find

HTTP POST リクエスト

リクエスト ヘッダー

リクエスト本文

クライアント情報

すべてのクライアントの状態

セーフ ブラウジング リスト

脅威のハッシュ プレフィックス

HTTP POST レスポンス

レスポンス ヘッダー

レスポンスの本文

一致

メタデータ

キャッシュ期間

最小待機時間

ローカルデータベースの更新

リクエストヘッダー

セーフブラウジングリスト

レスポンスヘッダー

リクエストヘッダー

セーフブラウジングリスト

脅威のハッシュプレフィックス

レスポンスヘッダー