作业管理 API 参考 - AWS Snowball

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

作业管理 API 参考

适用于 AWS Snowball 的作业管理 API 是基于 HTTP (RFC 2616) 的网络协议。有关此 RFC 的更多信息,请参阅 IETF 网站上的 HTTP (RFC 2616)。对于作业管理 API 的每次调用,您需要向要管理作业的 AWS 区域的区域特定作业管理 API 端点发送 HTTP 请求。API 会对 HTTP 请求/响应正文使用 JSON (RFC 4627) 文档。

注意

在美国区域进行的用于列出工作或描述地址的 API 调用将返回该账户在美国境内的所有作业或地址。

适用于 Snowball 的作业管理 API 是一种 RPC 模型。在该模型中具有一套固定的操作,客户端已知每个操作的语法,而无需事先进行任何交互。在下文中,您可以使用一个抽象 RPC 表示找出各个 API 操作的说明以及不会在线显示的操作名称。对于每个操作,该主题指定了指向 HTTP 请求要素的映射。

某个给定请求所映射到的特定作业管理操作由请求方法 (GET、PUT、POST 或 DELETE) 以及与其请求-URI 匹配的模式共同确定。如果操作为 PUT 或 POST,则 Snowball 将从请求 URI 路径分段、查询参数和请求正文内的 JSON 对象中提取调用参数。

尽管操作名称(如 CreateJob)不会在线显示,但这些操作名称在 AWS Identity and Access Management (IAM) 策略中具有重要意义。操作名称还可用于为命令行工具中的命令和 AWS SDK API 的元素命名。例如,AWS Command Line Interface (AWS CLI) 命令 create-job 会映射到 CreateJob 操作。操作名称还会显示在 Snowball API 调用的 CloudTrail 日志中。

有关安装和设置 AWS CLI 的信息(包括指定要为其执行 AWS CLI 调用的地区),请参阅 AWS Command Line Interface用户指南

注意

作业管理 API 提供了与 AWS Snowball 管理控制台功能相同的编程接口,即为 Snowball 创建和管理作业。要使用 Snowball 设备在本地传输数据,请使用 Snowball 客户端或适用于 Snowball 的 S3 SDK 适配器。有关更多信息,请参阅 AWS Snowball 用户指南中的使用 Snowball 传输数据

如果您使用的是 Snowball Edge,请使用 Snowball 客户端解锁设备。有关更多信息,请参阅 AWS Snowball 开发人员指南中的使用 Snowball 客户端

API 端点

API 端点是指在 API 调用的 HTTP URI 中用作主机的域名服务 (DNS) 名称。这些 API 端点是特定于区域的,并采用以下形式。

snowball.aws-region.amazonaws.com

例如,以下是美国西部(俄勒冈州)区域的 Snowball API 服务的端点。

snowball.us-west-2.amazonaws.com

有关 Snowball 支持的 AWS 区域 列表(您可以在其中创建和管理作业),请参阅 AWS 一般参考 中的 AWS Import/Export

特定于区域的 API 端点会定义您在执行 API 调用时可以访问的 Snowball 资源范围。例如,当您使用上述端点调用 ListJobs 操作时,您将获得在您账户中创建的位于美国西部(俄勒冈州)区域的作业列表。

API 版本

用于调用的 API 版本是由请求 URI 的第一个路径分段确定的,并且其格式为 ISO 8601 日期。本文档中所描述的版本为 API 版本 2016-06-30。

API 权限策略参考

使用 Snowball 的作业管理 API 创建作业时,需要使用以下策略。

用于创建作业的角色信任策略

使用作业管理 API 创建作业时,需要使用以下信任策略。

{ "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "importexport.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "AWSIE" } } } ] }
注意

要了解有关信任策略的更多信息,请参阅 IAM 用户指南中的修改角色

用于创建导入作业的角色策略

创建导入作业时,需要使用以下角色策略。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::*" }, { "Effect": "Allow", "Action": [ "s3:GetBucketPolicy", "s3:PutObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::*" }, { "Effect": "Allow", "Action": [ "snowball:*" ], "Resource": [ "*" ] } ] }

用于创建导出作业的角色策略

创建导出作业时,需要使用以下角色策略。

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket" ], "Resource": "arn:aws:s3:::*" }, { "Effect": "Allow", "Action": [ "snowball:*" ], "Resource": [ "*" ] } ] }

