기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# AWS SDK for Go v2를 AWS 서비스와 함께 사용
<a name="use-services"></a>

 AWS 서비스를 직접적으로 호출하려면 먼저 서비스 클라이언트 인스턴스를 구성해야 합니다. 서비스 클라이언트는 해당 서비스의 모든 API 작업에 대한 하위 수준의 액세스를 제공합니다. 예를 들어 Amazon S3 API 직접 호출을 수행하기 위해 Amazon S3 서비스 클라이언트를 생성합니다.

 서비스 작업을 직접 호출할 때 입력 파라미터를 구조체로 전달합니다. 직접 호출이 성공하면 서비스 API 응답이 포함된 출력 구조체가 생성됩니다. 예를 들어 Amazon S3 버킷 생성 작업을 성공적으로 직접 호출한 후 작업은 버킷의 위치와 함께 출력 구조체를 반환합니다.

 메서드 및 파라미터를 포함한 서비스 클라이언트 목록은 [AWS SDK for Go API 참조](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2)를 참조하세요.

# 체크섬을 통한 데이터 무결성 보호
<a name="s3-checksums"></a>

Amazon Simple Storage Service(S3)는 객체를 업로드할 때 체크섬을 지정하는 기능을 제공합니다. 체크섬을 지정하면 객체와 함께 저장되며 객체를 다운로드할 때 유효성을 검사할 수 있습니다.

