github.com-aws-aws-sdk-go_-_2019-11-09_00-42-16

github.com-aws-aws-sdk-go_-_2019-11-09_00-42-16

Posted by

Download
ITEM TILE – File Size: 8.7K

AWS SDK for the Go programming language.

API Reference Join the chat at https://gitter.im/aws/aws-sdk-go Build Status Apache V2 License

AWS SDK for Go

aws-sdk-go is the official AWS SDK for the Go programming language.

Checkout our release notes forinformation about the latest bug fixes, updates, and features added to the SDK.

We announced the Developer Preview for the v2 AWS SDK for Go. The v2 SDK source is available at https://github.com/aws/aws-sdk-go-v2, and add it to your project with go get github.com/aws/aws-sdk-go-v2. Check out the v2 SDK’s changes and updates, and let us know what you think. We want your feedback.

We have a pilot redesign of the AWS SDK for Go API reference documentation. Let us know what you think.

Installing

Use go get to retrieve the SDK to add it to your GOPATH workspace, orproject’s Go module dependencies.

go get github.com/aws/aws-sdk-go

To update the SDK use go get -u to retrieve the latest version of the SDK.

go get -u github.com/aws/aws-sdk-go

Dependencies

The SDK includes a vendor folder containing the runtime dependencies of theSDK. The metadata of the SDK’s dependencies can be found in the Go module filego.mod or Dep file Gopkg.toml.

Go Modules

If you are using Go modules, your go get will default to the latest taggedrelease version of the SDK. To get a specific release version of the SDK use@ in your go get command.

go get github.com/aws/aws-sdk-go@v1.15.77

To get the latest SDK repository change use @latest.

go get github.com/aws/aws-sdk-go@latest

Go 1.5

If you are using Go 1.5 without vendoring enabled, (GO15VENDOREXPERIMENT=1),you will need to use ... when retrieving the SDK to get its dependencies.

go get github.com/aws/aws-sdk-go/...

This will still include the vendor folder. The vendor folder can be deletedif not used by your environment.

rm -rf $GOPATH/src/github.com/aws/aws-sdk-go/vendor

Getting Help

Please use these community resources for getting help. We use the GitHub issuesfor tracking bugs and feature requests.

  • Ask a question on StackOverflow and tag it with the aws-sdk-go tag.
  • Come join the AWS SDK for Go community chat on gitter.
  • Open a support ticket with AWS Support.
  • If you think you may have found a bug, please open an issue.

Opening Issues

If you encounter a bug with the AWS SDK for Go we would like to hear about it.Search the existing issues and seeif others are also experiencing the issue before opening a new issue. Pleaseinclude the version of AWS SDK for Go, Go language, and OS you’re using. Pleasealso include reproduction case when appropriate.

The GitHub issues are intended for bug reports and feature requests. For helpand questions with using AWS SDK for GO please make use of the resources listedin the Getting Help section.Keeping the list of open issues lean will help us respond in a timely manner.

Reference Documentation

Getting Started Guide – This documentis a general introduction on how to configure and make requests with the SDK.If this is your first time using the SDK, this documentation and the APIdocumentation will help you get started. This document focuses on the syntaxand behavior of the SDK. The Service DeveloperGuide will help you get started usingspecific AWS services.

SDK API ReferenceDocumentation – Use thisdocument to look up all API operation input and output parameters for AWSservices supported by the SDK. The API reference also includes documentation ofthe SDK, and examples how to using the SDK, service client API operations, andAPI operation require parameters.

Service Developer Guide – Use thisdocumentation to learn how to interface with AWS services. These are greatguides both, if you’re getting started with a service, or looking for moreinformation on a service. You should not need this document for coding, thoughin some cases, services may supply helpful samples that you might want to lookout for.

SDK Examples -Included in the SDK’s repo are several hand crafted examples using the SDKfeatures and AWS services.

Overview of SDK’s Packages