用于创建作业的 Amazon S3 存储桶策略委托人

在某些情况下,您用于 Snowball 的 Amazon S3 存储桶所采用的存储桶策略要求列出代入角色的角色会话名称。在这些情况下,您需要在标识 AWSImportExport-Validation 的策略中指定一位委托人。以下示例 Amazon S3 存储桶策略展示了如何执行此操作。

{ "Version": "2012-10-17", "Statement": { "Sid": "Allow AWS Snowball To Create Jobs", "Effect": "Deny", "NotPrincipal": { "AWS": [ "arn:aws:iam::111122223333:role/rolename", "arn:aws:sts::111122223333:assumed-role/rolename/AWSImportExport-Validation", "arn:aws:iam::111122223333:root" ] }, "Action": "S3:*", "Resource": ["arn:aws:s3:::examplebucket/*"] } }

在此示例策略中,我们拒绝了除 NotPrincipal 元素中指定的委托人之外的所有委托人的访问。有关如何使用 NotPrincipal 的更多信息,请参阅 IAM 用户指南中的 NotPrincipal

注意

对于 AWS GovCloud (US) 中的作业,Snowball 将 AWSIEJob 用作代入角色的角色会话名称。

为 Snowball 和 Snowball Edge 创建 IAM 角色

创建的 IAM 角色策略必须拥有对 Amazon S3 存储桶的读写权限。IAM 角色还必须与 Snowball 有信任关系。拥有信任关系意味着 AWS 可以在 Snowball 和 Amazon S3 存储桶中写入数据,具体取决于您是导入数据还是导出数据。

在 AWS Snow 系列管理控制台 中创建作业时,在权限部分的步骤 4 中创建所需的 IAM 角色。此过程是自动的。您允许 Snowball 代入的 IAM 角色只用于在带有所传输数据的 Snowball 抵达 AWS 时将您的数据写入到存储桶。此流程包括下列步骤。

为导入作业创建 IAM 角色
  1. 登录 AWS Management Console,打开 AWS Snowball 控制台:https://console.aws.amazon.com/importexport/

  2. 请选择创建作业

  3. 在第一步中,在 Amazon S3 中填写导入作业的详细信息,然后选择下一步

  4. 在第二步中,在权限下选择创建/选择 IAM 角色

    IAM 管理控制台将打开,其中显示 AWS 用于将对象复制到您指定的 Amazon S3 存储桶的 IAM 角色。

  5. 检查此页上的详细信息,然后选择允许

    您将返回到 AWS Snow 系列管理控制台,其中选择的 IAM 角色 ARN 包含您刚刚创建的 IAM 角色的 Amazon 资源名称 (ARN)。

  6. 选择下一步完成创建您的 IAM 角色。

上述过程创建了一个对您计划将数据导入到的 Amazon S3 存储桶拥有写权限的 IAM 角色。创建的 IAM 角色具有以下结构之一,具体取决于它是用于导入作业还是用于导出作业。

用于导入作业的 IAM 角色

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:ListBucketMultipartUploads" ], "Resource": "arn:aws:s3:::*" }, { "Effect": "Allow", "Action": [ "s3:GetBucketPolicy", "s3:PutObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts", "s3:PutObjectAcl" ], "Resource": "arn:aws:s3:::*" } ] }

如果您使用带有 AWS KMS 托管密钥 (SSE-KMS) 的服务器端加密对与您的导出作业关联的 Amazon S3 存储桶进行加密,则您还需要将以下语句添加到您的 IAM 角色。

{ "Effect": "Allow", "Action": [ "kms:GenerateDataKey" ], "Resource": "arn:aws:s3:::SSEKMSEncryptedBucketName" }

用于导出作业的 IAM 角色

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetBucketPolicy", "s3:GetObject", "s3:ListBucket" ], "Resource": "arn:aws:s3:::*" } ] }

如果您使用带有 AWS KMS 托管密钥的服务器端加密对与您的导出作业关联的 Amazon S3 存储桶进行加密,则您还需要将以下语句添加到您的 IAM 角色。

{ "Effect": "Allow", "Action": [ “kms:Decrypt” ], "Resource": "arn:aws:s3:::SSEKMSEncryptedBucketName" }