aws-sdk-go - aws-sdk-go 是适用于 Go 编程语言的官方 AWS 开发工具包。

Created at: 2014-12-05 13:29:41
Language: Go
License: Apache-2.0

适用于 Go 的 AWS 开发工具包

接口参考 在 https://gitter.im/aws/aws-sdk-go 加入聊天 构建状态 Apache V2 许可证

aws-sdk-go 是用于 Go 编程语言的官方 AWS 开发工具包。

查看我们的发行说明,了解有关添加到 SDK 的最新错误修复、更新和功能的信息。

我们宣布了适用于 Go 的 AWS 开发工具包 V2 (v2) 的正式发布。v2 SDK 源可在 https://github.com/aws/aws-sdk-go-v2 中找到。查看 v2 开发工具包的开发人员指南以开始使用适用于 Go 的 AWS 开发工具包,或者如果你已使用版本 1,请查看迁移指南

跳转到:

开始

安装

用于检索 SDK 以将其添加到工作区或项目的 Go 模块依赖项。

go get
GOPATH

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

若要更新 SDK,请使用 检索最新版本的 SDK。

go get -u

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

依赖

SDK 包含一个文件夹,其中包含 SDK 的运行时依赖项。SDK 依赖项的元数据可以在 Go 模块文件或 Dep 文件中找到。

vendor
go.mod
Gopkg.toml

Go 模块

如果你使用的是 Go 模块,则默认为 SDK 的最新标记发布版本。若要获取 SDK 的特定发布版本,请在命令中使用。

go get
@<tag>
go get

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

要获取最新的 SDK 存储库更改,请使用 。

@latest

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

围棋 1.5

如果你在未启用供应商的情况下使用 Go 1.5,(),则需要在检索 SDK 时使用 以获取其依赖项。

GO15VENDOREXPERIMENT=1
...

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

这仍将包括该文件夹。如果你的环境未使用该文件夹,则可以删除该文件夹。

vendor
vendor

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

快速示例

完整的开发工具包示例

此示例显示了一个完整的工作 Go 文件,该文件会将文件上传到 S3,并使用上下文模式实现超时逻辑,如果请求时间过长,将取消请求。此示例重点介绍如何使用会话、创建服务客户端、发出请求、处理错误以及处理响应。

  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, %v\n", err)
  		} else {
  			fmt.Fprintf(os.Stderr, "failed to upload object, %v\n", err)
  		}
  		os.Exit(1)
  	}

  	fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key)
  }

开发工具包包概述

SDK 由两个主要组件组成,即 SDK 核心和服务客户端。开发工具包核心包在开发工具包根目录下的 aws 包下全部可用。受支持的 AWS 服务的每个客户端都可以在开发工具包根目录下的服务文件夹下自己的包中使用。

  • aws - 开发工具包核心,提供常见的共享类型,例如配置、记录器和实用程序,以便更轻松地使用 API 参数。

    • awserr - 提供 SDK 将用于 SDK 处理过程中发生的所有错误的错误接口。这也包括服务 API 响应错误。错误类型由代码和消息组成。将开发工具包返回的错误类型强制转换为 awserr。错误并调用 Code 方法将返回的错误与特定错误代码进行比较。有关可提取的其他值(如 RequestID),请参阅包的文档。

    • 凭证 - 提供开发工具包将用于检索 AWS 凭证以发出 API 请求的类型和内置凭证提供程序。嵌套在此文件夹下的还有其他凭证提供程序,例如用于代入 IAM 角色的 stscreds 和用于 EC2 实例角色的 ec2rolecreds 。

    • 终端节点 - 提供开发工具包的 AWS 区域和终端节点元数据。使用它来查找 AWS 服务终端节点信息,例如哪些服务位于某个区域以及服务所在的区域。还为所有区域标识符提供了常量,例如“us-west-2”的 UsWest2RegionID。

    • session - 提供初始默认配置,并从外部源(如环境和共享凭据文件)加载配置。

    • request - 提供 SDK 的 API 请求发送和重试逻辑。此软件包还包括用于定义你自己的请求重试程序以及配置 SDK 处理请求的方式的实用程序。

  • 服务 - 适用于 AWS 服务的客户端。SDK 支持的所有服务都在此文件夹下可用。

如何使用开发工具包的 AWS 服务客户端

开发工具包包括可用于向 AWS 服务 API 发出请求的 Go 类型和实用程序。在开发工具包根目录下的服务文件夹中,你将找到开发工具包支持的每个 AWS 服务的程序包。所有服务客户端都遵循通用的创建和使用模式。