The SDK is composed of two main components, SDK core, and service clients.The SDK core packages are all available under the aws package at the root ofthe SDK. Each client for a supported AWS service is available within its ownpackage under the service folder at the root of the SDK.

  • aws – SDK core, provides common shared types such as Config, Logger,and utilities to make working with API parameters easier.

    • awserr – Provides the error interface that the SDK will use for allerrors that occur in the SDK’s processing. This includes service APIresponse errors as well. The Error type is made up of a code and message.Cast the SDK’s returned error type to awserr.Error and call the Codemethod to compare returned error to specific error codes. See the package’sdocumentation for additional values that can be extracted such as RequestID.

    • credentials – Provides the types and built in credentials providersthe SDK will use to retrieve AWS credentials to make API requests with.Nested under this folder are also additional credentials providers such asstscreds for assuming IAM roles, and ec2rolecreds for EC2 Instance roles.

    • endpoints – Provides the AWS Regions and Endpoints metadata for the SDK.Use this to lookup AWS service endpoint information such as which servicesare in a region, and what regions a service is in. Constants are also providedfor all region identifiers, e.g UsWest2RegionID for “us-west-2”.

    • session – Provides initial default configuration, and loadconfiguration from external sources such as environment and sharedcredentials file.

    • request – Provides the API request sending, and retry logic for the SDK.This package also includes utilities for defining your own requestretryer, and configuring how the SDK processes the request.

  • service – Clients for AWS services. All services supported by the SDK areavailable under this folder.

How to Use the SDK’s AWS Service Clients

The SDK includes the Go types and utilities you can use to make requests toAWS service APIs. Within the service folder at the root of the SDK you’ll finda package for each AWS service the SDK supports. All service clients follow common pattern of creation and usage.

When creating a client for an AWS service you’ll first need to have a Sessionvalue constructed. The Session provides shared configuration that can be sharedbetween your service clients. When service clients are created you can passin additional configuration via the aws.Config type to override configurationprovided by in the Session to create service client instances with customconfiguration.

Once the service’s client is created you can use it to make API requests theAWS service. These clients are safe to use concurrently.

Configuring the SDK

In the AWS SDK for Go, you can configure settings for service clients, suchas the log level and maximum number of retries. Most settings are optional;however, for each service client, you must specify a region and your credentials.The SDK uses these values to send requests to the correct AWS region and signrequests with the correct credentials. You can specify these values as partof a session or as environment variables.

See the SDK’s configuration guide for more information.

See the session package documentation for more information on how to use Sessionwith the SDK.

See the Config type in the aws package for more information on configurationoptions.

Configuring Credentials

When using the SDK you’ll generally need your AWS credentials to authenticatewith AWS services. The SDK supports multiple methods of supporting thesecredentials. By default the SDK will source credentials automatically fromits default credential chain. See the session package for more informationon this chain, and how to configure it. The common items in the credentialchain are the following:

  • Environment Credentials – Set of environment variables that are usefulwhen sub processes are created for specific roles.

  • Shared Credentials file (~/.aws/credentials) – This file stores yourcredentials based on a profile name and is useful for local development.

  • EC2 Instance Role Credentials – Use EC2 Instance Role to assign credentialsto application running on an EC2 instance. This removes the need to managecredential files in production.

Credentials can be configured in code as well by setting the Config’s Credentialsvalue to a custom provider or using one of the providers included with theSDK to bypass the default credential chain and use a custom one. This ishelpful when you want to instruct the SDK to only use a specific set ofcredentials or providers.

This example creates a credential provider for assuming an IAM role, “myRoleARN”and configures the S3 service client to use that role for API requests.

“`go // Initial credentials loaded from SDK’s default credential chain. Such as // the environment, shared credentials (~/.aws/credentials), or EC2 Instance // Role. These credentials will be used to to make the STS Assume Role API. sess := session.Must(session.NewSession())

// Create the credentials from AssumeRoleProvider to assume the role // referenced by the “myRoleARN” ARN. creds := stscreds.NewCredentials(sess, “myRoleArn”)

// Create service client value configured for credentials // from assumed role. svc := s3.New(sess, &aws.Config{Credentials: creds})“`

See the credentials package documentation for more information on credentialproviders included with the SDK, and how to customize the SDK’s usage ofcredentials.

The SDK has support for the shared configuration file (~/.aws/config). Thissupport can be enabled by setting the environment variable, “AWSSDKLOAD_CONFIG=1″,or enabling the feature in code when creating a Session via theOption’s SharedConfigState parameter.

go sess := session.Must(session.NewSessionWithOptions(session.Options{ SharedConfigState: session.SharedConfigEnable, }))

Configuring AWS Region

In addition to the credentials you’ll need to specify the region the SDKwill use to make AWS API requests to. In the SDK you can specify the regioneither with an environment variable, or directly in code when a Session orservice client is created. The last value specified in code wins if the regionis specified multiple ways.

