CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/golang-github-com--aws--aws-sdk-go-v2

AWS SDK for Go v2 with 130+ service clients, Request/Send pattern, and context support.

Overview
Eval results
Files

s3.mddocs/reference/

Amazon S3 (service/s3)

Import: github.com/aws/aws-sdk-go-v2/service/s3

Full Amazon S3 client including bucket management, object operations, multipart uploads, presigned URLs, encryption, and bucket notifications.

Client

const ServiceName = "s3"

type S3 struct {
    *aws.Client
}

func New(config aws.Config) *S3

Configuration Notes

  • S3 uses path-style or virtual-hosted-style addressing. The SDK defaults to virtual-hosted-style.
  • For S3, URL path escaping is disabled (DisableURIPathEscaping: true in signer options).
  • The DisableRestProtocolURICleaning config option on aws.Config affects S3 key names with empty path segments.

Error Codes

const (
    ErrCodeBucketAlreadyExists                    = "BucketAlreadyExists"
    ErrCodeBucketAlreadyOwnedByYou                = "BucketAlreadyOwnedByYou"
    ErrCodeNoSuchBucket                           = "NoSuchBucket"
    ErrCodeNoSuchKey                              = "NoSuchKey"
    ErrCodeNoSuchUpload                           = "NoSuchUpload"
    ErrCodeObjectAlreadyInActiveTierError         = "ObjectAlreadyInActiveTierError"
    ErrCodeObjectNotInActiveTierError             = "ObjectNotInActiveTierError"
)

Bucket Operations

func (c *S3) CreateBucketRequest(input *CreateBucketInput) CreateBucketRequest
func (c *S3) DeleteBucketRequest(input *DeleteBucketInput) DeleteBucketRequest
func (c *S3) HeadBucketRequest(input *HeadBucketInput) HeadBucketRequest
func (c *S3) ListBucketsRequest(input *ListBucketsInput) ListBucketsRequest

