Migration From V4
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
یکی از پیشرفت‌های قابل توجه Google Safe Browsing نسخه 5 نسبت به نسخه 4 (به طور خاص، API به‌روزرسانی v4 ) تازگی و پوشش داده است. از آنجایی که حفاظت به شدت به پایگاه داده محلی نگهداری شده توسط سرویس گیرنده بستگی دارد، تاخیر و اندازه به روز رسانی پایگاه داده محلی عامل اصلی حفاظت از دست رفته است. در نسخه 4، مشتری معمولی 20 تا 50 دقیقه طول می کشد تا به روزترین نسخه لیست تهدیدات را به دست آورد. متأسفانه، حملات فیشینگ به سرعت گسترش می‌یابد: تا سال 2021، 60 درصد سایت‌هایی که حملات را انجام می‌دهند کمتر از 10 دقیقه عمر می‌کنند. تجزیه و تحلیل ما نشان می دهد که حدود 25 تا 30 درصد از محافظت از دست رفته فیشینگ به دلیل چنین بیاتی داده ها است. علاوه بر این، برخی از دستگاه‌ها برای مدیریت کل لیست‌های تهدید مرور ایمن Google مجهز نیستند، که به مرور زمان بزرگ‌تر می‌شود.
اگر در حال حاضر از v4 Update API استفاده می‌کنید، یک مسیر یکپارچه از نسخه 4 به نسخه 5 بدون نیاز به تنظیم مجدد یا پاک کردن پایگاه داده محلی وجود دارد. این بخش نحوه انجام آن را مستند می کند.
تبدیل به‌روزرسانی‌های فهرست
بر خلاف V4، که در آن لیست ها با چند نوع تهدید، نوع پلت فرم، نوع ورود تهدید شناسایی می شوند، در V5 لیست ها به سادگی با نام شناسایی می شوند. هنگامی که چندین لیست v5 می توانند یک نوع تهدید را به اشتراک بگذارند، این انعطاف پذیری را فراهم می کند. انواع پلت فرم و انواع ورود تهدید در نسخه 5 حذف شده اند.
در نسخه 4، برای دانلود لیست ها از متد gefListUpdates.fetch استفاده می شود. در نسخه 5، می توان به روش hashLists.batchGet سوئیچ کرد.
تغییرات زیر باید در درخواست ایجاد شود:
- شی v4
ClientInfo را به طور کامل حذف کنید. به جای ارائه شناسه مشتری با استفاده از یک فیلد اختصاصی، به سادگی از هدر معروف User-Agent استفاده کنید. در حالی که هیچ فرمت مشخصی برای ارائه شناسه مشتری در این هدر وجود ندارد، پیشنهاد می کنیم به سادگی شناسه مشتری اصلی و نسخه مشتری را که با یک نویسه فاصله یا یک کاراکتر اسلش از هم جدا شده اند، اضافه کنید. - برای هر شیء v4
ListUpdateRequest :- نام لیست v5 مربوطه را از لیست های موجود جستجو کنید و آن نام را در درخواست v5 وارد کنید.
- فیلدهای غیرضروری مانند
threat_entry_type یا platform_type را حذف کنید. - فیلد
state در v4 مستقیماً با قسمت versions v5 سازگار است. همان رشته بایتی که با استفاده از فیلد state در v4 به سرور ارسال می شود، می تواند به سادگی با استفاده از فیلد versions در v5 ارسال شود. - برای محدودیت های v4، v5 از یک نسخه ساده شده به نام
SizeConstraints استفاده می کند. فیلدهای اضافی مانند region باید حذف شوند.
تغییرات زیر باید در پاسخ ایجاد شود:
- v4 enum
ResponseType به سادگی با یک فیلد بولی به نام partial_update جایگزین می شود. - اکنون می‌توان فیلد
minimum_wait_duration را صفر یا حذف کرد. اگر چنین باشد، از مشتری درخواست می شود که فوراً درخواست دیگری ارائه دهد. این تنها زمانی اتفاق می‌افتد که مشتری در SizeConstraints محدودیت کوچک‌تری را برای حداکثر اندازه به‌روزرسانی نسبت به حداکثر اندازه پایگاه داده تعیین کند. - الگوریتم رمزگشایی Rice برای اعداد صحیح 32 بیتی باید تنظیم شود. تفاوت در این است که داده های کدگذاری شده با endianness متفاوت کدگذاری می شوند. در هر دو نسخه 4 و 5، پیشوندهای هش 32 بیتی به صورت واژگانی مرتب شده اند. اما در v4، آن پیشوندها هنگام مرتب‌سازی به‌عنوان اندیان کوچک در نظر گرفته می‌شوند، در حالی که در v5 آن پیشوندها هنگام مرتب‌سازی به عنوان اندیان بزرگ در نظر گرفته می‌شوند. این بدان معناست که مشتری نیازی به مرتب سازی ندارد، زیرا مرتب سازی واژگانی با مرتب سازی عددی با اندیان بزرگ یکسان است. نمونه‌ای از این نوع در اجرای Chromium نسخه 4 را می‌توانید در اینجا پیدا کنید. چنین مرتب سازی را می توان حذف کرد.
- الگوریتم رمزگشایی Rice باید برای سایر طول های هش نیز پیاده سازی شود.
تبدیل جستجوهای هش
در نسخه 4، از روش fullHashes.find برای بدست آوردن هش کامل استفاده می شود. روش معادل در v5 روش hash.search است.
تغییرات زیر باید در درخواست ایجاد شود:
- ساختار کد را طوری تنظیم کنید که فقط پیشوندهای هش که دقیقاً 4 بایت طول دارند ارسال کند.
- اشیاء v4
ClientInfo را به طور کامل حذف کنید. به جای ارائه شناسه مشتری با استفاده از یک فیلد اختصاصی، به سادگی از هدر معروف User-Agent استفاده کنید. در حالی که هیچ فرمت مشخصی برای ارائه شناسه مشتری در این هدر وجود ندارد، پیشنهاد می کنیم به سادگی شناسه مشتری اصلی و نسخه مشتری را که با یک نویسه فاصله یا یک کاراکتر اسلش از هم جدا شده اند، اضافه کنید. - قسمت
client_states را حذف کنید. دیگر لازم نیست. - دیگر نیازی به وارد کردن
threat_types و فیلدهای مشابه نیست.
تغییرات زیر باید در پاسخ ایجاد شود:
- قسمت
minimum_wait_duration حذف شده است. مشتری همیشه می تواند بر اساس نیاز درخواست جدیدی صادر کند. - شی v4
ThreatMatch به شی FullHash ساده شده است. - ذخیره سازی به یک مدت زمان کش ساده شده است. رویه های بالا را برای تعامل با حافظه پنهان ببینید.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین به‌روزرسانی 2025-08-08 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین به‌روزرسانی 2025-08-08 بهوقت ساعت هماهنگ جهانی."],[],[],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."]]