To set the region via the environment variable set the “AWS_REGION” to theregion you want to the SDK to use. Using this method to set the region willallow you to run your application in multiple regions without needing additionalcode in the application to select the region.

AWS_REGION=us-west-2

The endpoints package includes constants for all regions the SDK knows. Thevalues are all suffixed with RegionID. These values are helpful, because theyreduce the need to type the region string manually.

To set the region on a Session use the aws package’s Config struct parameterRegion to the AWS region you want the service clients created from the session touse. This is helpful when you want to create multiple service clients, andall of the clients make API requests to the same region.

go sess := session.Must(session.NewSession(&aws.Config{ Region: aws.String(endpoints.UsWest2RegionID), }))

See the endpoints package for the AWS Regions and Endpoints metadata.

In addition to setting the region when creating a Session you can also setthe region on a per service client bases. This overrides the region of aSession. This is helpful when you want to create service clients in specificregions different from the Session’s region.

go svc := s3.New(sess, &aws.Config{ Region: aws.String(endpoints.UsWest2RegionID), })

See the Config type in the aws package for more information and additionaloptions such as setting the Endpoint, and other service client configuration options.

Making API Requests

Once the client is created you can make an API request to the service.Each API method takes a input parameter, and returns the service responseand an error. The SDK provides methods for making the API call in multiple ways.

In this list we’ll use the S3 ListObjects API as an example for the differentways of making API requests.

  • ListObjects – Base API operation that will make the API request to the service.

  • ListObjectsRequest – API methods suffixed with Request will construct theAPI request, but not send it. This is also helpful when you want to get apresigned URL for a request, and share the presigned URL instead of yourapplication making the request directly.

  • ListObjectsPages – Same as the base API operation, but uses a callback toautomatically handle pagination of the API’s response.

  • ListObjectsWithContext – Same as base API operation, but adds support forthe Context pattern. This is helpful for controlling the canceling of inflight requests. See the Go standard library context package for moreinformation. This method also takes request package’s Option functionaloptions as the variadic argument for modifying how the request will bemade, or extracting information from the raw HTTP response.

  • ListObjectsPagesWithContext – same as ListObjectsPages, but adds support forthe Context pattern. Similar to ListObjectsWithContext this method alsotakes the request package’s Option function option types as the variadicargument.

In addition to the API operations the SDK also includes several higher levelmethods that abstract checking for and waiting for an AWS resource to be ina desired state. In this list we’ll use WaitUntilBucketExists to demonstratethe different forms of waiters.

  • WaitUntilBucketExists. – Method to make API request to query an AWS service fora resource’s state. Will return successfully when that state is accomplished.

  • WaitUntilBucketExistsWithContext – Same as WaitUntilBucketExists, but addssupport for the Context pattern. In addition these methods take requestpackage’s WaiterOptions to configure the waiter, and how underlying requestwill be made by the SDK.

The API method will document which error codes the service might return forthe operation. These errors will also be available as const strings prefixedwith “ErrCode” in the service client’s package. If there are no errors listedin the API’s SDK documentation you’ll need to consult the AWS service’s APIdocumentation for the errors that could be returned.

“`go ctx := context.Background()

result, err := svc.GetObjectWithContext(ctx, &s3.GetObjectInput{ Bucket: aws.String(“my-bucket”), Key: aws.String(“my-key”), }) if err != nil { // Cast err to awserr.Error to handle specific error codes. aerr, ok := err.(awserr.Error) if ok && aerr.Code() == s3.ErrCodeNoSuchKey { // Specific error code handling } return err }

// Make sure to close the body when done with it for S3 GetObject APIs or // will leak connections. defer result.Body.Close()

fmt.Println(“Object Size:”, aws.Int64Value(result.ContentLength))“`

API Request Pagination and Resource Waiters

Pagination helper methods are suffixed with “Pages”, and provide thefunctionality needed to round trip API page requests. Pagination methodstake a callback function that will be called for each page of the API’s response.

“`go objects := []string{} err := svc.ListObjectsPagesWithContext(ctx, &s3.ListObjectsInput{ Bucket: aws.String(myBucket), }, func(p *s3.ListObjectsOutput, lastPage bool) bool { for _, o := range p.Contents { objects = append(objects, aws.StringValue(o.Key)) } return true // continue paging }) if err != nil { panic(fmt.Sprintf(“failed to list objects for bucket, %s, %v”, myBucket, err)) }

fmt.Println(“Objects in bucket:”, objects)“`

