开始使用 Amazon SDK for Java 2.x - Amazon SDK for Java 2.x
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

开始使用 Amazon SDK for Java 2.x

为 Amazon Web Services (Amazon) Amazon SDK for Java 2.x 提供了 Java API。使用 SDK,您可以构建与、 Amazon S3 Amazon EC2 DynamoDB、等配合使用的 Java 应用程序。

本教程向您展示了如何使用 Apache Maven 为适用于 Java 的 SDK 2.x 定义依赖项,然后编写用于连接 Amazon S3 以上传文件的代码。

要完成本教程,请执行以下步骤:

步骤 1:为本教程进行设置

在开始本教程之前,您需要具备:

  • 访问权限 Amazon S3

  • 配置为 Amazon Web Services 使用单点登录访问的 Java 开发环境 Amazon IAM Identity Center

请按照 设置概述 中的说明为本教程进行设置。在将开发环境配置为 Java SDK 的单点登录访问权限并且Amazon 访问门户会话处于活动状态后,请继续本教程的步骤 2。

步骤 2:创建项目

要为本教程创建项目,您需要运行一条 Maven 命令,该命令会提示您输入有关如何配置项目的信息。完成所有输入并进行确认后,Maven 通过创建 pom.xml 完成项目构建,并创建存根 Java 文件。

  1. 打开终端或命令提示符窗口,然后导航到您选择的目录,例如您的 DesktopHome 文件夹。

  2. 在终端中输入以下命令,然后按 Enter

    mvn archetype:generate \ -DarchetypeGroupId=software.amazon.awssdk \ -DarchetypeArtifactId=archetype-app-quickstart \ -DarchetypeVersion=2.20.43
  3. 为每个提示输入第二列中列出的值。

    提示 要输入的值
    Define value for property 'service': s3
    Define value for property 'httpClient': apache-client
    Define value for property 'nativeImage': false
    Define value for property 'credentialProvider' identity-center
    Define value for property 'groupId': org.example
    Define value for property 'artifactId': getstarted
    Define value for property 'version' 1.0-SNAPSHOT: <Enter>
    Define value for property 'package' org.example: <Enter>
  4. 输入最后一个值后,Maven 会列出您所做的选择。通过输入 Y 进行确认,或者通过输入 N 重新输入值。

Maven 会根据您输入的 artifactId 值创建名为 getstarted 的项目文件夹。在 getstarted 文件夹中,找到一个可以查看的 README.md 文件、一个 pom.xml 文件和一个 src 目录。

Maven 构建了以下目录树。

getstarted ├── README.md ├── pom.xml └── src ├── main │   ├── java │   │   └── org │   │   └── example │   │   ├── App.java │   │   ├── DependencyFactory.java │   │   └── Handler.java │   └── resources │   └── simplelogger.properties └── test └── java └── org └── example └── HandlerTest.java 10 directories, 7 files

下面显示的是 pom.xml 项目文件的内容。