// Bucket configuration
func (c *S3) GetBucketAclRequest(input *GetBucketAclInput) GetBucketAclRequest
func (c *S3) PutBucketAclRequest(input *PutBucketAclInput) PutBucketAclRequest
func (c *S3) GetBucketCorsRequest(input *GetBucketCorsInput) GetBucketCorsRequest
func (c *S3) PutBucketCorsRequest(input *PutBucketCorsInput) PutBucketCorsRequest
func (c *S3) DeleteBucketCorsRequest(input *DeleteBucketCorsInput) DeleteBucketCorsRequest
func (c *S3) GetBucketEncryptionRequest(input *GetBucketEncryptionInput) GetBucketEncryptionRequest
func (c *S3) PutBucketEncryptionRequest(input *PutBucketEncryptionInput) PutBucketEncryptionRequest
func (c *S3) DeleteBucketEncryptionRequest(input *DeleteBucketEncryptionInput) DeleteBucketEncryptionRequest
func (c *S3) GetBucketLifecycleConfigurationRequest(input *GetBucketLifecycleConfigurationInput) GetBucketLifecycleConfigurationRequest
func (c *S3) PutBucketLifecycleConfigurationRequest(input *PutBucketLifecycleConfigurationInput) PutBucketLifecycleConfigurationRequest
func (c *S3) DeleteBucketLifecycleRequest(input *DeleteBucketLifecycleInput) DeleteBucketLifecycleRequest
func (c *S3) GetBucketLocationRequest(input *GetBucketLocationInput) GetBucketLocationRequest
func (c *S3) GetBucketLoggingRequest(input *GetBucketLoggingInput) GetBucketLoggingRequest
func (c *S3) PutBucketLoggingRequest(input *PutBucketLoggingInput) PutBucketLoggingRequest
func (c *S3) GetBucketNotificationConfigurationRequest(input *GetBucketNotificationConfigurationInput) GetBucketNotificationConfigurationRequest
func (c *S3) PutBucketNotificationConfigurationRequest(input *PutBucketNotificationConfigurationInput) PutBucketNotificationConfigurationRequest
func (c *S3) GetBucketPolicyRequest(input *GetBucketPolicyInput) GetBucketPolicyRequest
func (c *S3) PutBucketPolicyRequest(input *PutBucketPolicyInput) PutBucketPolicyRequest
func (c *S3) DeleteBucketPolicyRequest(input *DeleteBucketPolicyInput) DeleteBucketPolicyRequest
func (c *S3) GetBucketReplicationRequest(input *GetBucketReplicationInput) GetBucketReplicationRequest
func (c *S3) PutBucketReplicationRequest(input *PutBucketReplicationInput) PutBucketReplicationRequest
func (c *S3) DeleteBucketReplicationRequest(input *DeleteBucketReplicationInput) DeleteBucketReplicationRequest
func (c *S3) GetBucketRequestPaymentRequest(input *GetBucketRequestPaymentInput) GetBucketRequestPaymentRequest
func (c *S3) PutBucketRequestPaymentRequest(input *PutBucketRequestPaymentInput) PutBucketRequestPaymentRequest
func (c *S3) GetBucketTaggingRequest(input *GetBucketTaggingInput) GetBucketTaggingRequest
func (c *S3) PutBucketTaggingRequest(input *PutBucketTaggingInput) PutBucketTaggingRequest
func (c *S3) DeleteBucketTaggingRequest(input *DeleteBucketTaggingInput) DeleteBucketTaggingRequest
func (c *S3) GetBucketVersioningRequest(input *GetBucketVersioningInput) GetBucketVersioningRequest
func (c *S3) PutBucketVersioningRequest(input *PutBucketVersioningInput) PutBucketVersioningRequest
func (c *S3) GetBucketWebsiteRequest(input *GetBucketWebsiteInput) GetBucketWebsiteRequest
func (c *S3) PutBucketWebsiteRequest(input *PutBucketWebsiteInput) PutBucketWebsiteRequest
func (c *S3) DeleteBucketWebsiteRequest(input *DeleteBucketWebsiteInput) DeleteBucketWebsiteRequest
func (c *S3) GetBucketAccelerateConfigurationRequest(input *GetBucketAccelerateConfigurationInput) GetBucketAccelerateConfigurationRequest
func (c *S3) PutBucketAccelerateConfigurationRequest(input *PutBucketAccelerateConfigurationInput) PutBucketAccelerateConfigurationRequest

Object Operations

func (c *S3) GetObjectRequest(input *GetObjectInput) GetObjectRequest
func (c *S3) PutObjectRequest(input *PutObjectInput) PutObjectRequest
func (c *S3) HeadObjectRequest(input *HeadObjectInput) HeadObjectRequest
func (c *S3) DeleteObjectRequest(input *DeleteObjectInput) DeleteObjectRequest
func (c *S3) DeleteObjectsRequest(input *DeleteObjectsInput) DeleteObjectsRequest
func (c *S3) CopyObjectRequest(input *CopyObjectInput) CopyObjectRequest
func (c *S3) RestoreObjectRequest(input *RestoreObjectInput) RestoreObjectRequest
func (c *S3) SelectObjectContentRequest(input *SelectObjectContentInput) SelectObjectContentRequest
func (c *S3) GetObjectAclRequest(input *GetObjectAclInput) GetObjectAclRequest
func (c *S3) PutObjectAclRequest(input *PutObjectAclInput) PutObjectAclRequest
func (c *S3) GetObjectTaggingRequest(input *GetObjectTaggingInput) GetObjectTaggingRequest
func (c *S3) PutObjectTaggingRequest(input *PutObjectTaggingInput) PutObjectTaggingRequest
func (c *S3) DeleteObjectTaggingRequest(input *DeleteObjectTaggingInput) DeleteObjectTaggingRequest
func (c *S3) GetObjectTorrentRequest(input *GetObjectTorrentInput) GetObjectTorrentRequest

Object Listing

func (c *S3) ListObjectsRequest(input *ListObjectsInput) ListObjectsRequest
func (c *S3) ListObjectsV2Request(input *ListObjectsV2Input) ListObjectsV2Request
func (c *S3) ListObjectVersionsRequest(input *ListObjectVersionsInput) ListObjectVersionsRequest

