Method: hashes.search

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

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

HTTP リクエスト

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

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

クエリ パラメータ

パラメータ
hashPrefixes[]

string (bytes format)

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

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

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

string

省略可。クライアントが特定の種類の脅威のみを取得するなど、フィルタリングに関心がある場合は、これを指定できます。省略すると、一致するすべての脅威が返されます。セーフ ブラウジングによる保護を最大限にするために、この設定を省略することを強くおすすめします。

フィルタは Google Common Expression Language を使用して指定します。詳しくは、https://github.com/google/cel-spec に一般的な例が記載されています。ここで使用できる具体的な例を次に示します。

フィルタ "threatType == ThreatType.SOCIAL_ENGINEERING" では、FullHashDetail 内の脅威の種類が SOCIAL_ENGINEERING である必要があります。識別子 "threatType" は、現在の脅威の種類を表します。識別子 "ThreatType" は、可能性のあるすべての脅威タイプのコレクションを表します。

フィルタ "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" では、脅威の種類を UNWANTED_SOFTWARE または MALWARE にする必要があります。

リクエスト本文

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

レスポンスの本文

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

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

V5 の新機能: FullHash と FullHashDetail が分離されています。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)

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

ThreatAttribute

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

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