为 AWS 服务创建客户端时,首先需要构造会话值。会话提供可在服务客户端之间共享的共享配置。创建服务客户端后,你可以通过 aws 传入其他配置。配置类型,用于覆盖会话中提供的配置,以使用自定义配置创建服务客户端实例。

创建服务的客户端后,你可以使用它向 AWS 服务发出 API 请求。这些客户端可以安全地同时使用。

配置开发工具包

在适用于 Go 的 AWS 开发工具包中,你可以配置服务客户端的设置,例如日志级别和最大重试次数。大多数设置是可选的;但是,对于每个服务客户端,你必须指定区域和凭据。开发工具包使用这些值将请求发送到正确的 AWS 区域,并使用正确的凭证对请求进行签名。你可以将这些值指定为会话的一部分或环境变量。

有关详细信息,请参阅 SDK 的配置指南

有关如何将会话与 SDK 配合使用的更多信息,请参阅会话包文档。

有关配置选项的更多信息,请参阅 aws 软件包中的配置类型。

配置凭据

使用开发工具包时,你通常需要 AWS 凭证才能使用 AWS 服务进行身份验证。SDK 支持多种支持这些凭据的方法。默认情况下,SDK 将自动从其默认凭据链中获取凭据。有关此链以及如何配置它的更多信息,请参阅会话包。凭据链中的常见项如下:

  • 环境凭据 - 为特定角色创建子进程时非常有用的环境变量集。

  • 共享凭据文件 (~/.aws/credentials) - 此文件根据配置文件名称存储凭据,对于本地开发非常有用。

  • EC2 实例角色凭证 - 使用 EC2 实例角色将凭证分配给在 EC2 实例上运行的应用程序。这样就无需在生产环境中管理凭据文件。

还可以通过在代码中配置凭据,也可以通过将配置的凭据值设置为自定义提供程序或使用 SDK 附带的提供程序之一绕过默认凭据链并使用自定义凭据链来配置凭据。当你想要指示 SDK 仅使用一组特定的凭据或提供程序时,这非常有用。

此示例创建一个凭证提供程序,用于代入 IAM 角色“myRoleARN”,并将 S3 服务客户端配置为将该角色用于 API 请求。

  // 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})

有关 SDK 附带的凭据提供程序以及如何自定义 SDK 的凭据用法的详细信息,请参阅凭据包文档。

SDK 支持共享配置文件 (~/.aws/config)。可以通过设置环境变量“AWS_SDK_LOAD_CONFIG=1”或在通过选项的 SharedConfigState 参数创建会话时在代码中启用该功能来启用此支持。

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

配置 AWS 区域

除了凭证之外,你还需要指定开发工具包将用于向其发出 AWS API 请求的区域。在 SDK 中,你可以使用环境变量指定区域,也可以在创建会话或服务客户端时直接在代码中指定区域。如果以多种方式指定区域,则代码中指定的最后一个值优先。

要通过环境变量设置区域,请将“AWS_REGION”设置为你希望 SDK 使用的区域。使用此方法设置区域将允许你在多个区域中运行应用程序,而无需在应用程序中使用其他代码来选择区域。

AWS_REGION=us-west-2

终端节点包包含 SDK 知道的所有区域的常量。这些值都以区域 ID 为后缀。这些值非常有用,因为它们减少了手动键入区域字符串的需要。

要在会话上设置区域,请使用 aws 软件包的 Config 结构参数区域到你希望从会话创建的服务客户端使用的 AWS 区域。当你想要创建多个服务客户端,并且所有客户端都向同一区域发出 API 请求时,这非常有用。

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

有关 AWS 区域和终端节点元数据,请参阅终端节点包。

除了在创建会话时设置区域外,还可以在每个服务客户端基础上设置区域。这将覆盖会话的区域。当你希望在与会话区域不同的特定区域中创建服务客户端时,这非常有用。

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

有关更多信息和其他选项,例如设置终端节点和其他服务客户端配置选项,请参阅 aws 软件包中的配置类型。

发出 API 请求

创建客户端后,你可以向服务发出 API 请求。每个 API 方法都采用一个输入参数,并返回服务响应和错误。SDK 提供了以多种方式进行 API 调用的方法。

在此列表中,我们将使用 S3 ListObjects API 作为发出 API 请求的不同方式的示例。

  • 列表对象 - 将向服务发出 API 请求的基本 API 操作。

  • ListObjectsRequest - 后缀为 Request 的 API 方法将构造 API 请求,但不发送它。当你想要获取请求的预签名 URL 并共享预签名 URL 而不是直接发出请求的应用程序时,这也很有用。

  • ListObjectsPages - 与基本 API 操作相同,但使用回调自动处理 API 响应的分页。

  • ListObjectsWithContext - 与基本 API 操作相同,但增加了对上下文模式的支持。这有助于控制飞行中请求的取消。有关更多信息,请参阅 Go 标准库上下文包。此方法还将请求包的 Option 功能选项作为可变参数,用于修改请求的发出方式或从原始 HTTP 响应中提取信息。

  • ListObjectsPagesWithContext - 与ListObjectsPages相同,但增加了对Context模式的支持。与 ListObjectsWithContext 类似,此方法也将请求包的 Option 函数选项类型作为可变参数。

