Method: hashes.search

هش کامل مطابق با پیشوندهای مشخص شده را جستجو کنید.

این یک روش سفارشی است که توسط https://google.aip.dev/136 تعریف شده است (روش سفارشی به این روش اشاره دارد که یک نام سفارشی در نام‌گذاری توسعه API عمومی Google دارد؛ به استفاده از روش HTTP سفارشی اشاره نمی‌کند).

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

پارامترهای پرس و جو

پارامترها
hashPrefixes[]

string ( bytes format)

مورد نیاز. پیشوندهای هش که باید جستجو شوند. مشتریان نباید بیش از 1000 پیشوند هش ارسال کنند. با این حال، به دنبال روش پردازش URL، مشتریان نباید بیش از 30 پیشوند هش ارسال کنند.

در حال حاضر هر پیشوند هش باید دقیقاً 4 بایت باشد. این ممکن است در آینده آرام شود.

رشته ای با کد base64.

filter

string

اختیاری. اگر مشتری علاقه مند به فیلتر کردن باشد، مانند بازیابی انواع خاصی از تهدیدات، می توان آن را مشخص کرد. در صورت حذف، تمام تهدیدات منطبق برگردانده می شوند. برای دریافت کاملترین حفاظتی که Safe Browsing می تواند ارائه دهد، به شدت توصیه می شود که این مورد را حذف کنید.

فیلتر با استفاده از زبان عبارت رایج گوگل مشخص شده است، که می‌توانید آن را در 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) وضعیت OK (کد وضعیت HTTP 200) را با فیلد fullHashes خالی برمی گرداند.

چیزهای جدید در V5 : یک جدایی بین FullHash و FullHashDetail وجود دارد. در صورتی که یک هش نشان دهنده سایتی باشد که چندین تهدید دارد (مانند MALWARE و SOCIAL_ENGINEERING)، نیازی نیست هش کامل دو برابر نسخه 4 ارسال شود. علاوه بر این، مدت زمان کش به یک فیلد cacheDuration ساده شده است.

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایندگی JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
فیلدها
fullHashes[]

object ( FullHash )

لیست نامرتب لیست نامرتب هش کامل پیدا شد.

cacheDuration

string ( Duration format)

مدت زمان کش سمت مشتری. مشتری باید این مدت زمان را به زمان فعلی اضافه کند تا زمان انقضا مشخص شود. زمان انقضا پس از آن برای هر پیشوند هش درخواست شده توسط مشتری در درخواست اعمال می شود، صرف نظر از اینکه چه تعداد هش کامل در پاسخ بازگردانده شده است. حتی اگر سرور هیچ هش کاملی را برای یک پیشوند هش خاص برنگرداند، این واقعیت نیز باید توسط مشتری ذخیره شود.

اگر و فقط اگر فیلد fullHashes خالی باشد، سرویس گیرنده ممکن است cacheDuration افزایش دهد تا انقضای جدیدی را تعیین کند که دیرتر از زمان تعیین شده توسط سرور باشد. در هر صورت، افزایش مدت زمان کش نباید بیشتر از 24 ساعت باشد.

مهم: کلاینت نباید فرض کند که سرور مدت زمان کش یکسانی را برای همه پاسخ ها برمی گرداند. سرور ممکن است بسته به موقعیت، مدت زمان کش متفاوتی را برای پاسخ های مختلف انتخاب کند.

مدت زمان در ثانیه با حداکثر نه رقم کسری که با ' s ' ختم می شود. مثال: "3.5s" .

FullHash

هش کامل با یک یا چند مورد منطبق شناسایی شده است.

نمایندگی 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 مراجعه کنید)، بنابراین مشتریان باید برای دریافت پیام‌های FullHashDetail حاوی مقادیر ThreatType enum یا ThreatAttribute آماده باشند. مقادیر enum که توسط مشتری نامعتبر در نظر گرفته می شوند. بنابراین، این مسئولیت مشتری است که اعتبار تمام مقادیر ThreatType و ThreatAttribute enum را بررسی کند. اگر مقداری نامعتبر در نظر گرفته شود، مشتری باید کل پیام FullHashDetail را نادیده بگیرد.

نمایندگی JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
فیلدها
threatType

enum ( ThreatType )

نوع تهدید. این فیلد هرگز خالی نخواهد بود.

attributes[]

enum ( ThreatAttribute )

لیست نامرتب ویژگی‌های اضافی درباره آن هش‌های کامل. این ممکن است خالی باشد.

ThreatAttribute

ویژگی های تهدید این ویژگی ها ممکن است معنای بیشتری به یک تهدید خاص بدهد اما بر نوع تهدید تأثیری نخواهد گذاشت. به عنوان مثال، یک ویژگی ممکن است اطمینان کمتری را مشخص کند در حالی که یک ویژگی دیگر ممکن است اطمینان بالاتری را مشخص کند. ممکن است در آینده ویژگی های بیشتری اضافه شود.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED ویژگی ناشناخته اگر این مورد توسط سرور برگردانده شود، کلاینت باید FullHashDetail را به طور کامل نادیده بگیرد.
CANARY نشان می دهد که typeType نباید برای اجرا استفاده شود.
FRAME_ONLY نشان می دهد که نوع تهدید فقط باید برای اعمال روی فریم ها استفاده شود.