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

Amazon S3 유틸리티

Amazon S3 Transfer 관리자

Amazon S3 업로드 및 다운로드 관리자는 큰 객체를 분할할 수 있으므로 여러 부분으로 병렬로 전송할 수 있습니다. 이렇게 하면 중단된 전송을 쉽게 재개할 수 있습니다.

Amazon S3 업로드 관리자

Amazon S3 업로드 관리자는 파일을 더 작은 부분으로 분할하고 병렬로 업로드할 수 있는지 여부를 결정합니다. 병렬 업로드 수와 업로드된 파트의 크기를 사용자 지정할 수 있습니다.

다음 예제에서는 Amazon S3를 사용하여 파일을 Uploader 업로드합니다. 를 사용하는 Uploader 것은 s3.PutObject() 작업과 비슷합니다.

import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/feature/s3/manager"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Printf("error: %v", err)
    return
}

client := s3.NewFromConfig(cfg)

uploader := manager.NewUploader(client)
result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-object-key"),
    Body:   uploadFile,
})

구성 옵션

NewUploader를 사용하여 Uploader 인스턴스를 인스턴스화할 때 여러 구성 옵션을 지정하여 객체 업로드 방법을 사용자 지정할 수 있습니다. 옵션은에 하나 이상의 인수를 제공하여 재정의됩니다NewUploader. 이 옵션에는 다음이 포함됩니다.

Concurrency 값은 지정된 Upload 호출에 대해 발생할 수 있는 동시 파트 업로드 수를 제한합니다. 이는 글로벌 클라이언트 동시성 제한이 아닙니다. PartSize 및 Concurrency 구성 값을 조정하여 최적의 구성을 찾습니다. 예를 들어 대역폭이 높은 연결이 있는 시스템은 더 큰 부분과 더 많은 업로드를 병렬로 전송할 수 있습니다.

예를 들어 애플리케이션은 Concurrency의 설정Uploader으로를 구성합니다5. 애플리케이션이 서로 다른 두 개 구루틴Upload에서를 호출하면 10 동시 파트 업로드(구루틴 2개 * 5개Concurrency)가 발생합니다.

다음은 Uploader 생성 중에 기본 파트 크기를 설정하는 예제입니다.

uploader := manager.NewUploader(client, func(u *Uploader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

Uploader 및 구성에 대한 자세한 내용은 AWS SDK for Go API 참조의 업로더를 참조하세요.

PutObjectInput 본문 필드(io.ReadSeeker와 io.Reader 비교)

s3.PutObjectInput 구조체의 Body 필드는 io.Reader 유형입니다. 그러나이 필드는 호스트 환경의 애플리케이션 리소스 사용률을 개선하기 위해 io.ReadSeeker 및 io.ReaderAt 인터페이스를 모두 충족하는 유형으로 채울 수 있습니다. 다음 예제에서는 두 인터페이스를 ReadSeekerAt 모두 충족하는 유형을 생성합니다.

type ReadSeekerAt interface {
    io.ReadSeeker
    io.ReaderAt
}

io.Reader 유형의 경우 부분을 업로드하려면 먼저 리더의 바이트를 메모리에 버퍼링해야 합니다. PartSize 또는 Concurrency 값을 늘리면에 필요한 메모리(RAM)가 크게 Uploader 증가합니다. 필요한 메모리는 약 PartSize * 입니다Concurrency. 예를 들어에 100MBConcurrency를 지정PartSize하고에 10MB를 지정하려면 최소 1GB가 필요합니다.

io.Reader 유형은 바이트를 읽기 전에 크기를 결정할 수 없으므로 업로드할 파트 수를 계산할 수 Uploader 없습니다. 따라서를 PartSize 너무 낮게 설정하면 Uploader는 대용량 파일의 Amazon S3 업로드 한도인 10,000파트에 도달할 수 있습니다. 10,000개 이상의 파트를 업로드하려고 하면 업로드가 중지되고 오류가 반환됩니다.

ReadSeekerAt 유형을 구현하는 body 값의 경우는 Amazon S3로 전송하기 전에 본문 콘텐츠를 메모리에 버퍼링하지 Uploader 않습니다.는 파일을 Amazon S3에 업로드하기 전에 예상 부분 수를 Uploader 계산합니다. 의 현재 값에 파일을 업로드하는 데 10,000개 이상의 파트가 PartSize 필요한 경우는 필요한 파트 수가 적도록 파트 크기 값을 Uploader늘립니다.

실패한 업로드 처리

Amazon S3에 대한 업로드가 실패하면 기본적으로 Uploader는 Amazon S3 AbortMultipartUpload 작업을 사용하여 업로드된 부분을 제거합니다. 이 기능은 실패한 업로드가 Amazon S3 스토리지를 사용하지 않도록 합니다.

가 성공적으로 업로드된 부분을 삭제하지 않도록를 trueLeavePartsOnError로 설정할 수 Uploader 있습니다. 이는 부분적으로 완료된 업로드를 재개하는 데 유용합니다. 업로드된 파트에서 작동하려면 실패한 업로드UploadID의를 가져와야 합니다. 다음 예제에서는 manager.MultiUploadFailure 오류 인터페이스 유형을 사용하여를 가져오는 방법을 보여줍니다UploadID.

result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-object-key"),
    Body:   uploadFile,
})
output, err := u.upload(input)
if err != nil {
    var mu manager.MultiUploadFailure
    if errors.As(err, &mu) {
        // Process error and its associated uploadID
        fmt.Println("Error:", mu)
        _ = mu.UploadID() // retrieve the associated UploadID
    } else {
        // Process error generically
        fmt.Println("Error:", err.Error())
    }
    return
}