Multipart Upload

func (c *S3) CreateMultipartUploadRequest(input *CreateMultipartUploadInput) CreateMultipartUploadRequest
func (c *S3) UploadPartRequest(input *UploadPartInput) UploadPartRequest
func (c *S3) UploadPartCopyRequest(input *UploadPartCopyInput) UploadPartCopyRequest
func (c *S3) CompleteMultipartUploadRequest(input *CompleteMultipartUploadInput) CompleteMultipartUploadRequest
func (c *S3) AbortMultipartUploadRequest(input *AbortMultipartUploadInput) AbortMultipartUploadRequest
func (c *S3) ListMultipartUploadsRequest(input *ListMultipartUploadsInput) ListMultipartUploadsRequest
func (c *S3) ListPartsRequest(input *ListPartsInput) ListPartsRequest

Analytics/Metrics/Inventory

func (c *S3) GetBucketAnalyticsConfigurationRequest(input *GetBucketAnalyticsConfigurationInput) GetBucketAnalyticsConfigurationRequest
func (c *S3) PutBucketAnalyticsConfigurationRequest(input *PutBucketAnalyticsConfigurationInput) PutBucketAnalyticsConfigurationRequest
func (c *S3) DeleteBucketAnalyticsConfigurationRequest(input *DeleteBucketAnalyticsConfigurationInput) DeleteBucketAnalyticsConfigurationRequest
func (c *S3) ListBucketAnalyticsConfigurationsRequest(input *ListBucketAnalyticsConfigurationsInput) ListBucketAnalyticsConfigurationsRequest
func (c *S3) GetBucketMetricsConfigurationRequest(input *GetBucketMetricsConfigurationInput) GetBucketMetricsConfigurationRequest
func (c *S3) PutBucketMetricsConfigurationRequest(input *PutBucketMetricsConfigurationInput) PutBucketMetricsConfigurationRequest
func (c *S3) DeleteBucketMetricsConfigurationRequest(input *DeleteBucketMetricsConfigurationInput) DeleteBucketMetricsConfigurationRequest
func (c *S3) ListBucketMetricsConfigurationsRequest(input *ListBucketMetricsConfigurationsInput) ListBucketMetricsConfigurationsRequest
func (c *S3) GetBucketInventoryConfigurationRequest(input *GetBucketInventoryConfigurationInput) GetBucketInventoryConfigurationRequest
func (c *S3) PutBucketInventoryConfigurationRequest(input *PutBucketInventoryConfigurationInput) PutBucketInventoryConfigurationRequest
func (c *S3) DeleteBucketInventoryConfigurationRequest(input *DeleteBucketInventoryConfigurationInput) DeleteBucketInventoryConfigurationRequest
func (c *S3) ListBucketInventoryConfigurationsRequest(input *ListBucketInventoryConfigurationsInput) ListBucketInventoryConfigurationsRequest

Waiters

func (c *S3) WaitUntilBucketExists(ctx aws.Context, input *HeadBucketInput, opts ...aws.WaiterOption) error
func (c *S3) WaitUntilBucketNotExists(ctx aws.Context, input *HeadBucketInput, opts ...aws.WaiterOption) error
func (c *S3) WaitUntilObjectExists(ctx aws.Context, input *HeadObjectInput, opts ...aws.WaiterOption) error
func (c *S3) WaitUntilObjectNotExists(ctx aws.Context, input *HeadObjectInput, opts ...aws.WaiterOption) error

Helper Functions

// Normalize bucket location: normalizes EU to eu-west-1
func NormalizeBucketLocation(loc BucketLocationConstraint) BucketLocationConstraint
func WithNormalizeBucketLocation(r *aws.Request)
var NormalizeBucketLocationHandler aws.NamedHandler

Key Types

Enum Types

type BucketCannedACL string
const (
    BucketCannedACLPrivate           BucketCannedACL = "private"
    BucketCannedACLPublicRead        BucketCannedACL = "public-read"
    BucketCannedACLPublicReadWrite   BucketCannedACL = "public-read-write"
    BucketCannedACLAuthenticatedRead BucketCannedACL = "authenticated-read"
)