dependencyManagement 部分包含一个 Amazon SDK for Java 2.x 依赖项,而 dependencies 部分包含一个 Amazon S3 依赖项。由于 maven.compiler.sourcemaven.compiler.target 属性中的值是 1.8,所以该项目使用 Java 1.8。

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.example</groupId> <artifactId>getstarted</artifactId> <version>1.0-SNAPSHOT</version> <packaging>jar</packaging> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <maven.shade.plugin.version>3.2.1</maven.shade.plugin.version> <maven.compiler.plugin.version>3.6.1</maven.compiler.plugin.version> <exec-maven-plugin.version>1.6.0</exec-maven-plugin.version> <aws.java.sdk.version>2.20.43</aws.java.sdk.version> <-------- SDK version picked up from archetype version. <slf4j.version>1.7.28</slf4j.version> <junit5.version>5.8.1</junit5.version> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>bom</artifactId> <version>${aws.java.sdk.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>s3</artifactId> <-------- S3 dependency <exclusions> <exclusion> <groupId>software.amazon.awssdk</groupId> <artifactId>netty-nio-client</artifactId> </exclusion> <exclusion> <groupId>software.amazon.awssdk</groupId> <artifactId>apache-client</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>sso</artifactId> <-------- Required for identity center authentication. </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>ssooidc</artifactId> <-------- Required for identity center authentication. </dependency> <dependency> <groupId>software.amazon.awssdk</groupId> <artifactId>apache-client</artifactId> <-------- HTTP client specified. <exclusions> <exclusion> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>${slf4j.version}</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>${slf4j.version}</version> </dependency> <!-- Needed to adapt Apache Commons Logging used by Apache HTTP Client to Slf4j to avoid ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl during runtime --> <dependency> <groupId>org.slf4j</groupId> <artifactId>jcl-over-slf4j</artifactId> <version>${slf4j.version}</version> </dependency> <!-- Test Dependencies --> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>${junit5.version}</version> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>${maven.compiler.plugin.version}</version> </plugin> </plugins> </build> </project>

步骤 3:编写代码

以下代码显示的是 Maven 创建的 App 类。main 方法是应用程序的入口点,它会创建 Handler 类的实例,然后调用其 sendRequest 方法。

package org.example; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class App { private static final Logger logger = LoggerFactory.getLogger(App.class); public static void main(String... args) { logger.info("Application starts"); Handler handler = new Handler(); handler.sendRequest(); logger.info("Application ends"); } }

Maven 创建的 DependencyFactory 类包含用于构建和返回 S3Client 实例的 s3Client 工厂方法。S3Client 实例使用基于 Apache 的 HTTP 客户端的实例。这是因为您在 Maven 提示您输入使用哪个 HTTP 客户端时指定了 apache-client

以下代码中显示了 DependencyFactory

package org.example; import software.amazon.awssdk.http.apache.ApacheHttpClient; import software.amazon.awssdk.services.s3.S3Client; /** * The module containing all dependencies required by the {@link Handler}. */ public class DependencyFactory { private DependencyFactory() {} /** * @return an instance of S3Client */ public static S3Client s3Client() { return S3Client.builder() .httpClientBuilder(ApacheHttpClient.builder()) .build(); } }

Handler 类包含程序的主要逻辑。在 App 类中创建 Handler 的实例时,DependencyFactory 将提供 S3Client 服务客户端。您的代码使用 S3Client 实例调用 Amazon S3 服务。

Maven 生成以下带有 TODO 注释的 Handler 类。本教程的下一步会将 TODO 替换为代码。

package org.example; import software.amazon.awssdk.services.s3.S3Client; public class Handler { private final S3Client s3Client; public Handler() { s3Client = DependencyFactory.s3Client(); } public void sendRequest() { // TODO: invoking the api calls using s3Client. } }

要填写逻辑,请将该 Handler 类的全部内容替换为以下代码。这将填写 sendRequest 方法并添加必要的导入。

该代码首先创建一个新的 S3 桶,其名称的最后一部分使用 System.currentTimeMillis() 生成,以使桶名称具有唯一性。

使用 createBucket() 方法创建桶后,程序将使用 S3ClientputObject 方法上传对象。对象的内容是使用 RequestBody.fromString 方法创建的简单字符串。

最后,程序使用 cleanUp 方法删除对象,然后删除桶。

package org.example; import software.amazon.awssdk.core.sync.RequestBody; import software.amazon.awssdk.services.s3.S3Client; import software.amazon.awssdk.services.s3.model.CreateBucketRequest; import software.amazon.awssdk.services.s3.model.DeleteBucketRequest; import software.amazon.awssdk.services.s3.model.DeleteObjectRequest; import software.amazon.awssdk.services.s3.model.HeadBucketRequest; import software.amazon.awssdk.services.s3.model.PutObjectRequest; import software.amazon.awssdk.services.s3.model.S3Exception; public class Handler { private final S3Client s3Client; public Handler() { s3Client = DependencyFactory.s3Client(); } public void sendRequest() { String bucket = "bucket" + System.currentTimeMillis(); String key = "key"; createBucket(s3Client, bucket); System.out.println("Uploading object..."); s3Client.putObject(PutObjectRequest.builder().bucket(bucket).key(key) .build(), RequestBody.fromString("Testing with the {sdk-java}")); System.out.println("Upload complete"); System.out.printf("%n"); cleanUp(s3Client, bucket, key); System.out.println("Closing the connection to {S3}"); s3Client.close(); System.out.println("Connection closed"); System.out.println("Exiting..."); } public static void createBucket(S3Client s3Client, String bucketName) { try { s3Client.createBucket(CreateBucketRequest .builder() .bucket(bucketName) .build()); System.out.println("Creating bucket: " + bucketName); s3Client.waiter().waitUntilBucketExists(HeadBucketRequest.builder() .bucket(bucketName) .build()); System.out.println(bucketName + " is ready."); System.out.printf("%n"); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } } public static void cleanUp(S3Client s3Client, String bucketName, String keyName) { System.out.println("Cleaning up..."); try { System.out.println("Deleting object: " + keyName); DeleteObjectRequest deleteObjectRequest = DeleteObjectRequest.builder().bucket(bucketName).key(keyName).build(); s3Client.deleteObject(deleteObjectRequest); System.out.println(keyName + " has been deleted."); System.out.println("Deleting bucket: " + bucketName); DeleteBucketRequest deleteBucketRequest = DeleteBucketRequest.builder().bucket(bucketName).build(); s3Client.deleteBucket(deleteBucketRequest); System.out.println(bucketName + " has been deleted."); System.out.printf("%n"); } catch (S3Exception e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } System.out.println("Cleanup complete"); System.out.printf("%n"); } }

步骤 4:构建并运行应用程序

在创建了包含完整 Handler 类的项目后,生成并运行该应用程序。

  1. 确保您的 IAM Identity Center 会话处于活动状态。为此,请运行 Amazon Command Line Interface 命令 aws sts get-caller-identity 并检查响应。如果您没有活动会话,请参阅此部分了解说明。

  2. 打开终端或命令提示符窗口并导航至您的项目目录 getstarted

  3. 使用以下命令生成项目:

    mvn clean package
  4. 使用以下命令运行应用程序。

    mvn exec:java -Dexec.mainClass="org.example.App"

要查看程序创建的新桶和对象,请执行以下步骤。

  1. Handler.java 中,注释掉 sendRequest 方法中的 cleanUp(s3Client, bucket, key) 行并保存文件。

  2. 运行 mvn clean package 以重新生成项目。

  3. 重新运行 mvn exec:java -Dexec.mainClass="org.example.App" 以再次上传文本对象。

  4. 登录 S3 控制台,在新创建的桶中查看新对象。

查看文件后,删除对象,然后删除桶。

成功

如果您的 Maven 项目生成和运行都没有错误,那么恭喜您!您已经使用适用于 Java 的 SDK 2.x 成功构建了您的第一个 Java 应用程序。

清理

要清除您在本教程中创建的资源,请执行以下操作:

  • S3 控制台中删除运行应用程序时创建的所有对象和所有桶(如果您尚未执行此操作)。

  • 删除项目文件夹 (getstarted)。

后续步骤

现在您已掌握了基础知识,接下来,您可以了解以下内容: