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 のように完全なハッシュを 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 をフレームの適用にのみ使用する必要があることを示します。