Waiter helper methods provide the functionality to wait for an AWS resourcestate. These methods abstract the logic needed to check the state of anAWS resource, and wait until that resource is in a desired state. The waiterwill block until the resource is in the state that is desired, an error occurs,or the waiter times out. If a resource times out the error code returned willbe request.WaiterResourceNotReadyErrorCode.

go err := svc.WaitUntilBucketExistsWithContext(ctx, &s3.HeadBucketInput{ Bucket: aws.String(myBucket), }) if err != nil { aerr, ok := err.(awserr.Error) if ok && aerr.Code() == request.WaiterResourceNotReadyErrorCode { fmt.Fprintf(os.Stderr, "timed out while waiting for bucket to exist") } panic(fmt.Errorf("failed to wait for bucket to exist, %v", err)) } fmt.Println("Bucket", myBucket, "exists")

Complete SDK Example

This example shows a complete working Go file which will upload a file to S3and use the Context pattern to implement timeout logic that will cancel therequest if it takes too long. This example highlights how to use sessions,create a service client, make a request, handle the error, and process theresponse.

“`go package main

import ( “context” “flag” “fmt” “os” “time”

"github.com/aws/aws-sdk-go/aws""github.com/aws/aws-sdk-go/aws/awserr""github.com/aws/aws-sdk-go/aws/request""github.com/aws/aws-sdk-go/aws/session""github.com/aws/aws-sdk-go/service/s3"

)

// Uploads a file to S3 given a bucket and object key. Also takes a duration // value to terminate the update if it doesn’t complete within that time. // // The AWS Region needs to be provided in the AWS shared config or on the // environment variable as AWS_REGION. Credentials also must be provided // Will default to shared config file, but can load from environment if provided. // // Usage: // # Upload myfile.txt to myBucket/myKey. Must complete within 10 minutes or will fail // go run withContext.go -b mybucket -k myKey -d 10m < myfile.txt func main() { var bucket, key string var timeout time.Duration

flag.StringVar(&bucket, "b", "", "Bucket name.")flag.StringVar(&key, "k", "", "Object key name.")flag.DurationVar(&timeout, "d", 0, "Upload timeout.")flag.Parse()// All clients require a Session. The Session provides the client with// shared configuration such as region, endpoint, and credentials. A// Session should be shared where possible to take advantage of// configuration and credential caching. See the session package for// more information.sess := session.Must(session.NewSession())// Create a new instance of the service's client with a Session.// Optional aws.Config values can also be provided as variadic arguments// to the New function. This option allows you to provide service// specific configuration.svc := s3.New(sess)// Create a context with a timeout that will abort the upload if it takes// more than the passed in timeout.ctx := context.Background()var cancelFn func()if timeout > 0 {    ctx, cancelFn = context.WithTimeout(ctx, timeout)}// Ensure the context is canceled to prevent leaking.// See context package for more information, https://golang.org/pkg/context/if cancelFn != nil {    defer cancelFn()}// Uploads the object to S3. The Context will interrupt the request if the// timeout expires._, err := svc.PutObjectWithContext(ctx, &s3.PutObjectInput{    Bucket: aws.String(bucket),    Key:    aws.String(key),    Body:   os.Stdin,})if err != nil {    if aerr, ok := err.(awserr.Error); ok && aerr.Code() == request.CanceledErrorCode {        // If the SDK can determine the request or retry delay was canceled        // by a context the CanceledErrorCode error code will be returned.        fmt.Fprintf(os.Stderr, "upload canceled due to timeout, %vn", err)    } else {        fmt.Fprintf(os.Stderr, "failed to upload object, %vn", err)    }    os.Exit(1)}fmt.Printf("successfully uploaded file to %s/%sn", bucket, key)

}“`

License

This SDK is distributed under theApache License, Version 2.0,see LICENSE.txt and NOTICE.txt for more information.

To restore the repository download the bundle

wget https://archive.org/download/github.com-aws-aws-sdk-go_-_2019-11-09_00-42-16/aws-aws-sdk-go_-_2019-11-09_00-42-16.bundle

and run:

 git clone aws-aws-sdk-go_-_2019-11-09_00-42-16.bundle 

Source: https://github.com/aws/aws-sdk-go
Uploader: aws
Upload date: 2019-11-09