Migration From V4
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
من التحسينات المهمة التي يوفّرها الإصدار 5 من "التصفّح الآمن من Google" مقارنةً بالإصدار 4 (وتحديدًا Update API في الإصدار 4) هي حداثة البيانات وتغطيتها. بما أنّ الحماية تعتمد بشكل كبير على قاعدة البيانات المحلية التي يحتفظ بها العميل، فإنّ التأخير في تحديث قاعدة البيانات المحلية وحجمها هما السبب الرئيسي في عدم توفّر الحماية. في الإصدار 4، يستغرق العميل العادي من 20 إلى 50 دقيقة للحصول على أحدث إصدار من قوائم التهديدات. لسوء الحظ، تنتشر هجمات التصيّد الاحتيالي بسرعة: اعتبارًا من عام 2021، كان% 60 من المواقع الإلكترونية التي تنفّذ الهجمات نشطًا لمدة أقل من 10 دقائق. تشير تحليلاتنا إلى أنّ حوالي %25 إلى %30 من حالات عدم توفّر الحماية من التصيّد الاحتيالي تعود إلى عدم حداثة البيانات. بالإضافة إلى ذلك، لا تكون بعض الأجهزة مجهّزة لإدارة جميع قوائم التهديدات في "التصفّح الآمن" من Google، والتي تستمر في النمو بمرور الوقت.
إذا كنت تستخدم حاليًا Update API الإصدار 4، يتوفّر مسار نقل سلس من الإصدار 4 إلى الإصدار 5 بدون الحاجة إلى إعادة ضبط قاعدة البيانات المحلية أو محوها. يوضّح هذا القسم كيفية إجراء ذلك.
تعديلات على قائمة التحويل
على عكس الإصدار 4، حيث يتم تحديد القوائم من خلال مجموعة من نوع التهديد ونوع النظام الأساسي ونوع إدخال التهديد، يتم في الإصدار 5 تحديد القوائم ببساطة من خلال الاسم. ويوفّر ذلك المرونة عندما يمكن أن تتشارك قوائم الإصدار 5 المتعددة نوع التهديد نفسه. تمت إزالة أنواع المنصات وأنواع إدخالات التهديدات في الإصدار 5.
في الإصدار 4، يمكن استخدام طريقة threatListUpdates.fetch لتنزيل القوائم. في الإصدار 5، يتم التبديل إلى طريقة hashLists.batchGet.
يجب إجراء التغييرات التالية على الطلب:
- أزِل العنصر v4
ClientInfo بالكامل. بدلاً من تقديم تعريف العميل باستخدام حقل مخصّص، يمكنك ببساطة استخدام عنوان User-Agent المعروف. مع أنّه ليس هناك تنسيق محدّد لتقديم تعريف العميل في هذا العنوان، نقترح تضمين معرّف العميل الأصلي وإصدار العميل مفصولَين بمسافة أو شرطة مائلة.
- لكل عنصر v4
ListUpdateRequest:
- ابحث عن اسم قائمة الإصدار 5 المقابل من القوائم المتاحة وقدِّم هذا الاسم في طلب الإصدار 5.
- أزِل الحقول غير الضرورية، مثل
threat_entry_type أو platform_type.
- يتوافق الحقل
state في الإصدار 4 مباشرةً مع الحقل versions في الإصدار 5. يمكن ببساطة إرسال سلسلة البايت نفسها التي سيتم إرسالها إلى الخادم باستخدام الحقل state في الإصدار 4 من خلال الحقل versions في الإصدار 5.
- بالنسبة إلى قيود الإصدار 4، يستخدم الإصدار 5 نسخة مبسطة تُعرف باسم
SizeConstraints. يجب حذف الحقول الإضافية، مثل region.
يجب إجراء التغييرات التالية على الردّ:
- يتم ببساطة استبدال enum
ResponseType في الإصدار 4 بحقل منطقي اسمه partial_update.
- يمكن الآن أن تكون قيمة الحقل
minimum_wait_duration صفرًا أو يمكن إغفاله. وفي حال كان كذلك، يُطلب من العميل إرسال طلب آخر على الفور. يحدث ذلك فقط عندما يحدّد العميل في SizeConstraints قيدًا أصغر على الحد الأقصى لحجم التحديث من الحد الأقصى لحجم قاعدة البيانات.
- يجب تعديل خوارزمية فك ترميز Rice للأعداد الصحيحة ذات 32 بت. والفرق هو أنّ البيانات المرمّزة يتم ترميزها باستخدام ترتيب مختلف. في كل من الإصدار 4 والإصدار 5، يتم ترتيب بادئات التجزئة ذات 32 بت حسب الترتيب المعجمي. ولكن في الإصدار 4، يتم التعامل مع هذه البادئات على أنّها little endian عند ترتيبها، بينما في الإصدار 5 يتم التعامل مع هذه البادئات على أنّها big endian عند ترتيبها. وهذا يعني أنّ العميل لا يحتاج إلى إجراء أي عملية ترتيب، لأنّ الترتيب المعجمي مطابق للترتيب الرقمي مع نظام النهاية الكبرى. يمكنك الاطّلاع هنا على مثال لهذا النوع في عملية تنفيذ الإصدار 4 من Chromium. ويمكن إزالة هذا النوع من الترتيب.
- يجب تنفيذ خوارزمية فك ترميز Rice لأطوال التجزئة الأخرى أيضًا.
تحويل عمليات البحث باستخدام رموز التجزئة
في الإصدار 4، يمكن استخدام طريقة fullHashes.find للحصول على تجزئات كاملة. الطريقة المكافئة في الإصدار 5 هي الطريقة hashes.search.
يجب إجراء التغييرات التالية على الطلب:
- يجب أن تكون بنية الرمز البرمجي على النحو الذي يتيح إرسال بادئات التجزئة التي يبلغ طولها 4 بايتات فقط.
- أزِل عناصر v4
ClientInfo بالكامل. بدلاً من تقديم تعريف العميل باستخدام حقل مخصّص، يمكنك ببساطة استخدام عنوان User-Agent المعروف. مع أنّه ليس هناك تنسيق محدّد لتقديم تعريف العميل في هذا العنوان، نقترح تضمين معرّف العميل الأصلي وإصدار العميل مفصولَين بمسافة أو شرطة مائلة.
- أزِل الحقل
client_states. لم يعُد ذلك ضروريًا.
- لم يعُد من الضروري تضمين
threat_types والحقول المشابهة.
يجب إجراء التغييرات التالية على الردّ:
- تمت إزالة الحقل
minimum_wait_duration. يمكن للعميل دائمًا إصدار طلب جديد حسب الحاجة.
- تم تبسيط العنصر v4
ThreatMatch إلى العنصر FullHash.
- تم تبسيط التخزين المؤقت ليصبح مدة تخزين مؤقت واحدة. راجِع الإجراءات المذكورة أعلاه للتفاعل مع ذاكرة التخزين المؤقت.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-10 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-10 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Migration From V4\n\nOne significant improvement of Google Safe Browsing v5 over v4 (specifically, [the v4 Update API](/safe-browsing/v4/update-api)) is data freshness and coverage. Since the protection highly depends on the client-maintained local database, the delay and size of the local database update is the main contributor of the missed protection. In v4, the typical client takes 20 to 50 minutes to obtain the most up-to-date version of threat lists. Unfortunately, phishing attacks spread fast: as of 2021, 60% of sites that deliver attacks live less than 10 minutes. Our analysis shows that around 25-30% of missing phishing protection is due to such data staleness. Further, some devices are not equipped to manage the entirety of the Google Safe Browsing threat lists, which continues to grow larger over time.\n\nIf you are currently using the [v4 Update API](/safe-browsing/v4/update-api), there is a seamless migration path from v4 to v5 without having to reset or erase the local database. This section documents how to do that.\n\n### Converting List Updates\n\nUnlike V4, where lists are identified by the tuple of threat type, platform type, threat entry type, in v5 lists are simply identified by name. This provides flexibility when multiple v5 lists could share the same threat type. Platform types and threat entry types are removed in v5.\n\nIn v4, one would use the [threatListUpdates.fetch method](/safe-browsing/reference/rest/v4/threatListUpdates/fetch) to download lists. In v5, one would switch to the [hashLists.batchGet method](/safe-browsing/reference/rest/v5/hashLists/batchGet).\n\nThe following changes should be made to the request:\n\n1. Remove the [v4 `ClientInfo` object](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n2. For each [v4 `ListUpdateRequest` object](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#listupdaterequest):\n - Look up the corresponding v5 list name from the [available lists](/safe-browsing/reference/Local.Database#available-lists) and supply that name in the v5 request.\n - Remove unneeded fields such as `threat_entry_type` or `platform_type`.\n - The `state` field in v4 is directly compatible with the v5 `versions` field. The same byte string that would be sent to the server using the `state` field in v4 can simply be sent in v5 using the `versions` field.\n - For the v4 constraints, v5 uses a simplified version called [`SizeConstraints`](/safe-browsing/reference/rest/v5/SizeConstraints). Additional fields such as `region` should be dropped.\n\nThe following changes should be made to the response:\n\n1. The v4 [enum `ResponseType`](/safe-browsing/reference/rest/v4/threatListUpdates/fetch#ResponseType) is simply replaced by a boolean field named `partial_update`.\n2. The `minimum_wait_duration` field can now be zero or omitted. If it is, the client is requested to immediately make another request. This only happens when the client specifies in `SizeConstraints` a smaller constraint on max update size than the max database size.\n3. The Rice decoding algorithm for 32-bit integers will need to be adjusted. The difference is that the encoded data are encoded with a different endianness. In both v4 and v5, 32-bit hash prefixes are sorted lexicographically. But in v4, those prefixes are treated as little endian when sorted, whereas in v5 those prefixes are treated as big endian when sorted. This means that the client does not need to do any sorting, since lexicographic sorting is identical to numeric sorting with big endian. An example of this sort in the Chromium implementation of v4 can be found [here](https://source.chromium.org/chromium/chromium/src/+/main:components/safe_browsing/core/browser/db/v4_rice.cc;l=144-146;drc=8ba1bad80dc22235693a0dd41fe55c0fd2dbdabd). Such sorting can be removed.\n4. The Rice decoding algorithm will need to be implemented for other hash lengths as well.\n\n### Converting Hash Searches\n\nIn v4, one would use the [fullHashes.find method](/safe-browsing/reference/rest/v4/fullHashes/find) to get full hashes. The equivalent method in v5 is [the hashes.search method](/safe-browsing/reference/rest/v5/hashes/search).\n\nThe following changes should be made to the request:\n\n1. Structure the code to only send hash prefixes that are exactly 4 bytes in length.\n2. Remove the [v4 `ClientInfo` objects](/safe-browsing/reference/rest/v4/ClientInfo) altogether. Instead of supplying a client's identification using a dedicated field, simply use the well-known [User-Agent header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent). While there is no prescribed format for supplying the client identification in this header, we suggest simply including the original client ID and client version separated by a space character or a slash character.\n3. Remove the `client_states` field. It is no longer necessary.\n4. It is no longer needed to include `threat_types` and similar fields.\n\nThe following changes should be made to the response:\n\n1. The `minimum_wait_duration` field has been removed. The client can always issue a new request on an as-needed basis.\n2. The [v4 `ThreatMatch` object](/safe-browsing/reference/rest/v4/ThreatMatch) has been simplified into the [`FullHash`](/safe-browsing/reference/rest/v5/hashes/search#FullHash) object.\n3. Caching has been simplified into a single cache duration. See the above procedures for interacting with the cache."]]