type ObjectCannedACL string
const (
    ObjectCannedACLPrivate                  ObjectCannedACL = "private"
    ObjectCannedACLPublicRead               ObjectCannedACL = "public-read"
    ObjectCannedACLPublicReadWrite          ObjectCannedACL = "public-read-write"
    ObjectCannedACLAuthenticatedRead        ObjectCannedACL = "authenticated-read"
    ObjectCannedACLAwsExecRead              ObjectCannedACL = "aws-exec-read"
    ObjectCannedACLBucketOwnerRead          ObjectCannedACL = "bucket-owner-read"
    ObjectCannedACLBucketOwnerFullControl   ObjectCannedACL = "bucket-owner-full-control"
)

type StorageClass string
const (
    StorageClassStandard           StorageClass = "STANDARD"
    StorageClassReducedRedundancy  StorageClass = "REDUCED_REDUNDANCY"
    StorageClassStandardIa         StorageClass = "STANDARD_IA"
    StorageClassOnezoneIa          StorageClass = "ONEZONE_IA"
    StorageClassGlacier            StorageClass = "GLACIER"
)

type ServerSideEncryption string
const (
    ServerSideEncryptionAes256  ServerSideEncryption = "AES256"
    ServerSideEncryptionAwsKms  ServerSideEncryption = "aws:kms"
)

type BucketVersioningStatus string
const (
    BucketVersioningStatusEnabled   BucketVersioningStatus = "Enabled"
    BucketVersioningStatusSuspended BucketVersioningStatus = "Suspended"
)

type BucketLocationConstraint string
const (
    BucketLocationConstraintEu         BucketLocationConstraint = "EU"
    BucketLocationConstraintEuWest1    BucketLocationConstraint = "eu-west-1"
    BucketLocationConstraintUsWest1    BucketLocationConstraint = "us-west-1"
    BucketLocationConstraintUsWest2    BucketLocationConstraint = "us-west-2"
    BucketLocationConstraintApSouth1   BucketLocationConstraint = "ap-south-1"
    BucketLocationConstraintApSoutheast1 BucketLocationConstraint = "ap-southeast-1"
    BucketLocationConstraintApSoutheast2 BucketLocationConstraint = "ap-southeast-2"
    BucketLocationConstraintApNortheast1 BucketLocationConstraint = "ap-northeast-1"
    BucketLocationConstraintSaEast1    BucketLocationConstraint = "sa-east-1"
    BucketLocationConstraintCnNorth1   BucketLocationConstraint = "cn-north-1"
    BucketLocationConstraintEuCentral1 BucketLocationConstraint = "eu-central-1"
    // ... more regions
)

type TaggingDirective string
const (
    TaggingDirectiveCopy    TaggingDirective = "COPY"
    TaggingDirectiveReplace TaggingDirective = "REPLACE"
)

type RequestPayer string
const (
    RequestPayerRequester RequestPayer = "requester"
)

type Tier string
const (
    TierStandard  Tier = "Standard"
    TierBulk      Tier = "Bulk"
    TierExpedited Tier = "Expedited"
)

type Type string
const (
    TypeCanonicalUser         Type = "CanonicalUser"
    TypeAmazonCustomerByEmail Type = "AmazonCustomerByEmail"
    TypeGroup                 Type = "Group"
)

type ReplicationStatus string
const (
    ReplicationStatusComplete  ReplicationStatus = "COMPLETE"
    ReplicationStatusPending   ReplicationStatus = "PENDING"
    ReplicationStatusFailed    ReplicationStatus = "FAILED"
    ReplicationStatusReplica   ReplicationStatus = "REPLICA"
)

Key Input/Output Structs