업로드당 업로더 옵션 재정의

메서드에 하나 이상의 인수Upload를 제공하여를 호출할 때 Uploader 옵션을 재정의할 수 있습니다. 이러한 재정의는 동시성에 안전한 수정 사항이며 진행 중인 업로드 또는 후속 관리자 Upload 호출에는 영향을 주지 않습니다. 예를 들어 특정 업로드 요청에 대한 PartSize 구성을 재정의하려면

params := &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-key"),
    Body:   myBody,
}
resp, err := uploader.Upload(context.TODO(), params, func(u *manager.Uploader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

예시

Amazon S3에 폴더 업로드

다음 예제에서는 path/filepath 패키지를 사용하여 파일 목록을 재귀적으로 수집하여 지정된 Amazon S3 버킷에 업로드합니다. Amazon S3 객체의 키에는 파일의 상대 경로 접두사가 붙습니다.

package main

import (
    "context"
    "log"
    "os"
    "path/filepath"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

var (
    localPath string
    bucket    string
    prefix    string
)

func init() {
    if len(os.Args) != 4 {
        log.Fatalln("Usage:", os.Args[0], "<local path> <bucket> <prefix>")
    }
    localPath = os.Args[1]
    bucket = os.Args[2]
    prefix = os.Args[3]
}

func main() {
    walker := make(fileWalk)
    go func() {
        // Gather the files to upload by walking the path recursively 
        if err := filepath.Walk(localPath, walker.Walk); err != nil {
            log.Fatalln("Walk failed:", err)
        }
        close(walker)
    }()

    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        log.Fatalln("error:", err)
    }
    
    // For each file found walking, upload it to Amazon S3
    uploader := manager.NewUploader(s3.NewFromConfig(cfg))
    for path := range walker {
        rel, err := filepath.Rel(localPath, path)
        if err != nil {
            log.Fatalln("Unable to get relative path:", path, err)
        }
        file, err := os.Open(path)
        if err != nil {
            log.Println("Failed opening file", path, err)
            continue
        }
        defer file.Close()
        result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
            Bucket: &bucket,
            Key:    aws.String(filepath.Join(prefix, rel)),
            Body:   file,
        })
        if err != nil {
            log.Fatalln("Failed to upload", path, err)
        }
        log.Println("Uploaded", path, result.Location)
    }
}

type fileWalk chan string

func (f fileWalk) Walk(path string, info os.FileInfo, err error) error {
    if err != nil {
        return err
    }
    if !info.IsDir() {
        f <- path
    }
    return nil
}

다운로드 관리자

Amazon S3 Downloader 관리자는 파일을 더 작은 부분으로 분할하여 병렬로 다운로드할 수 있는지 여부를 결정합니다. 병렬 다운로드 수와 다운로드한 부분의 크기를 사용자 지정할 수 있습니다.

예: 파일 다운로드

다음 예제에서는 Amazon S3를 사용하여 파일을 Downloader 다운로드합니다. 를 사용하는 Downloader 것은 s3.GetObject 작업과 유사합니다.

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/feature/s3/manager"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Println("error:", err)
    return
}

client := s3.NewFromConfig(cfg)

downloader := manager.NewDownloader(client)
numBytes, err := downloader.Download(context.TODO(), downloadFile, &s3.GetObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"), 
    Key:    aws.String("my-key"),
})

downloadFile 파라미터는 io.WriterAt 유형입니다. WriterAt 인터페이스를 사용하면가 파일의 여러 부분을 병렬Downloader로 쓸 수 있습니다.

구성 옵션

Downloader 인스턴스를 인스턴스화할 때 구성 옵션을 지정하여 객체 다운로드 방법을 사용자 지정할 수 있습니다.

Concurrency 값은 지정된 Download 호출에 대해 발생할 수 있는 동시 파트 다운로드 수를 제한합니다. 이는 글로벌 클라이언트 동시성 제한이 아닙니다. PartSize 및 Concurrency 구성 값을 조정하여 최적의 구성을 찾습니다. 예를 들어 대역폭 연결이 높은 시스템은 더 큰 부분과 더 많은 다운로드를 병렬로 수신할 수 있습니다.

예를 들어 애플리케이션은 Concurrency의 Downloader 로를 구성합니다5. 그러면 애플리케이션이 서로 다른 두 개 고루틴Download에서를 호출하므로 10 동시 파트 다운로드(고루틴 2개 * 5개Concurrency)가 발생합니다.

