로컬 데이터베이스
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서는 Update API (v4): threatListUpdates.fetch 메서드에 적용됩니다.
데이터베이스 설정
Update API를 사용하는 클라이언트는 로컬 데이터베이스를 설정하고 작업할 세이프 브라우징 목록을 처음 다운로드해야 합니다. 시작하려면 safebrowsing Go 패키지를 빌드 및 배포하거나 이 패키지를 사용하여 자체 구현을 모델링하면 됩니다. 자세한 내용은 https://github.com/google/safebrowsing/을 참조하세요.
데이터베이스 업데이트
최신 위협으로부터 보호하기 위해 클라이언트는
threatListUpdates.fetch 메서드를 사용하여 로컬 세이프 브라우징 목록을 정기적으로 업데이트하는 것이 좋습니다.
threatListUpdates.fetch request는 업데이트할 목록을 지정합니다. 클라이언트에 메모리 또는 대역폭 제한이 있으면 요청을 사용하여 업데이트 제약조건을 설정할 수도 있습니다 (
제약조건 업데이트 참고).
threatListUpdates.fetch 응답은 아래 설명처럼 각 목록의 전체 업데이트 또는 부분 업데이트를 반환합니다.
전체 업데이트
클라이언트가 threatListUpdates.fetch 요청의 state 필드를 비워 두거나 서버에서 전체 업데이트가 필요하다고 판단하면 전체 업데이트가 반환됩니다. 전체 업데이트의 경우 추가만 반환됩니다. 클라이언트는 업데이트를 적용하고 유효성 검사를 실행하기 전에 로컬 데이터베이스를 삭제해야 합니다.
빈 상태
클라이언트가 목록의 초기 요청을 보내면 전체 업데이트가 반환됩니다. 이 경우 요청의 state 필드는 비어 있게 되고 (제공할 값이 없으므로) 응답의 newClientState 필드는 로컬 목록의 초기 상태를 반환합니다. 클라이언트가 후속 요청에서 state 필드를 의도적으로 비워 두는 경우에도 전체 업데이트가 반환됩니다. 이렇게 하면 전체 업데이트가 강제 실행되고 응답의 newClientState 필드에 새로운 상태가 반환됩니다.
서버 결정
클라이언트가 부분 업데이트만 요청한 경우 세이프 브라우징 서버에서 전체 업데이트를 반환하는 경우가 있습니다. 클라이언트가 처음에 작은 버전의 목록을 다운로드한 후 더 큰 버전의 목록으로 업데이트할 때 이러한 상황이 발생할 수 있습니다. 서버는 전체 목록의 전체 업데이트를 반환합니다. 클라이언트가 장시간 데이터를 다운로드하지 않고 부분 업데이트를 요청하는 경우에도 이 문제가 발생할 수 있습니다. 마찬가지로 서버는 단순히 전체 목록이 포함된 전체 업데이트를 반환합니다.
부분 업데이트
클라이언트가 threatListUpdates.fetch 요청에서 state 필드에 값을 제공하면 부분 업데이트가 반환됩니다(위에서 언급한 바와 같이 서버에서 전체 업데이트가 필요하다고 판단하는 경우는 예외임). 부분 업데이트의 경우 추가 및 삭제가 모두 반환됩니다. 클라이언트는 로컬 데이터베이스의 목록을 업데이트 (추가하기 전에 삭제 적용)한 후 유효성 검사를 수행합니다.
추가
추가는 로컬 데이터베이스에 추가해야 하는 SHA256 해시 프리픽스입니다. 해시 프리픽스의 대부분은 길이가 4바이트이지만 일부 해시 프리픽스의 길이는 4~32바이트일 수 있습니다.
따라서 여러 개의 덧셈 세트가 반환될 수 있습니다. 예를 들어 하나는 4바이트 프리픽스를 포함하고 다른 하나는 5바이트 프리픽스를 포함합니다.
클라이언트가 압축을 지원하는 경우 Rice 압축을 사용하여 응답을 압축할 수 있습니다. 그러나 4바이트 해시 프리픽스만 압축됩니다. 긴 해시 프리픽스는 항상 압축되지 않은 원시 형식으로 전송됩니다 (압축 참고).
이사
삭제는 사전순으로 정렬된 클라이언트 데이터베이스에서 로컬 데이터베이스에서 삭제해야 하는 항목을 가리키는 0 기반 색인입니다. 하나의 삭제 집합만 반환됩니다.
클라이언트가 압축을 지원하는 경우 '쌀 해시' 및 '라이 색인'이 반환됩니다. 압축이 지원되지 않으면 '원시 해시' 및 '원시 색인'이 반환됩니다 (압축 참고).
유효성 검사 확인
전체 업데이트 또는 부분 업데이트와 함께 threatListUpdates.fetch 응답이 반환되면 클라이언트가 유효성 검사를 수행해야 합니다.
클라이언트는 먼저 로컬 데이터베이스의 목록을 업데이트합니다 (추가하기 전에 삭제 적용). 그런 다음 클라이언트는 사전순으로 정렬된 로컬 목록의 SHA256 해시를 계산하고 응답에 반환된 체크섬과 비교합니다.
두 값이 같으면 세이프 브라우징 목록이 '올바른' 것으로 간주됩니다.
두 값이 같지 않으면 세이프 브라우징 목록이 '손상된' 것으로 간주됩니다. 클라이언트는 데이터베이스에서 목록을 지우고 state 필드가 빈 문자열로 설정된 두 번째 업데이트를 다시 실행해야 합니다. 이렇게 하면 전체가 강제로 업데이트되고 완전히 새로운 목록과 상태가 반환됩니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-25(UTC)
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-25(UTC)"],[[["\u003cp\u003eThe Safe Browsing Update API (v4) allows clients to download and update local Safe Browsing lists for threat detection.\u003c/p\u003e\n"],["\u003cp\u003eClients need to set up a local database and perform an initial download of the desired Safe Browsing lists.\u003c/p\u003e\n"],["\u003cp\u003eRegular updates are crucial, and can be either full (requiring a local database clear) or partial (applying additions and removals).\u003c/p\u003e\n"],["\u003cp\u003eValidation checks using SHA256 hashes ensure the integrity of the local Safe Browsing lists after each update.\u003c/p\u003e\n"],["\u003cp\u003eIf validation fails, clients should clear the local list and request a full update to obtain a fresh copy.\u003c/p\u003e\n"]]],["Clients utilizing the Update API must establish a local database and download Safe Browsing lists. Regular updates are crucial via the `threatListUpdates.fetch` method, specifying desired lists and update constraints. The server responds with either full updates (client clears database and applies additions) or partial updates (client applies removals before additions). After each update, the local database's SHA256 hash is validated against the response checksum; mismatches trigger a full update.\n"],null,["# Local Databases\n\nThis document applies to the following method:\n[Update API (v4)](/safe-browsing/v4/update-api):\n[threatListUpdates.fetch](/safe-browsing/v4/update-api#example-threatListUpdatesfetch).\n\nDatabase setup\n--------------\n\nClients using the Update API are required to set up a local database and to perform an initial\ndownload of the Safe Browsing lists they want to work with. To get going, you can build and deploy\nthe `safebrowsing` Go package (or use the package to model your own implementation). For more information\nsee \u003chttps://github.com/google/safebrowsing/\u003e.\n\nDatabase updates\n----------------\n\nTo ensure protection against the latest threats, clients are strongly encouraged to regularly update their local Safe Browsing lists using the [threatListUpdates.fetch](/safe-browsing/reference/rest/v4/threatListUpdates/fetch) method. The [threatListUpdates.fetch request](/safe-browsing/v4/update-api#http-post-request) specifies the lists to be updated. If clients have memory or bandwidth limitations, they can also use the request to set update constraints (see [Update Constraints](/safe-browsing/v4/update-constraints)). The [threatListUpdates.fetch response](/safe-browsing/v4/update-api#http-post-response) returns either a full update or partial update for each list, as explained below.\n\n\u003cbr /\u003e\n\n### Full updates\n\nFull updates are returned when the client leaves the `state` field in the\n[threatListUpdates.fetch request](/safe-browsing/v4/update-api#http-post-request)\nempty or when the server determines a full update is required. For full updates, only\n[additions](/safe-browsing/v4/local-databases#additions) are returned. The client is\nexpected to *clear the local database* before applying the updates and performing the\n[validation check](/safe-browsing/v4/local-databases#validation-checks).\n**Empty state**\n\nFull updates are returned when the client sends the initial request for a list. In this case, the\n`state` field in the request is left empty (because there is no value to provide) and the `newClientState`\nfield in the response returns the initial state for the local list. Full updates are also returned\nwhen the client purposely leaves the `state` field empty on subsequent requests. This will force a full\nupdate and return a new state in the `newClientState` field of the response.\n**Server decision**\n\nOccasionally, the Safe Browsing server returns a full update when only a partial update\nwas requested by the client. This may happen when the client initially downloads a small version of the list\nand then updates to a larger version of the list; the server will simply return a full update with\nthe entire list. This may also happen if the client hasn't downloaded data in a long time and requests\na partial update; again, the server will simply return a full update with the entire list.\n\n### Partial updates\n\nPartial updates are returned when the client supplies a value for the `state` field in the\n[threatListUpdates.fetch request](/safe-browsing/v4/update-api#http-post-request)\n(the exception, as noted above, is when the server determines a full update is required). For\npartial updates, both [additions](/safe-browsing/v4/local-databases#additions) and\n[removals](/safe-browsing/v4/local-databases#removals) are returned. The client updates\nthe lists in the local database (applying the removals before the additions) and then performs the\n[validation check](/safe-browsing/v4/local-databases#validation-checks).\n\n### Additions\n\nAdditions are SHA256 hash prefixes that should be added to the local database. The vast majority\nof hash prefixes are 4 bytes long but some hash prefixes may have any length between 4 and 32 bytes.\nTherefore, multiple sets of additions could be returned; for example, one containing the 4-byte prefixes\nand one containing 5-byte prefixes.\n\nIf the client supports compression, the response may be compressed using Rice compression. However,\nonly 4-byte hash prefixes get compressed. Longer hash prefixes are always sent in uncompressed, raw\nformat (see [Compression](/safe-browsing/v4/compression)).\n\n### Removals\n\nRemovals are zero-based indices in the lexicographically-sorted client database pointing at entries\nthat should be removed from the local database. Only one set of removals will be returned.\n\nIf the client supports compression, \"rice hashes\" and \"rice indices\" are returned. If compression\nis not supported, \"raw hashes\" and \"raw indices\" are returned (see\n[Compression](/safe-browsing/v4/compression)).\n\nValidation checks\n-----------------\n\nWhen the [threatListUpdates.fetch response](/safe-browsing/v4/update-api#http-post-response)\nis returned---with either a full update or a partial update---the client is expected to perform a\nvalidation check.\n\nThe client first updates the lists in the local database (applying the removals before the\nadditions). The client then computes the SHA256 hash of the\n(lexicographically sorted) local list and compares it to the checksum returned in the response.\nIf the two values are equal, the Safe Browsing list is considered \"correct.\"\n\nIf the two values are not equal, the Safe Browsing list is considered \"corrupt.\" The client must\nclear the list from the database and reissue a second update with the `state` field set\nto the empty string; this will force a full update and return a brand new list and state."]]