type GetObjectInput struct {
    Bucket                     *string `location:"uri" locationName:"Bucket"`
    Key                        *string `location:"uri" locationName:"Key"`
    IfMatch                    *string `location:"header" locationName:"If-Match"`
    IfModifiedSince            *time.Time
    IfNoneMatch                *string
    IfUnmodifiedSince          *time.Time
    PartNumber                 *int64
    Range                      *string `location:"header" locationName:"Range"`
    RequestPayer               RequestPayer
    ResponseCacheControl       *string
    ResponseContentDisposition *string
    ResponseContentEncoding    *string
    ResponseContentLanguage    *string
    ResponseContentType        *string
    ResponseExpires            *time.Time
    SSECustomerAlgorithm       *string
    SSECustomerKey             *string
    SSECustomerKeyMD5          *string
    VersionId                  *string
}

type GetObjectOutput struct {
    Body                  io.ReadCloser
    ContentLength         *int64
    ContentType           *string
    ContentEncoding       *string
    ContentDisposition    *string
    ContentLanguage       *string
    ContentRange          *string
    ETag                  *string
    Expiration            *string
    LastModified          *time.Time
    Metadata              map[string]*string
    MissingMeta           *int64
    PartsCount            *int64
    ReplicationStatus     ReplicationStatus
    RequestCharged        RequestCharged
    Restore               *string
    SSECustomerAlgorithm  *string
    SSECustomerKeyMD5     *string
    SSEKMSKeyId           *string
    ServerSideEncryption  ServerSideEncryption
    StorageClass          StorageClass
    TagCount              *int64
    VersionId             *string
    WebsiteRedirectLocation *string
    DeleteMarker          *bool
    MissingMeta           *int64
}

type PutObjectInput struct {
    Bucket                          *string `location:"uri" locationName:"Bucket"`
    Key                             *string `location:"uri" locationName:"Key"`
    Body                            io.ReadSeeker
    ACL                             ObjectCannedACL
    CacheControl                    *string
    ContentDisposition              *string
    ContentEncoding                 *string
    ContentLanguage                 *string
    ContentLength                   *int64
    ContentMD5                      *string
    ContentType                     *string
    Expires                         *time.Time
    GrantFullControl                *string
    GrantRead                       *string
    GrantReadACP                    *string
    GrantWriteACP                   *string
    Metadata                        map[string]*string
    RequestPayer                    RequestPayer
    SSECustomerAlgorithm            *string
    SSECustomerKey                  *string
    SSECustomerKeyMD5               *string
    SSEKMSKeyId                     *string
    ServerSideEncryption            ServerSideEncryption
    StorageClass                    StorageClass
    Tagging                         *string
    WebsiteRedirectLocation         *string
}

type PutObjectOutput struct {
    ETag                 *string
    Expiration           *string
    RequestCharged       RequestCharged
    SSECustomerAlgorithm *string
    SSECustomerKeyMD5    *string
    SSEKMSKeyId          *string
    ServerSideEncryption ServerSideEncryption
    VersionId            *string
}

type CreateBucketInput struct {
    Bucket                    *string `location:"uri" locationName:"Bucket"`
    ACL                       BucketCannedACL
    CreateBucketConfiguration *CreateBucketConfiguration
    GrantFullControl          *string
    GrantRead                 *string
    GrantReadACP              *string
    GrantWrite                *string
    GrantWriteACP             *string
    ObjectLockEnabledForBucket *bool
}

type CreateBucketConfiguration struct {
    LocationConstraint BucketLocationConstraint
}

type DeleteObjectsInput struct {
    Bucket       *string `location:"uri" locationName:"Bucket"`
    Delete       *Delete
    MFA          *string
    RequestPayer RequestPayer
}

type Delete struct {
    Objects []ObjectIdentifier
    Quiet   *bool
}

type ObjectIdentifier struct {
    Key       *string
    VersionId *string
}

type ListObjectsV2Input struct {
    Bucket            *string `location:"uri" locationName:"Bucket"`
    ContinuationToken *string
    Delimiter         *string
    EncodingType      EncodingType
    FetchOwner        *bool
    MaxKeys           *int64
    Prefix            *string
    RequestPayer      RequestPayer
    StartAfter        *string
}