체크섬은 파일을 전송할 때 데이터 무결성을 한층 더 강화합니다. 체크섬을 사용하면 수신된 파일이 원본 파일과 일치하는지 확인하여 데이터 일관성을 확인할 수 있습니다. Amazon S3의 체크섬에 대한 자세한 내용은 [지원되는 알고리즘](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html#using-additional-checksums)이 포함된 [Amazon Simple Storage Service 사용 설명서](https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html)를 참조하세요.

필요에 가장 적합한 알고리즘을 유연하게 선택하고 SDK가 체크섬을 계산하도록 할 수 있습니다. 또는 지원되는 알고리즘 중 하나를 사용하여 미리 계산된 체크섬 값을 제공할 수 있습니다.

**참고**  
[Amazon S3 모듈의 버전 v1.74.1](https://github.com/aws/aws-sdk-go-v2/blob/v1.34.0/service/s3/CHANGELOG.md#v1741-2025-01-24)부터 SDK는 업로드에 대한 `CRC32` 체크섬을 자동으로 계산하여 기본 무결성 보호를 제공합니다. 사전 계산된 체크섬 값을 제공하지 않거나 SDK가 체크섬을 계산하는 데 사용해야 하는 알고리즘을 지정하지 않은 경우 SDK는 이 체크섬을 계산합니다.  
또한 SDK는 외부에서 설정할 수 있는 데이터 무결성 보호에 대한 전역 설정을 제공하며, 이에 대한 자세한 내용은 [AWS SDK 및 도구 참조 안내서](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html)에서 확인할 수 있습니다.

체크섬은 객체 업로드와 객체 다운로드라는 두 가지 요청 단계로 설명합니다.

## 객체 업로드
<a name="use-service-S3-checksum-upload"></a>

`putObject` 메서드를 사용하여 객체를 업로드하고 체크섬 알고리즘을 제공하면 SDK는 지정된 알고리즘에 대한 체크섬을 계산합니다.

다음 코드 스니펫은 `CRC32` 체크섬을 포함하여 객체를 업로드하라는 요청을 보여줍니다. SDK는 요청을 보낼 때 `CRC32` 체크섬을 계산하고 객체를 업로드합니다. Amazon S3는 체크섬을 계산하고 SDK에서 제공하는 체크섬과 비교하여 콘텐츠의 무결성을 검증합니다. 그런 다음 Amazon S3는 객체와 함께 체크섬을 저장합니다.

```
out, err := s3Client.PutObject(context.Background(), &s3.PutObjectInput{
     Bucket:            aws.String("bucket"),
     Key:               aws.String("key"),
     ChecksumAlgorithm: types.ChecksumAlgorithmCrc32,
     Body:              strings.NewReader("Hello World"),
 })
```

요청 시 체크섬 알고리즘을 제공하지 않으면 다음 표에 표시된 대로 사용 중인 SDK 버전에 따라 체크섬 동작이 달라집니다.

**체크섬 알고리즘이 제공되지 않은 경우 체크섬 동작**


| AWS SDK for Go의 Amazon S3 모듈 버전 | 체크섬 동작 | 
| --- | --- | 
| v1.74.1 이하 | SDK에서 CRC 기반 체크섬을 자동으로 계산해서 요청에 제공하지 않습니다. | 
| v1.74.1 이상 |  SDK에서 `CRC32` 알고리즘을 사용하여 체크섬을 계산하고 요청에 제공합니다. Amazon S3는 자체 `CRC32` 체크섬을 계산하여 전송의 무결성을 검증하고 이를 SDK에서 제공하는 체크섬과 비교합니다. 체크섬이 일치하면 체크섬이 객체와 함께 저장됩니다.  | 

### 미리 계산된 체크섬 값 사용
<a name="use-service-S3-checksum-upload-pre"></a>

요청과 함께 제공되는 사전 계산된 체크섬 값은 SDK의 자동 계산을 비활성화하고 제공된 값을 대신 사용합니다.

다음 예제는 사전 계산된 SHA256 체크섬을 포함하는 요청을 보여줍니다.

```
out, err := s3Client.PutObject(context.Background(), &s3.PutObjectInput{
     Bucket:        aws.String("bucket"),
     Key:           aws.String("key"),
     ChecksumCRC32: aws.String("checksumvalue"),
     Body:          strings.NewReader("Hello World"),
 })
```

Amazon S3에서 체크섬 값이 지정된 알고리즘에 대해 올바르지 않다고 판단하면 서비스는 오류 응답을 반환합니다.

### 멀티파트 업로드
<a name="use-service-S3-checksum-upload-multi"></a>

멀티파트 업로드에 체크섬을 사용할 수도 있습니다.

 AWS SDK for Go는 멀티파트 업로드와 함께 체크섬을 사용할 수 있는 두 가지 옵션을 제공합니다. 첫 번째 옵션은 업로드용 `CRC32` 알고리즘을 지정하는 전송 관리자를 사용합니다.

```
s3Client := s3.NewFromConfig(cfg)
     transferManager := manager.NewUploader(s3Client)
     out, err := transferManager.Upload(context.Background(), &s3.PutObjectInput{
             Bucket:            aws.String("bucket"),
             Key:               aws.String("key"),
             Body:              large file to trigger multipart upload,
             ChecksumAlgorithm: types.ChecksumAlgorithmCrc32,
     })
```

전송 관리자를 사용하여 업로드할 때 체크섬 알고리즘을 제공하지 않으면 SDK는 `CRC32` 알고리즘을 기반으로 체크섬을 자동으로 계산합니다. SDK는 모든 버전의 SDK에 대해 이 계산을 수행합니다.

두 번째 옵션은 [Amazon S3](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3) 클라이언트를 사용하여 멀티파트 업로드를 수행합니다. 이 접근법으로 추가 체크섬을 지정하는 경우 업로드를 시작할 때 사용할 알고리즘을 지정해야 합니다. 또한 각 파트 요청에 대한 알고리즘을 지정하고 업로드 후 각 파트에 대해 계산된 체크섬을 제공해야 합니다.

```
s3Client := s3.NewFromConfig(cfg)
     createMultipartUploadOutput, err := s3Client.CreateMultipartUpload(context.Background(), &s3.CreateMultipartUploadInput{
             Bucket:            aws.String("bucket"),
             Key:               aws.String("key"),
             ChecksumAlgorithm: types.ChecksumAlgorithmCrc32,
          })
     if err != nil {
             log.Fatal("err create multipart upload ", err)
     }

     var partsBody []io.Reader // this is just an example parts content, you should load your target file in your code
     partNum := int32(1)
     var completedParts []types.CompletedPart
     for _, body := range partsBody {
         uploadPartOutput, err := s3Client.UploadPart(context.Background(), &s3.UploadPartInput{
             Bucket:            aws.String("bucket"),
             Key:               aws.String("key"),
             ChecksumAlgorithm: types.ChecksumAlgorithmCrc32,
             Body:              body,
             PartNumber:        aws.Int32(partNum),
             UploadId:          createMultipartUploadOutput.UploadId,
         })
         if err != nil {
             log.Fatal("err upload part ", err)
         }

         completedParts = append(completedParts, types.CompletedPart{
             PartNumber:    aws.Int32(partNum),
             ETag:          uploadPartOutput.ETag,
             ChecksumCRC32: uploadPartOutput.ChecksumCRC32,
         })
         partNum++
     }

     completeMultipartUploadOutput, err := s3Client.CompleteMultipartUpload(context.Background(), &s3.CompleteMultipartUploadInput{
         Bucket:   aws.String("bucket"),
         Key:      aws.String("key"),
         UploadId: createMultipartUploadOutput.UploadId,
         MultipartUpload: &types.CompletedMultipartUpload{
             Parts: completedParts,
         },
     })
     if err != nil {
         log.Fatal("err complete multipart upload ", err)
     }
```

## 객체 다운로드
<a name="use-service-S3-checksum-download"></a>

[GetObject](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.GetObject) 메서드를 사용하여 객체를 다운로드하면 `GetObjectInput`의 `ChecksumMode` 필드가 `types.ChecksumModeEnabled`로 설정될 때 SDK가 체크섬을 자동으로 검증합니다.

다음 스니펫의 요청은 체크섬을 계산하고 값을 비교하여 응답의 체크섬을 검증하도록 SDK에 지시합니다.

```
out, err := s3Client.GetObject(context.Background(), &s3.GetObjectInput{
     Bucket:       aws.String("bucket"),
     Key:          aws.String("key"),
     ChecksumMode: types.ChecksumModeEnabled,
 })
```

체크섬과 함께 객체를 업로드하지 않은 경우 검증이 수행되지 않습니다.