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)

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

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

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

نص الطلب

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

نص الاستجابة

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

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

الميزات الجديدة في الإصدار 5: تم فصل FullHash عن FullHashDetail. في حال كانت التجزئة تمثّل موقعًا إلكترونيًا يتضمّن تهديدات متعددة (مثل MALWARE وSOCIAL_ENGINEERING)، لا يلزم إرسال التجزئة الكاملة مرتين كما في الإصدار 4. بالإضافة إلى ذلك، تم تبسيط مدة ذاكرة التخزين المؤقت في حقل cacheDuration واحد.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
الحقول
fullHashes[]

object (FullHash)

قائمة بدون ترتيب القائمة غير المُرتَّبة للكلمات المحوَّلة الكاملة التي تم العثور عليها
cacheDuration

string (Duration format)

مدة ذاكرة التخزين المؤقت من جهة العميل على العميل إضافة هذه المدة إلى الوقت الحالي لتحديد وقت انتهاء الصلاحية. وينطبق وقت انتهاء الصلاحية بعد ذلك على كل بادئة تجزئة يبحث عنها العميل في الطلب، بغض النظر عن عدد التجزئات الكاملة التي يتم عرضها في الردّ. حتى إذا لم يعرض الخادم أيّ تجزئات كاملة لبادئة تجزئة معيّنة، يجب أن يخزن العميل هذه المعلومة أيضًا في ذاكرة التخزين المؤقت.

يجوز للعميل زيادة cacheDuration لتحديد تاريخ انتهاء صلاحية جديد يكون لاحقًا من التاريخ المحدّد من قِبل الخادم، وذلك إذا كان الحقل fullHashes فارغًا فقط. في جميع الأحوال، يجب ألا تزيد مدة الاحتفاظ بالذاكرة المؤقتة عن 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 فقط لفرض الإطارات.