ينطبق هذا المستند على الطريقة التالية: Update API (v4): threatListUpdates.fetch.
إعداد قاعدة البيانات
على العملاء الذين يستخدمون واجهة برمجة التطبيقات Update إعداد قاعدة بيانات محلية وإجراء عملية تنزيل مبدئية لقوائم "التصفح الآمن" التي يريدون العمل معها. للبدء، يمكنك إنشاء حزمة safebrowsing Go ونشرها (أو استخدام الحزمة لوضع نموذج لعملية التنفيذ الخاصة بك). للحصول على مزيد من المعلومات، يمكنك
الاطّلاع على https://github.com/google/safebrowsing/.
تعديلات قاعدة البيانات
ولضمان الحماية من أحدث التهديدات، ننصح العملاء بشدّة بتعديل قوائم "التصفّح الآمن" المحلية بانتظام باستخدام طريقة threatListUpdates.fetch. يُحدِّد طلب threatListUpdates.fetch القوائم المطلوب تحديثها. إذا كانت هناك قيود على الذاكرة أو معدل نقل البيانات في البرامج، فيمكنها أيضًا استخدام الطلب لتعيين قيود التحديث (راجع قيود التحديث). يعرض الاستجابة threatListUpdates.fetch إما تحديثًا كاملاً أو تحديثًا جزئيًا لكل قائمة، كما هو موضح أدناه.التحديثات الكاملة
يتم عرض التحديثات الكاملة عندما يترك العميل الحقل state في
طلب threatListUpdates.fetch فارغًا أو عندما يقرّر الخادم أن هناك حاجة إلى إجراء تحديث كامل. للحصول على التحديثات الكاملة، يتم عرض
الإضافات فقط. ويُتوقّع من العميل
محو قاعدة البيانات المحلية قبل تطبيق التحديثات وإجراء
فحص التحقق.
يتم إرجاع التحديثات الكاملة عندما يرسل العميل الطلب الأولي للقائمة. في هذه الحالة، يُترك الحقل
state في الطلب فارغًا (لأنه لا تتوفّر قيمة لتقديمها) ويعرض الحقل
newClientState في الاستجابة الحالة الأولية للقائمة المحلية. يتم أيضًا عرض التحديثات الكاملة
عندما يترك العميل عمدًا حقل state فارغًا في الطلبات اللاحقة. سيؤدي ذلك إلى فرض تحديث كامل
وعرض حالة جديدة في حقل newClientState للاستجابة.
في بعض الأحيان، يعرض خادم التصفح الآمن تحديثًا كاملاً عندما يطلب العميل تحديثًا جزئيًا فقط. وقد يحدث هذا الأمر عندما ينزّل العميل في البداية نسخة صغيرة من القائمة ثم يحدّثها إلى إصدار أكبر منها، وسيعرض الخادم تحديثًا كاملاً بالقائمة بأكملها. قد يحدث هذا أيضًا إذا لم ينزّل العميل البيانات منذ مدة طويلة وطلب تحديثًا جزئيًا، ومرة أخرى، سيعرض الخادم تحديثًا كاملاً بالقائمة بأكملها.
تعديلات جزئية
يتم عرض التحديثات الجزئية عندما يقدّم العميل قيمة للحقل state في
طلب threatListUpdates.fetch
(يُستثنى من ذلك، كما هو موضّح أعلاه، عندما يقرّر الخادم أن هناك تحديثًا كاملاً مطلوبًا). وبالنسبة إلى
التعديلات الجزئية، يتم عرض كل من الإضافات
وعمليات الإزالة. يعدّل العميل القوائم في قاعدة البيانات المحلية (يطبّق عمليات الإزالة قبل الإضافات) ثم يُجري فحص التحقّق.
الإضافات
الإضافات هي بادئات تجزئة SHA256 التي يجب إضافتها إلى قاعدة البيانات المحلية. يبلغ طول الغالبية العظمى من بادئات التجزئة 4 بايت، لكن قد يتراوح طول بعض بادئات التجزئة بين 4 و32 بايت. لذلك، يمكن عرض مجموعات متعددة من الإضافات، على سبيل المثال، مجموعة تحتوي على بادئات 4 بايت وأخرى تحتوي على بادئات 5 بايت.
إذا كان العميل يتيح الضغط، قد يتم ضغط الاستجابة باستخدام ضغط الأرز. ومع ذلك، يتم ضغط بادئات التجزئة بحجم 4 بايت فقط. يتم دائمًا إرسال بادئات التجزئة الأطول بتنسيق غير مضغوط وغير مضغوط (راجِع الضغط).
عمليات الإزالة
عمليات الإزالة هي فهارس قائمة على صفر في قاعدة بيانات العميل التي تم ترتيبها بشكل عِلمي وتشير إلى الإدخالات التي يجب إزالتها من قاعدة البيانات المحلية. سيتم عرض مجموعة واحدة فقط من عمليات الإزالة.
إذا كان العميل يتيح الضغط، يتم عرض "تجزئات الأرز" و "مؤشرات الأرز". إذا لم يكن الضغط متاحًا، يتم عرض "التجزئة الأولية" و "المؤشرات الأولية" (راجِع الضغط).
إجراءات التحقّق من الصحّة
عند عرض الاستجابة threatListUpdates.fetch، سواء مع تحديث كامل أو تحديث جزئي، من المتوقع أن يجري العميل فحصًا للتحقق.
يعدّل العميل أولاً القوائم في قاعدة البيانات المحلية (يتم تطبيق عمليات الإزالة قبل الإضافات). بعد ذلك، يحسب العميل تجزئة SHA256 للقائمة المحلية (المرتّبة بشكل لغوي) ويقارنها بالمجموع الاختباري الذي يتم عرضه في الاستجابة. وإذا كانت القيمتان متساويتان، ستُعتبر قائمة "التصفّح الآمن" "صحيحة".
وإذا لم تكن القيمتان متساويتين، فستعتبر قائمة التصفح الآمن "تلفة". على العميل محو القائمة من قاعدة البيانات وإعادة إصدار تحديث ثانٍ مع ضبط حقل state على السلسلة الفارغة، وسيؤدي ذلك إلى فرض إجراء تعديل كامل وعرض قائمة وحالة جديدتَين.