Downloader 및 기타 구성 옵션에 대한 자세한 내용은 AWS SDK for Go API 참조의 manager.Downloader를 참조하세요.

다운로드당 다운로드 옵션 재정의

메서드에 하나 이상의 기능적 인수Download를 제공하여를 호출할 때 Downloader 옵션을 재정의할 수 있습니다. 이러한 재정의는 동시성에 안전한 수정 사항이며 진행 중인 업로드 또는 후속 관리자 Download 호출에는 영향을 주지 않습니다. 예를 들어 특정 업로드 요청에 대한 PartSize 구성을 재정의하려면

params := &s3.GetObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-key"),
}
resp, err := downloader.Download(context.TODO(), targetWriter, params, func(u *manager.Downloader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

예시

버킷의 모든 객체 다운로드

다음 예제에서는 페이지 매김을 사용하여 Amazon S3 버킷에서 객체 목록을 수집합니다. 그런 다음 각 객체를 로컬 파일로 다운로드합니다.

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

var (
    Bucket         = "amzn-s3-demo-bucket" // Download from this bucket
    Prefix         = "logs/"    // Using this key prefix
    LocalDirectory = "s3logs"   // Into this directory
)

func main() {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        log.Fatalln("error:", err)
    }

    client := s3.NewFromConfig(cfg)
    manager := manager.NewDownloader(client)

    paginator := s3.NewListObjectsV2Paginator(client, &s3.ListObjectsV2Input{
        Bucket: &Bucket,
        Prefix: &Prefix,
    })

    for paginator.HasMorePages() {
        page, err := paginator.NextPage(context.TODO())
        if err != nil {
            log.Fatalln("error:", err)
        }
        for _, obj := range page.Contents {
            if err := downloadToFile(manager, LocalDirectory, Bucket, aws.ToString(obj.Key)); err != nil {
                log.Fatalln("error:", err)
            }
        }
    }
}

func downloadToFile(downloader *manager.Downloader, targetDirectory, bucket, key string) error {
    // Create the directories in the path
    file := filepath.Join(targetDirectory, key)
    if err := os.MkdirAll(filepath.Dir(file), 0775); err != nil {
        return err
    }

    // Set up the local file
    fd, err := os.Create(file)
    if err != nil {
        return err
    }
    defer fd.Close()

    // Download the file using the AWS SDK for Go
    fmt.Printf("Downloading s3://%s/%s to %s...\n", bucket, key, file)
    _, err = downloader.Download(context.TODO(), fd, &s3.GetObjectInput{Bucket: &bucket, Key: &key})

    return err
}

GetBucketRegion

GetBucketRegion은 Amazon S3 버킷의 AWS 리전 위치를 결정하는 유틸리티 함수입니다. GetBucketRegion는 Amazon S3 클라이언트를 가져와 클라이언트의 구성된 리전과 연결된 AWS 파티션 내에서 요청된 버킷의 위치를 결정하는 데 사용합니다.

예를 들어 버킷의 리전을 찾으려면amzn-s3-demo-bucket:

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Println("error:", err)
    return
}

bucket := "amzn-s3-demo-bucket"
region, err := manager.GetBucketRegion(ctx, s3.NewFromConfig(cfg), bucket)
if err != nil {
    var bnf manager.BucketNotFound
    if errors.As(err, &bnf) {
        log.Printf("unable to find bucket %s's Region\n", bucket)
    } else {
        log.Println("error:", err)
    }
    return
}
fmt.Printf("Bucket %s is in %s region\n", bucket, region)

GetBucketRegion가 버킷의 위치를 확인할 수 없는 경우 함수는 예제와 같이 BucketNotFound 오류 유형을 반환합니다.

확인할 수 없는 스트리밍 입력

PutObject 및와 같은 API 작업UploadPart의 경우 Amazon S3 클라이언트는 Body 입력 파라미터의 값이 기본적으로 io.Seeker 인터페이스를 구현할 것으로 예상합니다. io.Seeker 인터페이스는 클라이언트가 업로드할 값의 길이를 결정하고 요청 서명의 페이로드 해시를 계산하는 데 사용됩니다. Body 입력 파라미터 값이를 구현하지 않으면 io.Seeker애플리케이션에 오류가 발생합니다.

operation error S3: PutObject, failed to compute payload hash: failed to seek
body to start, request stream is not seekable

기능 옵션을 미들웨어 사용하여 작업 방법의를 수정하여이 동작을 변경할 수 있습니다. WithAPIOptions 헬퍼는 0개 이상의 미들웨어 변형기에 대한 기능 옵션을 반환합니다. 페이로드 해시를 계산하는 클라이언트를 비활성화하고 서명되지 않은 페이로드 요청 서명을 사용하려면 v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware를 추가합니다.

resp, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
    Bucket: &bucketName,
    Key: &objectName,
    Body: bytes.NewBuffer([]byte(`example object!`)),
    ContentLength: 15, // length of body
}, s3.WithAPIOptions(
    v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware,
))