Method: hashes.search

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

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

طلب HTTP

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

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

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

المعلمات
hashPrefixes[]

string (bytes format)

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

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

سلسلة مرمّزة باستخدام Base64

نص الطلب

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

نص الاستجابة

الرد الذي تم إرجاعه بعد البحث عن تجزئات التهديدات

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

الميزات الجديدة في الإصدار 5: تم الفصل بين FullHash وFullHashDetail. في حال كان التجزئة تمثّل موقعًا إلكترونيًا يتضمّن تهديدات متعدّدة (مثل البرامج الضارة والهندسة الاجتماعية)، ليس من الضروري إرسال التجزئة الكاملة مرّتين كما في الإصدار 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 تشير إلى أنّه يجب عدم استخدام threatType في عملية التنفيذ.
FRAME_ONLY تشير إلى أنّه يجب استخدام threatType فقط لفرض القيود على الإطارات.