インデックス
SafeBrowsing(インターフェース)BatchGetHashListsRequest(メッセージ)BatchGetHashListsResponse(メッセージ)FullHash(メッセージ)FullHash.FullHashDetail(メッセージ)GetHashListRequest(メッセージ)HashList(メッセージ)HashListMetadata(メッセージ)HashListMetadata.HashLength(列挙型)LikelySafeType(列挙型)ListHashListsRequest(メッセージ)ListHashListsResponse(メッセージ)RiceDeltaEncoded128Bit(メッセージ)RiceDeltaEncoded256Bit(メッセージ)RiceDeltaEncoded32Bit(メッセージ)RiceDeltaEncoded64Bit(メッセージ)SearchHashesRequest(メッセージ)SearchHashesResponse(メッセージ)SearchUrlsRequest(メッセージ)SearchUrlsResponse(メッセージ)SizeConstraints(メッセージ)ThreatAttribute(列挙型)ThreatType(列挙型)ThreatUrl(メッセージ)
SafeBrowsing
セーフ ブラウジング API を使用すると、クライアントは、常に更新される Google の安全でないウェブリソースのリストに照らし合わせてウェブリソース(通常は URL)をチェックできます。
| BatchGetHashLists |
|---|
|
複数のハッシュリストを一度に取得します。 クライアントが複数のハッシュリストを取得する必要があることはよくあります。このメソッドを使用する方が、通常の Get メソッドを複数回使用するよりもおすすめです。 これは、https://google.aip.dev/231 で定義されている標準のバッチ Get メソッドであり、HTTP メソッドも GET です。 |
| GetHashList |
|---|
|
ハッシュリストの最新のコンテンツを取得します。ハッシュリストは、脅威リストまたは非脅威リスト(グローバル キャッシュなど)のいずれかになります。 これは、https://google.aip.dev/131 で定義されている標準の Get メソッドであり、HTTP メソッドも GET です。 |
| ListHashLists |
|---|
|
ハッシュリストを一覧表示します。 V5 API では、このメソッドによって返されたハッシュリストが削除されることはありません。これにより、クライアントはこのメソッドの使用をスキップして、必要なすべてのハッシュリストをハードコードできます。 これは、https://google.aip.dev/132 で定義されている標準の List メソッドであり、HTTP メソッドは GET です。 |
| SearchHashes |
|---|
|
指定されたプレフィックスに一致する完全なハッシュを検索します。 これは https://google.aip.dev/136 で定義されているカスタム メソッドです(カスタム メソッドとは、Google の一般的な API 開発命名規則内でカスタム名を持つメソッドを指します。カスタム HTTP メソッドの使用を指すものではありません)。 |
| SearchUrls |
|---|
|
既知の脅威に一致する URL を検索します。各 URL とそのホスト接尾辞とパス接頭辞の式(深さの制限まで)がチェックされます。つまり、リクエストに含まれていないが、リクエストされた URL の表現である URL がレスポンスに含まれる可能性があります。 |
BatchGetHashListsRequest
複数のハッシュリストを同時に取得するリクエスト。
| フィールド | |
|---|---|
names[] |
必須。特定のハッシュリストの名前。このリストは脅威リストでも、グローバル キャッシュでも構いません。名前に重複を含めることはできません。重複が含まれている場合、クライアントはエラーを受け取ります。 |
version[] |
クライアントがすでに持っているハッシュリストのバージョン。クライアントがハッシュリストを初めて取得する場合は、このフィールドを空のままにします。それ以外の場合、クライアントはサーバーから以前に受信したバージョンを提供する必要があります。クライアントはこれらのバイトを操作してはなりません。 クライアントは、対応するリスト名と同じ順序でバージョンを送信する必要はありません。クライアントは、名前の数よりも少ないバージョンまたは多いバージョンをリクエストで送信できます。ただし、クライアントは同じ名前に対応する複数のバージョンを送信してはなりません。送信した場合、クライアントはエラーを受け取ります。 履歴: API の V4 では、これは |
size_constraints |
各リストのサイズ制約。省略した場合、制約はありません。ここで示されるサイズは、すべてのリストを合計したものではなく、リストごとのサイズです。 |
BatchGetHashListsResponse
複数のハッシュリストを含むレスポンス。
| フィールド | |
|---|---|
hash_lists[] |
ハッシュリストは、リクエストで指定された順序と同じ順序で返されます。 |
FullHash
1 つ以上の照合で識別された完全なハッシュ。
| フィールド | |
|---|---|
full_hash |
一致する完全なハッシュ。これは SHA256 ハッシュです。長さは正確に 32 バイトになります。 |
full_hash_details[] |
順序なしリスト。このフルハッシュに関連する詳細を特定する繰り返しフィールド。 |
FullHashDetail
一致する完全なハッシュに関する詳細。
前方互換性に関する重要な注意事項: 新しい脅威タイプと脅威属性は、サーバーによっていつでも追加される可能性があります。これらの追加はマイナー バージョンの変更と見なされます。Google のポリシーでは、API でマイナー バージョン番号を公開しないことになっています(バージョニング ポリシーについては、https://cloud.google.com/apis/design/versioning を参照)。そのため、クライアントは、クライアントが無効と見なす ThreatType 列挙値または ThreatAttribute 列挙値を含む FullHashDetail メッセージを受信する準備をしなければなりません。したがって、すべての ThreatType 列挙値と ThreatAttribute 列挙値の有効性を確認するのはクライアントの責任です。無効と見なされる値がある場合、クライアントは FullHashDetail メッセージ全体を無視しなければなりません。
| フィールド | |
|---|---|
threat_type |
脅威のタイプ。このフィールドは空になることはありません。 |
attributes[] |
順序なしリスト。これらの完全なハッシュに関する追加の属性。空の場合もあります。 |
GetHashListRequest
ハッシュリスト(脅威リストまたはグローバル キャッシュなどの非脅威リスト)を取得するリクエスト。
V5 の新機能: わかりやすくするために、V4 で states と呼ばれていたものが version に変更されました。リストに名前が付けられ、プラットフォーム タイプと脅威エントリ タイプが削除されました。複数のリストに同じ脅威タイプを設定したり、1 つのリストで複数の脅威タイプを対象にしたりできるようになりました。V4 の可変長のハッシュ接頭辞は多くのクライアント実装で問題を引き起こしていましたが、リスト内のすべてのハッシュが単一の長さになったため、クライアント実装の効率が大幅に向上しました。制約が簡素化され、圧縮タイプが削除されました(圧縮は常に適用されます)。
| フィールド | |
|---|---|
name |
必須。この特定のハッシュリストの名前。脅威リストまたはグローバル キャッシュのいずれかになります。 |
version |
クライアントがすでに持っているハッシュリストのバージョン。クライアントがハッシュリストを初めて取得する場合、このフィールドは空のままにする必要があります。それ以外の場合、クライアントはサーバーから以前に受信したバージョンを提供すべきです。クライアントはこれらのバイトを操作してはなりません。 V5 の新機能: API の V4 では、これは |
size_constraints |
リストのサイズ制約。省略した場合、制約はありません。制約は、処理能力、帯域幅、ストレージが限られているすべてのデバイスで推奨されます。 |
HashList
名前で識別されるハッシュのリスト。
| フィールド | |
|---|---|
name |
ハッシュリストの名前。グローバル キャッシュもハッシュリストであり、ここで参照できます。 |
version |
ハッシュリストのバージョン。クライアントはこれらのバイトを操作してはなりません。 |
partial_update |
true の場合、これはクライアントがすでに持っているものに基づいて追加と削除を含む部分的な差分です。false の場合、これは完全なハッシュリストです。 false の場合、クライアントはこのハッシュリストのローカルに保存されたバージョンを削除しなければなりません。これは、クライアントが所有しているバージョンが大幅に古いか、クライアント データが破損している可能性があることを意味します。 true の場合、クライアントは削除と追加を適用して増分更新を適用しなければなりません。 |
compressed_removals |
削除インデックスの Rice-delta エンコード バージョン。各ハッシュリストのエントリ数は 2^32 未満であるため、インデックスは 32 ビット整数として扱われ、エンコードされます。 |
minimum_wait_duration |
クライアントは、ハッシュリストを再度取得するまで、少なくともこの時間待機する必要があります。省略された場合、または 0 の場合、クライアントは直ちにフェッチすべきです。これは、サーバーにクライアントに送信する追加の更新があるものの、クライアントが指定した制約により送信できなかったことを示します。 |
sha256_checksum |
すべてのハッシュのソート済みリスト。SHA256 で再度ハッシュ化されます。これは、指定された更新を適用した後にデータベースに存在するすべてのハッシュのソート済みリストのチェックサムです。更新が提供されなかった場合、サーバーはこのフィールドを省略して、クライアントが既存のチェックサムを使用する必要があることを示します。 |
metadata |
ハッシュリストに関するメタデータ。これは |
共用体フィールド compressed_additions。追加の Rice-delta エンコード バージョン。追加のハッシュ プレフィックスの長さは、リスト内のすべての追加で均一です。compressed_additions は次のいずれかになります。 |
|
additions_four_bytes |
4 バイトの追加。 |
additions_eight_bytes |
8 バイトの追加。 |
additions_sixteen_bytes |
16 バイトの追加。 |
additions_thirty_two_bytes |
32 バイトの追加。 |
HashListMetadata
特定のハッシュリストに関するメタデータ。
| フィールド | |
|---|---|
threat_types[] |
順序なしリスト。空でない場合、ハッシュリストが脅威リストの一種であることを指定し、このハッシュリスト内のハッシュまたはハッシュ プレフィックスに関連付けられた脅威の種類を列挙します。エントリが脅威を表していない場合(安全なタイプを表している場合など)は、空になることがあります。 |
likely_safe_types[] |
順序なしリスト。空でない場合、ハッシュリストが安全である可能性の高いハッシュのリストを表し、それらが安全である可能性が高いと見なされる方法を列挙することを指定します。このフィールドは threat_types フィールドと相互に排他的です。 |
description |
このリストに関する人が読める形式の説明。英語で書かれています。 |
hash_length |
このハッシュリストでサポートされているハッシュの長さ。各ハッシュリストは 1 つの長さのみをサポートします。同じ脅威タイプまたは安全なタイプのセットに対して異なるハッシュ長が導入された場合、個別の名前とそれぞれのハッシュ長が設定された別のリストとして導入されます。 |
HashLength
ハッシュリスト内のハッシュの長さ。
| 列挙型 | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
長さが指定されていません。 |
FOUR_BYTES |
各ハッシュは 4 バイトのプレフィックスです。 |
EIGHT_BYTES |
各ハッシュは 8 バイトのプレフィックスです。 |
SIXTEEN_BYTES |
各ハッシュは 16 バイトのプレフィックスです。 |
THIRTY_TWO_BYTES |
各ハッシュは 32 バイトのフルハッシュです。 |
LikelySafeType
安全である可能性が高いサイトの種類。
SearchHashesResponse には意図的に LikelySafeType が含まれていません。
| 列挙型 | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
不明。 |
GENERAL_BROWSING |
このサイトは、一般的なブラウジングには十分安全である可能性があります。これはグローバル キャッシュとも呼ばれます。 |
CSD |
このサイトは、クライアントサイド検出モデルやパスワード保護チェックを実行する必要がないほど安全である可能性が高いです。 |
DOWNLOAD |
このサイトは安全性が高いと判断されるため、このサイトからのダウンロードはチェックする必要がない可能性があります。 |
ListHashListsRequest
使用可能なハッシュリストを一覧表示するリクエスト。
| フィールド | |
|---|---|
page_size |
返すハッシュリストの最大数。サービスが返す値はこれよりも少ないことがあります。指定しない場合、サーバーはページサイズを選択します。このサイズはハッシュリストの数よりも大きくなる可能性があるため、ページネーションは不要になります。 |
page_token |
前回の |
ListHashListsResponse
ハッシュリストに関するメタデータを含むレスポンス。
| フィールド | |
|---|---|
hash_lists[] |
ハッシュは任意の順序でリストされます。ハッシュリストの内容ではなく、ハッシュリストに関するメタデータのみが含まれます。 |
next_page_token |
次のページを取得するために |
RiceDeltaEncoded128Bit
RiceDeltaEncoded32Bit と同じですが、128 ビットの数値をエンコードします。
| フィールド | |
|---|---|
first_value_hi |
エンコードされたデータ(ハッシュ)の最初のエントリの上位 64 ビット。フィールドが空の場合、上位 64 ビットはすべてゼロになります。 |
first_value_lo |
エンコードされたデータ(ハッシュ)の最初のエントリの下位 64 ビット。フィールドが空の場合、下位 64 ビットはすべてゼロになります。 |
rice_parameter |
ゴロムライス パラメータ。このパラメータは 99 ~ 126 の範囲内であることが保証されています。 |
entries_count |
エンコードされたデータでデルタ エンコードされたエントリの数。単一の整数のみがエンコードされた場合、これは 0 になり、単一の値は |
encoded_data |
Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。 |
RiceDeltaEncoded256Bit
RiceDeltaEncoded32Bit と同じですが、256 ビットの数値をエンコードします。
| フィールド | |
|---|---|
first_value_first_part |
エンコードされたデータ(ハッシュ)の最初のエントリの最初の 64 ビット。フィールドが空の場合、最初の 64 ビットはすべてゼロです。 |
first_value_second_part |
エンコードされたデータ(ハッシュ)の最初のエントリの 65 ~ 128 ビット。フィールドが空の場合、65 ~ 128 ビットはすべてゼロになります。 |
first_value_third_part |
エンコードされたデータ(ハッシュ)の最初のエントリの 129 ~ 192 ビット。フィールドが空の場合、129 ~ 192 ビットはすべてゼロになります。 |
first_value_fourth_part |
エンコードされたデータ(ハッシュ)の最初のエントリの最後の 64 ビット。フィールドが空の場合、最後の 64 ビットはすべてゼロになります。 |
rice_parameter |
ゴロムライス パラメータ。このパラメータは 227 ~ 254 の範囲で指定する必要があります。 |
entries_count |
エンコードされたデータでデルタ エンコードされたエントリの数。単一の整数のみがエンコードされた場合、これは 0 になり、単一の値は |
encoded_data |
Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。 |
RiceDeltaEncoded32Bit
Rice-Golomb でエンコードされたデータ。ハッシュまたは削除インデックスのいずれかに使用されます。ここで、すべてのハッシュまたはインデックスの長さは同じであり、その長さは正確に 32 ビットであることが保証されています。
一般的に、すべてのエントリを辞書順に並べ替えると、上位ビットは下位ビットほど頻繁には変化しないことがわかります。つまり、エントリ間の隣接差も考慮すると、上位ビットがゼロになる可能性が高くなります。このゼロの確率が高いことを利用して、特定のビット数を選択します。このビット数よりも上位のビットはすべてゼロになる可能性が高いため、単項符号化を使用します。rice_parameter フィールドをご覧ください。
履歴: Rice-delta エンコードは、この API の V4 で初めて使用されました。V5 では、2 つの大きな改善が行われました。1 つ目は、4 バイトを超えるハッシュ プレフィックスで Rice-delta エンコードが使用できるようになったことです。2 つ目は、エンコードされたデータがビッグ エンディアンとして扱われるようになり、コストのかかる並べ替えステップが不要になったことです。
| フィールド | |
|---|---|
first_value |
エンコードされたデータ(ハッシュまたはインデックス)の最初のエントリ。または、単一のハッシュ プレフィックスまたはインデックスのみがエンコードされた場合は、そのエントリの値。フィールドが空の場合、エントリはゼロになります。 |
rice_parameter |
ゴロムライス パラメータ。このパラメータは 3 ~ 30 の範囲で指定する必要があります。 |
entries_count |
エンコードされたデータでデルタ エンコードされたエントリの数。単一の整数のみがエンコードされた場合、これは 0 になり、単一の値は |
encoded_data |
Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。 |
RiceDeltaEncoded64Bit
RiceDeltaEncoded32Bit と同じですが、64 ビットの数値をエンコードします。
| フィールド | |
|---|---|
first_value |
エンコードされたデータ(ハッシュ)の最初のエントリ。または、単一のハッシュ接頭辞のみがエンコードされた場合は、そのエントリの値。フィールドが空の場合、エントリはゼロになります。 |
rice_parameter |
ゴロムライス パラメータ。このパラメータは 35 ~ 62 の範囲で指定する必要があります。 |
entries_count |
エンコードされたデータでデルタ エンコードされたエントリの数。単一の整数のみがエンコードされた場合、これは 0 になり、単一の値は |
encoded_data |
Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。 |
SearchHashesRequest
クライアントが特定のハッシュ接頭辞を検索するために発行するリクエスト。
これは脅威リストのみを検索するように設計されており、グローバル キャッシュなどの脅威以外のリストは検索しません。
V5 の新機能: クライアントは、ローカル データベースで ClientInfo やハッシュリストの状態を指定する必要がなくなりました。これはプライバシーを強化するためのものです。また、クライアントは関心のある脅威の種類を送信する必要はありません。
| フィールド | |
|---|---|
hash_prefixes[] |
必須。検索するハッシュ プレフィックス。クライアントは 1,000 個を超えるハッシュ接頭辞を送信してはなりません。ただし、URL 処理手順に沿って処理する場合、クライアントが送信する必要があるハッシュ接頭辞は 30 個以下であるべきです。 現在、各ハッシュ プレフィックスは 4 バイト長にする必要があります。この制限は、今後緩和される可能性があります。 |
filter |
省略可。クライアントが特定の種類の脅威のみを取得するなど、フィルタリングに関心がある場合は、これを指定できます。省略すると、一致するすべての脅威が返されます。この機能を省略して、セーフ ブラウジングが提供する最も完全な保護を利用することを強くおすすめします。 フィルタは Google Common Expression Language を使用して指定します。この言語は、一般的な例とともに https://github.com/google/cel-spec で確認できます。ここでは、使用できる具体的な例をいくつかご紹介します。 フィルタ フィルタ |
SearchHashesResponse
脅威ハッシュの検索後に返されるレスポンス。
何も見つからない場合、サーバーは NOT_FOUND ステータス(HTTP ステータス コード 404)を返すのではなく、full_hashes フィールドが空の OK ステータス(HTTP ステータス コード 200)を返します。
V5 の新機能: FullHash と FullHashDetail が分離されました。ハッシュが複数の脅威(マルウェアとソーシャル エンジニアリングの両方など)を含むサイトを表す場合、V4 のように完全なハッシュを 2 回送信する必要はありません。また、キャッシュの有効期間が 1 つの cache_duration フィールドに簡素化されました。
| フィールド | |
|---|---|
full_hashes[] |
順序なしリスト。検出された完全なハッシュの順序なしリスト。 |
cache_duration |
クライアントサイド キャッシュの期間。クライアントは、この期間を現在時刻に加算して有効期限を決定しなければなりません。有効期限は、レスポンスで返されるフルハッシュの数に関係なく、リクエストでクライアントがクエリしたすべてのハッシュ プレフィックスに適用されます。サーバーが特定のハッシュ プレフィックスの完全なハッシュを返さない場合でも、クライアントはこの事実をキャッシュに保存しなければなりません。
重要: クライアントは、サーバーがすべてのレスポンスに対して同じキャッシュ期間を返すと想定してはなりません。サーバーは、状況に応じてレスポンスごとに異なるキャッシュ期間を選択しても構いません。 |
SearchUrlsRequest
クライアントが発行する、指定された URL に一致する脅威を検索するリクエスト。
これは脅威リストのみを検索するように設計されており、グローバル キャッシュなどの脅威以外のリストは検索しません。
| フィールド | |
|---|---|
urls[] |
必須。ルックアップする URL。クライアントは 50 個を超える URL を送信してはなりません。 |
SearchUrlsResponse
指定された URL に一致する脅威を検索した後に返されるレスポンス。
何も見つからない場合、サーバーは NOT_FOUND ステータス(HTTP ステータス コード 404)を返すのではなく、threats フィールドが空の OK ステータス(HTTP ステータス コード 200)を返します。
| フィールド | |
|---|---|
threats[] |
順序なしリスト。検出された脅威の一致の順序なしリスト。各エントリには、URL と、その URL に一致する脅威タイプが含まれています。リクエスト内の URL のすべての表現が考慮されるため、リストのサイズはリクエスト内の URL の数よりも大きくなる可能性があります。 |
cache_duration |
クライアントサイド キャッシュの期間。クライアントは、この期間を現在時刻に加算して有効期限を決定しなければなりません。有効期限は、レスポンスで返される URL の数に関係なく、リクエストでクライアントによってクエリされるすべての URL に適用されます。サーバーが特定の URL に一致するものを返さなかった場合でも、クライアントはこの事実をキャッシュに保存しなければなりません。
重要: クライアントは、サーバーがすべてのレスポンスに対して同じキャッシュ期間を返すと想定してはなりません。サーバーは、状況に応じてレスポンスごとに異なるキャッシュ期間を選択しても構いません。 |
SizeConstraints
ハッシュリストのサイズに関する制約。
| フィールド | |
|---|---|
max_update_entries |
最大サイズ(エントリ数)。更新にはこの値を超えるエントリは含まれませんが、この値よりも少ないエントリが含まれる可能性はあります。これは 1024 以上でなければなりません。省略した場合、またはゼロの場合、アップデート サイズの上限は設定されません。 |
max_database_entries |
クライアントがリストのローカル データベースに保存するエントリの最大数を設定します。(サーバーは、クライアントにこの数より少ないエントリを保存させても構いません)。省略するか 0 にすると、データベース サイズの上限は設定されません。 |
ThreatAttribute
脅威の属性。これらの属性は、特定の脅威に意味を追加する可能性がありますが、脅威タイプには影響しません。たとえば、ある属性で低い信頼度を指定し、別の属性で高い信頼度を指定できます。今後、属性が追加される可能性があります。
| 列挙型 | |
|---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
不明な属性。サーバーからこれが返された場合、クライアントは囲まれた FullHashDetail を完全に無視します。 |
CANARY |
threat_type を適用に使用しないことを示します。 |
FRAME_ONLY |
threat_type はフレームの強制適用にのみ使用されることを示します。 |
ThreatType
脅威の種類。
| 列挙型 | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
不明な脅威タイプ。サーバーからこれが返された場合、クライアントは囲まれた FullHashDetail を完全に無視します。 |
MALWARE |
マルウェアの脅威の種類。マルウェアとは、ソフトウェアまたはモバイルアプリであり、特にパソコン、モバイル デバイス、それらで実行されているソフトウェア、パソコンやモバイル デバイスのユーザーに対して有害な影響を与えることを目的として設計されたものを指します。マルウェアは、ユーザーの同意なしにソフトウェアをインストールする、ウイルスなどの有害なソフトウェアをインストールするなど、悪意のある動作を示します。 詳細につきましては、こちらをご覧ください。 |
SOCIAL_ENGINEERING |
ソーシャル エンジニアリングの脅威の種類。ソーシャル エンジニアリング ページは、第三者の代理として行動していると偽って主張し、視聴者がその第三者の真の代理人に対してのみ信頼する行動を視聴者に取らせることを目的としています。フィッシングは、ソーシャル エンジニアリングの一種で、視聴者をだましてログイン認証情報などの情報を提供させる特定の行為に誘導するものです。 詳細につきましては、こちらをご覧ください。 |
UNWANTED_SOFTWARE |
望ましくないソフトウェアの脅威タイプ。望ましくないソフトウェアとは、Google のソフトウェア原則に準拠していないものの、マルウェアではないソフトウェアのことです。 |
POTENTIALLY_HARMFUL_APPLICATION |
Google Play ストアの Google Play プロテクトで使用される、有害な可能性があるアプリの脅威タイプ。 |
ThreatUrl
1 つ以上の脅威に一致する URL。
| フィールド | |
|---|---|
url |
1 つ以上の脅威と一致したリクエストされた URL。 |
threat_types[] |
順序なしリスト。URL が分類された脅威の順序なしリスト。 |