Migration From V4
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
שיפור משמעותי אחד בגרסה 5 של הגלישה הבטוחה של Google לעומת גרסה 4 (במיוחד ה-API של עדכון גרסה 4) הוא עדכניות הנתונים והכיסוי שלהם. מכיוון שההגנה תלויה מאוד במסד הנתונים המקומי שמתוחזק על ידי הלקוח, העיכוב והגודל של עדכון מסד הנתונים המקומי הם הגורמים העיקריים לכך שההגנה לא פעלה. בגרסה 4, בדרך כלל לוקח ללקוח 20 עד 50 דקות לקבל את הגרסה העדכנית ביותר של רשימות האיומים. לצערנו, התקפות פישינג מתפשטות במהירות: נכון לשנת 2021, 60% מהאתרים שמבצעים התקפות פעילים פחות מ-10 דקות. הניתוח שלנו מראה שכ-25% עד 30% מההגנה החסרה מפני פישינג נובעת מנתונים לא עדכניים כאלה. בנוסף, חלק מהמכשירים לא מצוידים לנהל את כל רשימות האיומים של הגלישה הבטוחה של Google, שממשיכות לגדול עם הזמן.
אם אתם משתמשים כרגע ב-v4 Update API, יש דרך חלקה לעבור מגרסה 4 לגרסה 5 בלי לאפס או למחוק את מסד הנתונים המקומי. בקטע הזה מוסבר איך עושים את זה.
המרת עדכוני רשימה
בגרסה 4, הרשימות מזוהות על ידי הטופל של סוג האיום, סוג הפלטפורמה וסוג רשומת האיום. בגרסה 5, הרשימות מזוהות פשוט לפי שם. הגמישות הזו שימושית במקרים שבהם כמה רשימות בגרסה 5 חולקות את אותו סוג איום. סוגי הפלטפורמות וסוגי רשומות האיומים הוסרו בגרסה 5.
בגרסה 4, משתמשים ב-threatListUpdates.fetch method כדי להוריד רשימות. בגרסה 5, צריך לעבור אל השיטה hashLists.batchGet.
צריך לבצע את השינויים הבאים בבקשה:
- מסירים את האובייקט
ClientInfo v4 לגמרי. במקום לספק את זיהוי הלקוח באמצעות שדה ייעודי, פשוט משתמשים בכותרת User-Agent המוכרת. אין פורמט מוגדר לאספקת זיהוי הלקוח בכותרת הזו, אבל אנחנו מציעים לכלול רק את מזהה הלקוח המקורי ואת גרסת הלקוח, כשהם מופרדים באמצעות רווח או לוכסן.
- לכל אובייקט
ListUpdateRequest בגרסה 4:
- מחפשים את שם הרשימה התואם בגרסה 5 מתוך הרשימות הזמינות ומזינים את השם הזה בבקשה בגרסה 5.
- מסירים שדות מיותרים כמו
threat_entry_type או platform_type.
- השדה
state בגרסה 4 תואם ישירות לשדה versions בגרסה 5. אפשר לשלוח בגרסה 5 את אותה מחרוזת בייטים שנשלחה לשרת באמצעות השדה state בגרסה 4, פשוט באמצעות השדה versions.
- בגרסה 5, האילוצים של גרסה 4 מופיעים בגרסה פשוטה יותר שנקראת
SizeConstraints. צריך להסיר שדות נוספים כמו region.
צריך לבצע את השינויים הבאים בתשובה:
- ה-enum
ResponseType בגרסה 4 פשוט מוחלף בשדה בוליאני בשם partial_update.
- השדה
minimum_wait_duration יכול להיות עכשיו אפס או מושמט. אם כן, הלקוח מתבקש לשלוח בקשה נוספת באופן מיידי. המצב הזה קורה רק כשהלקוח מציין ב-SizeConstraints מגבלה קטנה יותר על גודל העדכון המקסימלי מאשר גודל מסד הנתונים המקסימלי.
- צריך להתאים את אלגוריתם הפענוח של Rice למספרים שלמים בני 32 ביט. ההבדל הוא שהנתונים המקודדים מקודדים עם סדר בתים שונה. גם בגרסה 4 וגם בגרסה 5, קידומות הגיבוב (hash) של 32 ביט ממוינות בסדר לקסיקוגרפי. אבל בגרסה 4, הקידומות האלה נחשבות כ-little endian כשממיינים אותן, ואילו בגרסה 5 הן נחשבות כ-big endian כשממיינים אותן. המשמעות היא שהלקוח לא צריך לבצע מיון, כי מיון לקסיקוגרפי זהה למיון מספרי עם big endian. דוגמה לסוג כזה בהטמעה של v4 ב-Chromium מופיעה כאן. אפשר להסיר את המיון הזה.
- יהיה צורך להטמיע את אלגוריתם הפענוח של Rice גם עבור אורכי גיבוב אחרים.
המרת חיפושי גיבוב (Hash)
בגרסה 4, משתמשים בשיטה fullHashes.find כדי לקבל גיבובים מלאים. השיטה המקבילה בגרסה 5 היא השיטה hashes.search.
צריך לבצע את השינויים הבאים בבקשה:
- צריך לבנות את הקוד כך שישלח רק קידומות של גיבוב באורך של 4 בייטים בדיוק.
- להסיר את האובייקטים של גרסה 4
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 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-10 (שעון UTC)."],[],[],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."]]