除了 API 操作之外,开发工具包还包括几个更高级别的方法,这些方法抽象地检查和等待 AWS 资源处于所需状态。在此列表中,我们将使用 WaitUntilBucketExists 来演示不同形式的服务员。

  • WaitUntilBucketExists.- 发出 API 请求以查询 AWS 服务以获取资源状态的方法。完成该状态后将成功返回。

  • WaitUntilBucketExistsWithContext - 与 WaitUntilBucketExists 相同,但增加了对上下文模式的支持。此外,这些方法采用请求包的 WaiterOptions 来配置服务员,以及 SDK 将如何发出底层请求。

API 方法将记录服务可能为操作返回的错误代码。这些错误也将在服务客户端的包中以“ErrCode”为前缀的 const 字符串提供。如果 API 的开发工具包文档中未列出任何错误,则需要查阅 AWS 服务的 API 文档,了解可能返回的错误。

  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 请求分页和资源服务员

分页帮助程序方法后缀为“页面”,并提供往返 API 页面请求所需的功能。分页方法采用一个回调函数,该函数将为 API 响应的每个页面调用。

   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)

服务员帮助程序方法提供等待 AWS 资源状态的功能。这些方法抽象出检查 AWS 资源状态所需的逻辑,并等待该资源处于所需状态。服务员将阻塞,直到资源处于所需状态、发生错误或服务员超时。如果资源超时,返回的错误代码将是请求。WaiterResourceNotReadyErrorCode.

  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")

获取帮助

请使用这些社区资源获取帮助。我们使用 GitHub 问题来跟踪错误和功能请求。

  • StackOverflow 上提出一个问题,并使用 aws-sdk-go 标签对其进行标记。
  • 快来加入 gitter 上的 AWS 开发工具包 Go 社区聊天。
  • AWS Support 提交支持票证。
  • 如果你认为你可能发现了错误,请打开一个问题

此开发工具包实施 AWS 服务 API。有关 AWS 服务及其限制的一般问题,你还可以查看亚马逊云科技论坛

开放问题

如果你在使用 AWS 开发工具包 Go 时遇到错误,我们希望听到它。搜索现有问题,看看其他人是否也遇到该问题,然后再打开新问题。请包括适用于 Go 的 AWS 开发工具包版本、Go 语言和你正在使用的操作系统。在适当的时候,也请包括复制案例。

GitHub 问题适用于错误报告和功能请求。有关使用 AWS 开发工具包 Go 的帮助和问题,请使用获取帮助部分中列出的资源。精简未解决的问题列表将有助于我们及时做出响应。

贡献

我们努力为我们的 AWS 服务提供高质量且有用的开发工具包,并且我们非常重视社区的反馈和贡献。在提交任何问题拉取请求之前,请查看我们的贡献指南,以确保我们拥有有效响应你的错误报告或贡献的所有必要信息。

SDK 主要版本的维护和支持

有关维护和支持开发工具包主要版本和底层依赖项的信息,请参阅 AWS 开发工具包和工具共享配置和凭证参考指南中的以下内容:

资源

开发人员指南 - 本文档是有关如何使用 SDK 配置和发出请求的一般介绍。如果这是你第一次使用 SDK,本文档和 API 文档将帮助你入门。本文档重点介绍 SDK 的语法和行为。服务开发人员指南将帮助你开始使用特定的 AWS 服务。

开发工具包 API 参考文档 - 使用此文档查找开发工具包支持的 AWS 服务的所有 API 操作输入和输出参数。API 参考还包括 SDK 的文档,以及如何使用 SDK、服务客户端 API 操作和 API 操作需要参数的示例。

服务文档 - 使用此文档了解如何与 AWS 服务交互。这些指南非常适合开始使用服务或查找有关服务的更多信息。虽然此文档不是编码所必需的,但服务可能会提供有用的示例以供注意。

开发工具包示例 - 开发工具包的存储库中包含几个使用开发工具包功能和 AWS 服务手工制作的示例。

论坛 - 提出问题、获取帮助并提供反馈

问题 - 报告问题、提交拉取请求并参与其中(请参阅 Apache 2.0 许可证)