Method: hashes.search

指定した接頭辞に一致するフルハッシュを検索します。

これは、https://google.aip.dev/136 で定義されているカスタム メソッドです(カスタム メソッドとは、Google の一般的な API 開発の命名法でカスタム名を持つメソッドを指します。カスタム HTTP メソッドを使用するものではありません)。

HTTP リクエスト

GET https://safebrowsing.googleapis.com/v5/hashes:search

この URL は gRPC Transcoding 構文を使用します。

クエリ パラメータ

パラメータ
hashPrefixes[]

string (bytes format)

必須。検索するハッシュ接頭辞。クライアントは、1,000 個を超えるハッシュ プレフィックスを送信してはなりません。ただし、URL 処理手順に従うと、クライアントは 30 個を超えるハッシュ プレフィックスを送信する必要があるべきではありません。

現在、各ハッシュ接頭辞は長さが正確に 4 バイトである必要があります。今後は緩和しても構いません。

Base64 でエンコードされた文字列。

リクエストの本文

リクエストの本文は空にする必要があります。

レスポンスの本文

脅威ハッシュを検索した後に返されるレスポンス。

何も見つからない場合、サーバーは NOT_FOUND ステータス(HTTP ステータス コード 404)を返すのではなく、fullHashes フィールドが空になった OK ステータス(HTTP ステータス コード 200)を返します。

V5 の新機能: FullHashFullHashDetail が分離されています。V4 のように、ハッシュが複数の脅威(マルウェアと SOCIAL_ENGINEERING の両方)を持つサイトを表す場合、完全なハッシュを 2 回送信する必要はありません。さらに、キャッシュ期間は 1 つの cacheDuration フィールドに簡略化されています。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
フィールド
fullHashes[]

object (FullHash)

順序なしリスト。見つかったフルハッシュの順序付けされていないリスト。

cacheDuration

string (Duration format)

クライアントサイドのキャッシュ期間。クライアントは、この時間を現在の時刻に追加して有効期限を決定しなければなりません。有効期限は、レスポンスで返される完全なハッシュの数に関係なく、リクエストでクライアントによってクエリされたすべてのハッシュ接頭辞に適用されます。サーバーが特定のハッシュ接頭辞に対して完全なハッシュを返さない場合でも、この事実もクライアントによってキャッシュに保存されなければなりません。

フィールド fullHashes が空である場合にのみ、クライアントは cacheDuration を増やして、サーバーが指定した有効期限よりも後の新しい有効期限を決定しても構いません。いずれにしても、増加するキャッシュ期間を 24 時間以下にする必要があります。

重要: クライアントは、サーバーがすべてのレスポンスに対して同じキャッシュ期間を返すことを想定してはなりません。サーバーは、状況に応じて、レスポンスごとに異なるキャッシュ期間を選択しても構いません。

s で終わる小数 9 桁までの秒単位の期間。例: "3.5s"

FullHash

1 つ以上の一致によって識別される完全なハッシュ。

JSON 表現
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
フィールド
fullHash

string (bytes format)

照合するフルハッシュ。これは SHA256 ハッシュです。長さはちょうど 32 バイトになります。

Base64 でエンコードされた文字列。

fullHashDetails[]

object (FullHashDetail)

順序なしリスト。このフルハッシュに関連する詳細を識別する繰り返しフィールド。

FullHashDetail

一致するフルハッシュに関する詳細。

上位互換性に関する重要な注意事項:新しい脅威の種類と脅威の属性がサーバーによって随時追加される可能性があります。マイナー バージョンの変更と見なされます。Google のポリシーでは、API でマイナー バージョン番号を公開しないことが定められています(バージョニング ポリシーについては https://cloud.google.com/apis/design/versioning を参照)。そのためクライアントは、クライアントによって無効とみなされる ThreatType 列挙値または ThreatAttribute 列挙値を含む FullHashDetail メッセージを受信できるように準備しなければなりません。したがって、すべての ThreatType 列挙値と ThreatAttribute 列挙値の有効性を確認するのは、クライアントの責任です。いずれかの値が無効とみなされる場合、クライアントは FullHashDetail メッセージ全体を無視しなければなりません。

JSON 表現
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
フィールド
threatType

enum (ThreatType)

脅威の種類。このフィールドは空になりません。

attributes[]

enum (ThreatAttribute)

順序なしリスト。これらのフルハッシュに関する追加属性。この値は空でもかまいません。

ThreatType

脅威の種類

列挙型
THREAT_TYPE_UNSPECIFIED 不明な脅威タイプ。これがサーバーから返された場合、クライアントは含まれている FullHashDetail を完全に無視する必要があります。
MALWARE

マルウェアの脅威の種類。マルウェアとは、ソフトウェアまたはモバイルアプリであり、特にパソコン、モバイル デバイス、それらで実行されているソフトウェア、パソコンやモバイル デバイスのユーザーに対して有害な影響を与えることを目的として設計されたものを指します。マルウェアは、ユーザーの同意なしにソフトウェアをインストールする、ウイルスなどの有害なソフトウェアをインストールするなど、悪意のある動作を示します。

詳細につきましては、こちらをご覧ください。

SOCIAL_ENGINEERING

ソーシャル エンジニアリングの脅威タイプ。ソーシャル エンジニアリング ページでは、閲覧者が第三者の真の代理人のみを信頼して操作を実行させることを意図して、第三者を代理していると偽って視聴者を混乱させます。フィッシングとは、ログイン認証情報などの情報を提供してもらうという特定の操作をユーザーに行わせるソーシャル エンジニアリングの一種です。

詳細につきましては、こちらをご覧ください。

UNWANTED_SOFTWARE 望ましくないソフトウェアの脅威の種類。望ましくないソフトウェアとは、Google のソフトウェア原則に準拠していないがマルウェアではないソフトウェアを指します。
POTENTIALLY_HARMFUL_APPLICATION Play ストアの Google Play プロテクトで使用されている、有害な可能性があるアプリの脅威の種類。

ThreatAttribute

脅威の属性。これらの属性は、特定の脅威に追加の意味をもたらす可能性がありますが、脅威の種類には影響しません。たとえば、ある属性では低い信頼度を指定し、別の属性では高い信頼度を指定します。今後、他の属性が追加される可能性があります。

列挙型
THREAT_ATTRIBUTE_UNSPECIFIED 不明な属性です。これがサーバーから返された場合、クライアントは含まれている FullHashDetail を完全に無視する必要があります。
CANARY 適用に ThreatType を使用しないことを示します。
FRAME_ONLY ThreatType はフレームへの適用にのみ使用する必要があることを示します。