Cloud Storage는 버킷에서 그리고 버킷으로 전송되는 데이터의 유효성을 검사하도록 권장합니다. 이 페이지에서는 CRC32C 또는 MD5 체크섬을 사용하여 유효성 검사 수행에 대한 권장사항과 gcloud storage rsync 명령어에서 사용하는 변경 감지 알고리즘을 설명합니다.
해시를 사용하여 데이터 손상 방지
Cloud에서 업로드 또는 다운로드하는 동안 데이터가 여러 가지 이유로 손상될 수 있습니다.
클라이언트나 서버 컴퓨터, 또는 경로상에 있는 라우터에서의 메모리 오류
소프트웨어 버그(예: 고객이 사용하는 라이브러리에서)
장기간에 걸쳐 업로드가 발생하면 소스 파일이 변경됩니다.
Cloud Storage에서는 데이터 무결성 확인을 위해 사용할 수 있는 CRC32C 및 MD5라는 두 가지 해시 유형이 지원됩니다. CRC32C는 무결성 검사를 수행하는 데 권장되는 유효성 검사 방법입니다. MD5를 선호하는 고객은 해시를 사용할 수 있지만 MD5 해시는 모든 객체에 지원되지 않습니다.
클라이언트 측 유효성 검사
실시간으로 데이터를 해싱하고 결과를 서버 제공 체크섬과 비교하여 다운로드한 데이터에 무결성 검사를 수행할 수 있습니다. 그러나 서버 제공 체크섬은 Cloud Storage에 저장된 전체 객체를 기반으로 하므로 서버 제공 해시를 사용하여 다음 유형의 다운로드 유효성을 검사할 수 없습니다.
서버 제공 체크섬이 압축된 상태의 객체를 나타내는 반면, 제공된 데이터는 압축이 해제되어 결과적으로 다른 해시 값을 갖으므로 압축 해제 트랜스코딩을 거치는 다운로드
range 요청을 보낼 때 발생하는 객체 데이터 일부만 포함하는 응답. Cloud Storage에서는 마지막에 수신한 오프셋 이후 전체 객체 다운로드를 다시 시작하는 경우에만 범위 요청을 사용하는 것이 좋습니다. 이 경우 전체 다운로드가 완료되면 체크섬을 계산하고 유효성을 검사할 수 있기 때문입니다.
체크섬을 사용하여 다운로드 유효성을 검사할 수 있는 경우에는 잘못된 해시 값이 있는 다운로드 데이터를 삭제하고 권장 재시도 로직을 사용하여 요청을 재시도해야 합니다.
서버 측 유효성 검사
Cloud Storage는 다음과 같은 경우에 서버 측 유효성 검사를 수행합니다.
Cloud Storage 내에서 복사 또는 재작성 요청을 수행하는 경우
업로드 요청에서 객체의 예상 MD5 또는 CRC32C 해시를 제공할 경우
사용자가 제공한 해시가 Cloud Storage에서 계산하는 값과 일치하는 경우에만 Cloud Storage가 객체를 만듭니다. 일치하지 않으면 요청이 BadRequestException: 400 오류와 함께 거부됩니다.
또는 업로드된 객체의 메타데이터에 대한 요청을 실행하고 업로드된 객체의 해시 값을 예상 값과 비교한 후 일치하지 않는 경우 객체를 삭제하여 업로드의 클라이언트 측 유효성 검사를 수행할 수 있습니다. 이 방법은 업로드 시작 시 객체의 MD5 또는 CRC32C 해시를 알 수 없는 경우에 유용합니다.
동시 복합 업로드의 경우 사용자는 구성요소 업로드마다 무결성 검사를 수행한 후 구성 요청과 함께 사전 조건을 사용하여 경합 상태를 방지해야 합니다. 작성 요청에서는 서버 측 유효성 검사를 수행하지 않으므로 엔드 투 엔드 무결성 검사를 수행하려는 사용자는 새 복합 객체에서 클라이언트 측 유효성 검사를 수행해야 합니다.
Google Cloud CLI 유효성 검사
Google Cloud CLI의 경우 Cloud Storage 버킷에 대해 복사된 데이터가 검증됩니다. 이는 cp, mv, rsync 명령어에 적용됩니다. 소스 데이터의 체크섬이 대상 데이터의 체크섬과 일치하지 않으면 gcloud CLI가 잘못된 사본을 삭제하고 경고 메시지를 출력합니다.
이러한 일은 매우 드뭅니다. 실제로 발생하는 경우, 작업을 다시 시도해야 합니다.
객체 자체가 완료된 후 이 자동 검증이 수행되므로 잘못된 객체가 식별되고 삭제되기 전에 1~3초 동안 표시됩니다. 또한 업로드가 완료된 후 검증을 수행하기 전에 gcloud CLI가 중단되는 경우 잘못된 객체가 그대로 유지됩니다. --content-md5 플래그를 사용할 때 발생하는 서버 측 유효성 검사를 사용하여 단일 파일을 Cloud Storage에 업로드할 때 이러한 문제를 방지할 수 있습니다.
rsync 변경 감지
또한 gcloud storage rsync 명령어는 MD5 또는 CRC32C 체크섬을 사용하여 소스에서 찾은 객체의 버전과 대상에서 찾은 버전 간에 차이가 있는지 확인할 수도 있습니다. 이 명령어는 다음과 같은 경우에 체크섬을 비교합니다.
소스와 대상 모두 클라우드 버킷이고 객체의 두 버킷 모두에 MD5 또는 CRC32C 체크섬이 있습니다.
객체의 소스나 대상에는 파일 수정 시간(mtime)이 없습니다.
소스와 대상이 파일 시스템인 경우와 같이 관련 객체의 소스와 대상 모두에 mtime 값이 있으면 rsync 명령어는 체크섬을 사용하는 대신 객체 크기와 mtime을 비교합니다. 마찬가지로 소스가 클라우드 버킷이고 대상이 로컬 파일 시스템이면 rsync 명령어는 소스 객체에 생성된 시간을 mtime의 대안으로 사용하고 명령어는 체크섬을 사용하지 않습니다.
mtime 또는 체크섬을 사용할 수 없는 경우 rsync는 객체의 소스 버전과 대상 버전 간에 변경사항이 있는지 확인하는 경우에만 파일 크기를 비교합니다. 예를 들어 복합 객체를 CRC32C를 지원하지 않는 클라우드 제공업체의 객체와 비교하는 경우에는 mtime 또는 체크섬을 사용할 수 없습니다. 복합 객체에는 MD5가 없기 때문입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[],[],null,["# Data validation and change detection\n\nCloud Storage encourages you to validate the data you transfer\nto and from your buckets. This page describes best practices for performing\nvalidations using either [CRC32C or MD5 checksums](/storage/docs/metadata#checksums) and describes the change\ndetection algorithm used by the `gcloud storage rsync` command.\n\nProtect against data corruption by using hashes\n-----------------------------------------------\n\nThere are a variety of ways that data can be corrupted while uploading to or\ndownloading from the Cloud:\n\n- Memory errors on client or server computers, or routers along the path\n- Software bugs (e.g., in a library that customers use)\n- Changes to the source file when an upload occurs over an extended period of time\n\nCloud Storage supports two types of hashes you can use to check the integrity\nof your data: CRC32C and MD5. CRC32C is the recommended validation method\nfor performing integrity checks. Customers that prefer MD5 can use that hash,\nbut MD5 hashes are [not supported for all objects](/storage/docs/metadata#md5).\n\n### Client-side validation\n\nYou can perform a integrity check for downloaded data by hashing the data on the\nfly and comparing your results to the server-supplied checksums. Note, however,\nthat the server-supplied checksums are based on the complete object as it's\nstored in Cloud Storage, which means the following types of downloads\ncan't be validated using the server-supplied hashes:\n\n- Downloads which undergo [decompressive transcoding](/storage/docs/transcoding), because the\n server-supplied checksum represents the object in its compressed state, while\n the served data has compression removed and consequently a different hash\n value.\n\n- A response that contains only a [portion of the object data](/storage/docs/downloading-objects#downloading-an-object-portion), which occurs\n when making a `range` request. Cloud Storage recommends using range\n requests only for restarting the download of a full object after the last\n received offset, because in that case you can compute and validate the\n checksum when the full download completes.\n\nIn cases where you can validate the download using checksums, you should discard\ndownloaded data with incorrect hash values and use the\n[recommended retry logic](/storage/docs/retry-strategy) to retry the request.\n\n### Server-side validation\n\nCloud Storage performs server-side validation in the following cases:\n\n- When you perform a copy or rewrite request within Cloud Storage.\n\n- When supplying an object's expected MD5 or CRC32C hash in an upload request.\n Cloud Storage only creates the object if the hash you provide matches the\n value Cloud Storage calculates. If it does not match, the request is\n rejected with a `BadRequestException: 400` error.\n\n - In applicable JSON API requests, you supply checksums as part of the\n [objects resource](/storage/docs/json_api/v1/objects).\n\n - In applicable XML API requests, you supply checksums using the\n [`x-goog-hash` header](/storage/docs/xml-api/reference-headers#xgooghash). The XML API also accepts the standard HTTP\n [Content-MD5 header](/storage/docs/xml-api/reference-headers#contentmd5) (see the [specification](https://datatracker.ietf.org/doc/html/rfc1864#section-2)).\n\n - Alternatively, you can perform client-side validation of your uploads by\n issuing a request for the uploaded object's metadata, comparing the\n uploaded object's hash value to the expected value, and deleting the\n object in case of a mismatch. This method is useful if the object's MD5 or\n CRC32C hash isn't known at the start of the upload.\n\nIn the case of [parallel composite uploads](/storage/docs/parallel-composite-uploads), users should perform an\nintegrity check for each component upload and then use [preconditions](/storage/docs/request-preconditions) with\ntheir compose requests to protect against race conditions. Compose requests\ndon't perform server-side validation, so users who want an end-to-end integrity\ncheck should perform client-side validation on the new composite object.\n\n### Google Cloud CLI validation\n\nFor the [Google Cloud CLI](/sdk/gcloud/reference/storage), data copied to or from a Cloud Storage\nbucket is validated. This applies to `cp`, `mv`, and `rsync` commands. If the\nchecksum of the source data does not match the checksum of the destination data,\nthe gcloud CLI deletes the invalid copy and prints a warning message.\nThis very rarely happens. If it does, you should retry the operation.\n\nThis automatic validation occurs after the object itself is finalized, so\ninvalid objects are visible for 1-3 seconds before they're identified and\ndeleted. Additionally, there is a chance that the gcloud CLI could be\ninterrupted after the upload completes but before it performs the validation,\nleaving the invalid object in place. These issues can be avoided when uploading\nsingle files to Cloud Storage by using [server-side validation](#server-validation),\nwhich occurs when using the `--content-md5` flag.\n| **Note:** The `--content-md5` flag is ignored for [objects that don't have an MD5 hash](/storage/docs/metadata#md5).\n\nChange detection for `rsync`\n----------------------------\n\nThe [`gcloud storage rsync`](/sdk/gcloud/reference/storage/rsync) command can also use MD5 or CRC32C checksums to\ndetermine if there is a difference between the version of an object found at the\nsource and the version found at the destination. The command compares checksums\nin the following cases:\n\n- The source and destination are both cloud buckets and the object has an\n MD5 or CRC32C checksum in both buckets.\n\n- The object does not have a file modification time (`mtime`) in either the\n source or destination.\n\nIn cases where the relevant object has an `mtime` value in both the source and\ndestination, such as when the source and destination are file systems, the\n`rsync` command compares the objects' size and `mtime`, instead of using\nchecksums. Similarly, if the source is a cloud bucket and the destination is a\nlocal file system, the `rsync` command uses the time created for the source\nobject as a substitute for `mtime`, and the command does not use checksums.\n\nIf neither `mtime` nor checksums are available, `rsync` only compares file sizes\nwhen determining if there is a change between the source version of an object\nand the destination version. For example, neither `mtime` nor checksums are\navailable when comparing [composite objects](/storage/docs/composite-objects) with objects at a cloud provider\nthat doesn't support CRC32C, because composite objects don't have MD5 checksums.\n\nWhat's next\n-----------\n\n- Explore [upload and download options](/storage/docs/uploads-downloads) for Cloud Storage.\n- Learn about [retry strategies](/storage/docs/retry-strategy) for Cloud Storage."]]
