Migration From V4
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google 세이프 브라우징 v5가 v4 (특히 v4 업데이트 API)에 비해 크게 개선된 점은 데이터의 최신성과 적용 범위입니다. 보호는 클라이언트에서 유지관리하는 로컬 데이터베이스에 크게 의존하므로 로컬 데이터베이스 업데이트의 지연과 크기가 보호 누락의 주요 원인입니다. v4에서 일반적인 클라이언트는 최신 버전의 위협 목록을 가져오는 데 20~50분이 걸립니다. 안타깝게도 피싱 공격은 빠르게 확산됩니다. 2021년 기준으로 공격을 전달하는 사이트의 60% 가 10분 미만으로 운영됩니다. Google 분석에 따르면 누락된 피싱 방지 기능의 약 25~30% 가 이러한 데이터의 오래됨으로 인해 발생합니다. 또한 일부 기기는 시간이 지남에 따라 계속 커지는 Google 세이프 브라우징 위협 목록 전체를 관리할 수 없습니다.
현재 v4 업데이트 API를 사용 중인 경우 로컬 데이터베이스를 재설정하거나 삭제하지 않고도 v4에서 v5로 원활하게 이전할 수 있습니다. 이 섹션에서는 이를 수행하는 방법을 설명합니다.
목록 업데이트 변환
위협 유형, 플랫폼 유형, 위협 항목 유형의 튜플로 목록을 식별하는 V4와 달리 v5에서는 이름으로 목록을 식별합니다. 이렇게 하면 여러 v5 목록이 동일한 위협 유형을 공유할 수 있는 경우 유연성을 제공합니다. 플랫폼 유형과 위협 항목 유형이 v5에서 삭제됩니다.
v4에서는 threatListUpdates.fetch 메서드를 사용하여 목록을 다운로드합니다. v5에서는 hashLists.batchGet 메서드로 전환합니다.
요청을 다음과 같이 변경해야 합니다.
- v4
ClientInfo 객체를 완전히 삭제합니다. 전용 필드를 사용하여 클라이언트의 식별자를 제공하는 대신 잘 알려진 User-Agent 헤더를 사용하면 됩니다. 이 헤더에 클라이언트 식별자를 제공하는 데 정해진 형식은 없지만, 공백 문자나 슬래시 문자로 구분된 원래 클라이언트 ID와 클라이언트 버전을 포함하는 것이 좋습니다.
- 각 v4
ListUpdateRequest 객체의 경우:
- 사용 가능한 목록에서 해당 v5 목록 이름을 조회하고 v5 요청에 해당 이름을 제공합니다.
threat_entry_type 또는 platform_type과 같은 불필요한 필드를 삭제합니다.- v4의
state 필드는 v5 versions 필드와 직접 호환됩니다. v4에서 state 필드를 사용하여 서버에 전송되는 것과 동일한 바이트 문자열을 v5에서 versions 필드를 사용하여 전송하면 됩니다.
- v4 제약 조건의 경우 v5에서는
SizeConstraints라는 간소화된 버전을 사용합니다. region과 같은 추가 필드는 삭제해야 합니다.
대답을 다음과 같이 변경해야 합니다.
- v4 enum
ResponseType은 partial_update라는 불리언 필드로 대체됩니다.
- 이제
minimum_wait_duration 필드를 0으로 설정하거나 생략할 수 있습니다. 이 경우 클라이언트에게 즉시 다른 요청을 제출하도록 요청합니다. 이는 클라이언트가 SizeConstraints에서 최대 데이터베이스 크기보다 작은 최대 업데이트 크기 제약 조건을 지정한 경우에만 발생합니다.
- 32비트 정수의 Rice 디코딩 알고리즘을 조정해야 합니다. 차이점은 인코딩된 데이터가 다른 엔디언으로 인코딩된다는 것입니다. v4와 v5 모두에서 32비트 해시 접두사는 사전순으로 정렬됩니다. 하지만 v4에서는 이러한 접두사가 정렬될 때 리틀 엔디언으로 처리되는 반면 v5에서는 이러한 접두사가 정렬될 때 빅 엔디언으로 처리됩니다. 렉시코그래픽 정렬은 빅엔디안을 사용한 숫자 정렬과 동일하므로 클라이언트에서 정렬을 수행할 필요가 없습니다. Chromium v4 구현의 이러한 정렬 예는 여기에서 확인할 수 있습니다. 이러한 정렬은 삭제할 수 있습니다.
- Rice 디코딩 알고리즘은 다른 해시 길이에도 구현해야 합니다.
해시 검색 변환
v4에서는 fullHashes.find 메서드를 사용하여 전체 해시를 가져옵니다. v5의 해당 메서드는 hashes.search 메서드입니다.
요청을 다음과 같이 변경해야 합니다.
- 길이가 정확히 4바이트인 해시 접두사만 전송하도록 코드를 구성합니다.
- v4
ClientInfo 객체를 완전히 삭제합니다. 전용 필드를 사용하여 클라이언트의 식별자를 제공하는 대신 잘 알려진 User-Agent 헤더를 사용하면 됩니다. 이 헤더에 클라이언트 식별자를 제공하는 데 정해진 형식은 없지만, 공백 문자나 슬래시 문자로 구분된 원래 클라이언트 ID와 클라이언트 버전을 포함하는 것이 좋습니다.
client_states 필드를 삭제합니다. 더 이상 필요하지 않습니다.threat_types 및 유사한 필드를 포함할 필요가 없습니다.
대답을 다음과 같이 변경해야 합니다.
minimum_wait_duration 필드가 삭제되었습니다. 클라이언트는 필요에 따라 언제든지 새 요청을 발행할 수 있습니다.- v4
ThreatMatch 객체가 FullHash 객체로 간소화되었습니다.
- 캐싱이 단일 캐시 기간으로 단순화되었습니다. 캐시와 상호작용하는 방법은 위의 절차를 참고하세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 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."]]
