Method: hashes.search

البحث عن علامات تجزئة كاملة تطابق البادئات المحدّدة

هذه طريقة مخصّصة وفقًا لتعريف https://google.aip.dev/136 (تشير الطريقة المخصّصة إلى أنّ لهذه الطريقة اسم مخصّص ضمن التسمية العامة لتطوير واجهة برمجة التطبيقات من Google، ولا تشير إلى استخدام طريقة HTTP مخصّصة).

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

معامِلات طلب البحث

المعلمات
hashPrefixes[]

string (bytes format)

مطلوب. بادئات التجزئة المطلوب البحث عنها. يجب ألا يرسل العملاء أكثر من 1,000 بادئة تجزئة. مع ذلك، ووفقًا لإجراء معالجة عناوين URL، "ينبغي ألا يحتاج العملاء إلى إرسال أكثر من 30 بادئة تجزئة.

في الوقت الحالي، يجب أن يكون طول كل بادئة تجزئة 4 بايت بالضبط. وقد يكون هذا مريحًا في المستقبل.

سلسلة بترميز base64.
filter

string

اختياريّ. أما إذا كان العميل مهتمًا بالتصفية، مثل استرداد أنواع معينة من التهديدات فقط، فيمكن تحديد ذلك. وفي حال حذفها، يتم عرض جميع التهديدات المطابقة. وننصحك بشدة بتجاهل هذه الطريقة للحصول على أقصى حماية كاملة يمكن أن توفّرها ميزة "التصفّح الآمن".

يتم تحديد الفلتر باستخدام لغة التعبير الشائعة في Google، والتي يمكن العثور عليها على الرابط 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.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

ظهرت الاستجابة بعد البحث في تجزئات التهديد.

إذا لم يتم العثور على أي شيء، سيعرض الخادم حالة "صالح" (رمز حالة HTTP 200) مع ترك الحقل fullHashes فارغًا، بدلاً من عرض حالة NOT_FOUND (رمز حالة HTTP 404).

الجديد في 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 على عدم الكشف عن أرقام إصدارات ثانوية في واجهات برمجة التطبيقات (يُرجى الاطّلاع على https://cloud.google.com/apis/design/versioning للاطّلاع على سياسة تحديد الإصدارات)، لذلك يجب أن يكون العملاء مستعدّين لتلقّي رسائل FullHashDetail التي تحتوي على قيم تعداد ThreatType أو قيم تعداد لـ ThreatAttribute يعتبرها العميل غير صالحة. وبالتالي، تقع على عاتق العميل مسؤولية التحقّق من صلاحية جميع قيم التعداد للسمة ThreatType وThreatAttribute. وإذا تم اعتبار أي قيمة غير صالحة، على العميل تجاهل رسالة FullHashDetail بالكامل.

تمثيل JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
الحقول
threatType

enum (ThreatType)

يشير ذلك المصطلح إلى نوع التهديد. لن يكون هذا الحقل فارغًا أبدًا.
attributes[]

enum (ThreatAttribute)

قائمة بدون ترتيب. سمات إضافية عن علامات التجزئة الكاملة هذه قد يكون هذا الحقل فارغًا.

ThreatAttribute

سمات التهديدات. وقد تضيف هذه السمات معنى إضافيًا لتهديد معيّن ولكنها لن تؤثر في نوع التهديد. على سبيل المثال، قد تحدّد إحدى السمات مستوى ثقة أقل، في حين أنّ سمة مختلفة قد تحدّد مستوى ثقة أعلى. ويمكن إضافة المزيد من السمات في المستقبل.

عمليات التعداد
THREAT_ATTRIBUTE_UNSPECIFIED سمة غير معروفة. وفي حال عرض الخادم هذه الرسالة، سيتجاهل العميل سياسة FullHashDetail المضمّنة تمامًا.
CANARY يشير هذا الرمز إلى وجوب عدم استخدام نوع التهديد لإجراء تنفيذ.
FRAME_ONLY يشير إلى أنّه يجب استخدام نوع التهديد فقط لتنفيذ الإجراء على الإطارات.