type ListObjectsV2Output struct {
    Contents              []Object
    CommonPrefixes        []CommonPrefix
    ContinuationToken     *string
    Delimiter             *string
    EncodingType          EncodingType
    IsTruncated           *bool
    KeyCount              *int64
    MaxKeys               *int64
    Name                  *string
    NextContinuationToken *string
    Prefix                *string
    StartAfter            *string
}

type Object struct {
    ETag         *string
    Key          *string
    LastModified *time.Time
    Owner        *Owner
    Size         *int64
    StorageClass ObjectStorageClass
}

type Owner struct {
    DisplayName *string
    ID          *string
}

type Bucket struct {
    CreationDate *time.Time
    Name         *string
}

type Tag struct {
    Key   *string
    Value *string
}

type Tagging struct {
    TagSet []Tag
}

Common Usage Patterns

Upload Object

svc := s3.New(cfg)
f, _ := os.Open("file.txt")
defer f.Close()

req := svc.PutObjectRequest(&s3.PutObjectInput{
    Bucket:      aws.String("my-bucket"),
    Key:         aws.String("path/to/file.txt"),
    Body:        f,
    ContentType: aws.String("text/plain"),
    ServerSideEncryption: s3.ServerSideEncryptionAes256,
})
resp, err := req.Send()

Download Object

req := svc.GetObjectRequest(&s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("path/to/file.txt"),
})
resp, err := req.Send()
if err != nil { ... }
defer resp.Body.Close()
data, _ := ioutil.ReadAll(resp.Body)

Presigned URL

req := svc.GetObjectRequest(&s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("path/to/file.txt"),
})
url, err := req.Presign(15 * time.Minute)

List Objects (Paginated)

req := svc.ListObjectsV2Request(&s3.ListObjectsV2Input{
    Bucket: aws.String("my-bucket"),
    Prefix: aws.String("logs/"),
})
p := req.Paginate()
for p.Next() {
    for _, obj := range p.CurrentPage().Contents {
        fmt.Printf("%s (%d bytes)\n", *obj.Key, *obj.Size)
    }
}
if err := p.Err(); err != nil { ... }

Batch Delete

req := svc.DeleteObjectsRequest(&s3.DeleteObjectsInput{
    Bucket: aws.String("my-bucket"),
    Delete: &s3.Delete{
        Objects: []s3.ObjectIdentifier{
            {Key: aws.String("file1.txt")},
            {Key: aws.String("file2.txt")},
        },
        Quiet: aws.Bool(true),
    },
})
resp, err := req.Send()

Copy Object

req := svc.CopyObjectRequest(&s3.CopyObjectInput{
    Bucket:     aws.String("dest-bucket"),
    Key:        aws.String("dest-key"),
    CopySource: aws.String("source-bucket/source-key"),
    StorageClass: s3.StorageClassStandardIa,
})

S3 Client-Side Encryption

See S3 Encryption for s3crypto documentation.

S3 Interface Package

// From github.com/aws/aws-sdk-go-v2/service/s3/s3iface
type S3API interface {
    // All S3 operations as methods
    CreateBucketRequest(*s3.CreateBucketInput) s3.CreateBucketRequest
    DeleteBucketRequest(*s3.DeleteBucketInput) s3.DeleteBucketRequest
    GetObjectRequest(*s3.GetObjectInput) s3.GetObjectRequest
    PutObjectRequest(*s3.PutObjectInput) s3.PutObjectRequest
    // ... all other operations
    WaitUntilBucketExists(aws.Context, *s3.HeadBucketInput, ...aws.WaiterOption) error
    WaitUntilBucketNotExists(aws.Context, *s3.HeadBucketInput, ...aws.WaiterOption) error
    WaitUntilObjectExists(aws.Context, *s3.HeadObjectInput, ...aws.WaiterOption) error
    WaitUntilObjectNotExists(aws.Context, *s3.HeadObjectInput, ...aws.WaiterOption) error
}

Install with Tessl CLI

npx tessl i tessl/golang-github-com--aws--aws-sdk-go-v2@0.4.0

docs

reference

config.md

core.md

credentials.md

endpoints.md

errors.md

request.md

s3.md

s3manager.md

services.md

signing.md

utilities.md

index.md

tile.json