ينطبق هذا المستند على الطريقة التالية: Update API (v4): threatListUpdates.fetch.
إعداد قاعدة البيانات
على العملاء الذين يستخدمون Update API إعداد قاعدة بيانات محلية وإجراء عملية تنزيل مبدئية لقوائم التشغيل الآمن التي يريدون العمل عليها. وللبدء، يمكنك إنشاء حزمة 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 على السلسلة الفارغة. سيؤدي ذلك إلى فرض تحديث كامل وعرض قائمة وحالة جديدة تمامًا.