البحث عن علامات تجزئة كاملة تتطابق مع البادئات المحدّدة.
هذه طريقة مخصّصة على النحو المحدّد في https://google.aip.dev/136 (تشير الطريقة المخصّصة إلى أنّ لها اسم مخصّص ضمن التسمية العامة الخاصة بتطوير واجهة برمجة التطبيقات في Google، ولا تشير إلى استخدام طريقة HTTP مخصّصة).
طلب HTTP
GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات طلب البحث
المَعلمات | |
---|---|
hashPrefixes[] |
مطلوبة. بادئات التجزئة التي سيتم البحث عنها. يجب ألا يرسل العملاء أكثر من 1000 بادئة تجزئة. ومع ذلك، باتباع إجراء معالجة عنوان URL، لن يحتاج العملاء إلى إرسال أكثر من 30 بادئة تجزئة. في الوقت الحالي، يجب أن يبلغ طول كل بادئة تجزئة 4 بايت بالضبط. قد يساعد هذا في المستقبل. سلسلة بترميز base64. |
filter |
اختياريّ. إذا كان العميل مهتمًا بالفلترة، مثل استرداد أنواع معيّنة من التهديدات فقط، يمكن تحديد ذلك. وفي حال حذفها، يتم عرض جميع التهديدات المطابقة. وننصحك بشدة بتجاهل هذا الإجراء للحصول على أقصى حماية كاملة يمكن أن توفّرها ميزة "التصفّح الآمن". يتم تحديد الفلتر باستخدام لغة التعبير الشائعة في Google، والتي يمكن العثور عليها على الرابط https://github.com/google/cel-spec بالإضافة إلى أمثلة عامة. فيما يلي بعض الأمثلة المحددة التي يمكن استخدامها هنا: يشترط الفلتر يشترط الفلتر " |
نص الطلب
يجب أن يكون نص الطلب فارغًا.
نص الاستجابة
عُرض الرد بعد البحث عن علامات تجزئة التهديد.
إذا لم يتم العثور على أي نتائج، سيعرض الخادم حالة OK (رمز حالة HTTP 200) مع ترك الحقل fullHashes
فارغًا، بدلاً من عرض حالة NOT_FOUND (رمز حالة HTTP 404).
الميزات الجديدة في الإصدار 5: هناك فاصل بين FullHash
وFullHashDetail
. إذا كانت التجزئة تمثل موقعًا إلكترونيًا يواجه تهديدات متعددة (على سبيل المثال MALWARE وSOCIAL_ENGINEERING)، لن تكون هناك حاجة إلى إرسال التجزئة الكاملة مرتين كما في الإصدار V4. بالإضافة إلى ذلك، تم تبسيط مدة ذاكرة التخزين المؤقت في حقل cacheDuration
واحد.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"fullHashes": [
{
object ( |
الحقول | |
---|---|
fullHashes[] |
قائمة بدون ترتيب. القائمة غير المرتبة لعلامات التجزئة الكاملة التي تم العثور عليها. |
cacheDuration |
مدة ذاكرة التخزين المؤقت من جهة العميل. على العميل إضافة هذه المدة إلى الوقت الحالي لتحديد وقت انتهاء الصلاحية. وينطبق وقت انتهاء الصلاحية بعد ذلك على كل بادئة تجزئة يطلبها العميل في الطلب، بغض النظر عن عدد التجزئات الكاملة التي يتم عرضها في الاستجابة. حتى إذا لم يعرض الخادم أي تجزئات كاملة لبادئة تجزئة معينة، يجب أيضًا تخزين هذه الحقيقة مؤقتًا بواسطة العميل. وإذا كان الحقل هام: يجب ألا يفترض العميل أن الخادم سيعرض مدة ذاكرة التخزين المؤقت نفسها لجميع الاستجابات. قد يختار الخادم مددًا مختلفة لذاكرة التخزين المؤقت للاستجابات المختلفة بناءً على الموقف. مدة بالثواني يصل عددها إلى تسعة أرقام كسرية وتنتهي بـ " |
FullHash
التجزئة الكاملة التي تم تحديدها بمطابقة واحدة أو أكثر.
تمثيل JSON |
---|
{
"fullHash": string,
"fullHashDetails": [
{
object ( |
الحقول | |
---|---|
fullHash |
التجزئة الكاملة المطابقة. هذه هي تجزئة SHA256. سيكون الطول 32 بايت بالضبط. سلسلة بترميز base64. |
fullHashDetails[] |
قائمة بدون ترتيب. حقل متكرّر يحدّد التفاصيل ذات الصلة بهذه التجزئة الكاملة |
FullHashDetail
تفاصيل حول تجزئة كاملة مطابقة.
ملاحظة مُهمّة بشأن التوافق مع إعادة التوجيه: قد يضيف الخادم أنواع تهديدات وسمات تهديد جديدة في أي وقت، وتُعدّ هذه الإضافات تغييرات طفيفة في الإصدار. تنص سياسة Google على عدم الكشف عن أرقام الإصدارات الثانوية في واجهات برمجة التطبيقات (يُرجى الاطّلاع على https://cloud.google.com/apis/design/versioning لمعرفة سياسة تحديد الإصدارات)، لذلك يجب أن يكون العملاء مستعدين لتلقّي رسائل FullHashDetail
التي تحتوي على قيم ThreatType
للتعداد أو قيم تعداد ThreatAttribute
يعتبرها العميل غير صالحة. وبالتالي، تقع على عاتق العميل مسؤولية التحقق من صلاحية جميع قيم التعداد ThreatType
وThreatAttribute
، وإذا تم اعتبار أي قيمة غير صالحة، على العميل تجاهل رسالة FullHashDetail
بأكملها.
تمثيل JSON |
---|
{ "threatType": enum ( |
الحقول | |
---|---|
threatType |
نوع التهديد. لن يكون هذا الحقل فارغًا أبدًا. |
attributes[] |
قائمة بدون ترتيب. سمات إضافية عن قيم التجزئة الكاملة تلك قد يكون هذا الحقل فارغًا. |
ThreatAttribute
سمات التهديدات وقد تضفي هذه السمات معنى إضافيًا لتهديد معيّن، ولكنها لن تؤثر في نوع التهديد. على سبيل المثال، قد تشير السمة إلى مستوى ثقة أقل، بينما قد تشير سمة مختلفة إلى مستوى ثقة أعلى. وقد تتم إضافة المزيد من السمات في المستقبل.
عمليات التعداد | |
---|---|
THREAT_ATTRIBUTE_UNSPECIFIED |
سمة غير معروفة. وإذا عرَض الخادم هذا، سيتجاهل العميل تمامًا FullHashDetail المضمّنة. |
CANARY |
يشير إلى عدم استخدام نوع التهديد لتنفيذ إجراءات التنفيذ. |
FRAME_ONLY |
يشير هذا الحقل إلى أنّ نوع التهديد يجب أن يتم استخدامه لتنفيذ إجراءات التنفيذ على الإطارات فقط. |