Method: hashes.search

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

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

درخواست HTTP

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

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

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

string ( bytes format)

الزامی. پیشوندهای هش مورد جستجو. کلاینت‌ها نباید بیش از ۱۰۰۰ پیشوند هش ارسال کنند. با این حال، طبق روال پردازش URL، کلاینت‌ها نباید بیش از ۳۰ پیشوند هش ارسال کنند.

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

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

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

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

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

object ( FullHash )

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

cacheDuration

string ( Duration format)

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

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

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

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

فول‌هش

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

نمایش JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
فیلدها
fullHash

string ( bytes format)

هش کامل منطبق. این هش SHA256 است. طول آن دقیقاً ۳۲ بایت خواهد بود.

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

fullHashDetails[]

object ( FullHashDetail )

لیست نامرتب. یک فیلد تکراری که جزئیات مربوط به این هش کامل را مشخص می‌کند.

جزئیات کامل

جزئیات مربوط به یک هش کامل منطبق.

نکته‌ای مهم در مورد سازگاری رو به جلو: انواع تهدیدها و ویژگی‌های تهدید جدید ممکن است در هر زمانی توسط سرور اضافه شوند؛ این تغییرات جزئی نسخه در نظر گرفته می‌شوند. سیاست گوگل این است که شماره نسخه‌های جزئی را در 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 )

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

ویژگی تهدید

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

انوم‌ها
THREAT_ATTRIBUTE_UNSPECIFIED ویژگی ناشناخته. اگر این توسط سرور برگردانده شود، کلاینت باید FullHashDetail محصور شده را به طور کلی نادیده بگیرد.
CANARY نشان می‌دهد که نباید از threatType برای اعمال قانون استفاده شود.
FRAME_ONLY نشان می‌دهد که threatType فقط باید برای اعمال محدودیت روی فریم‌ها استفاده شود.