本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 開始使用適用於 Kotlin 的 SDK
<a name="get-started"></a>

為每個 適用於 Kotlin 的 AWS SDK 提供 Kotlin APIs AWS 服務。您可以使用 SDK 建置可搭配 Amazon S3、Amazon EC2、Amazon DynamoDB 等使用的 Kotlin 應用程式。

本教學課程說明如何使用 Gradle 來定義 的相依性 適用於 Kotlin 的 AWS SDK。然後，您可以建立程式碼，將資料寫入 DynamoDB 資料表。雖然您可能想要使用 IDE 的功能，但本教學課程只需要終端機視窗和文字編輯器。

請依照下列步驟完成本教學課程：
+  [步驟 1：設定本教學課程](#get-started-setup) 
+  [步驟 2：建立專案](#get-started-projectsetup) 
+  [步驟 3：撰寫程式碼](#get-started-code) 
+  [步驟 4：建置並執行應用程式](#get-started-run) 

## 步驟 1：設定本教學課程
<a name="get-started-setup"></a>

開始本教學課程之前，您需要可以存取 DynamoDB 的 [IAM Identity Center 許可集](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetsconcept.html)，而且需要以 IAM Identity Center 單一登入設定設定的 Kotlin 開發環境才能存取 AWS。

請依照[基本設定](setup-basic-onetime-setup.md)本指南中的指示，取得本教學課程的基本設定。

使用 Kotlin SDK [的單一登入存取](setup-basic-onetime-setup.md#setup-sso-access)設定開發環境，並擁有[作用中的 AWS 存取入口網站工作階段](setup-basic-onetime-setup.md#setup-login-sso)後，請繼續步驟 2。

## 步驟 2：建立專案
<a name="get-started-projectsetup"></a>

若要建立本教學課程的專案，請先使用 Gradle 為 Kotlin 專案建立基本檔案。然後，使用 所需的設定、相依性和程式碼來更新檔案 適用於 Kotlin 的 AWS SDK。

 **使用 Gradle 建立新專案** 

**注意**  
本教學課程使用 Gradle 8.11.1 版搭配 `gradle init`命令，在下面的步驟 3 中提供五個提示。如果您使用不同的 Gradle 版本，提示和預先填入的成品版本可能不同。

1. 在您選擇的`getstarted`位置建立新的目錄，例如桌面或主資料夾。

1. 開啟終端機或命令提示視窗，然後導覽至您建立的`getstarted`目錄。

1. 使用以下命令建立新的 Gradle 專案和基本 Kotlin 類別。

   ```
   gradle init --type kotlin-application --dsl kotlin
   ```
   + 當系統提示輸入目標 時`Java version`，按 `Enter`（預設為 `21`)。
   + 出現 提示時`Project name`，按 `Enter`（在本教學`getstarted`課程中預設為目錄名稱）。
   + 出現提示時`application structure`，按 `Enter`（預設為 `Single application project`)。
   + 出現 提示時`Select test framework`，按 `Enter`（預設為 `kotlin.test`)。
   + 出現 提示時`Generate build using new APIs and behavior`，按 `Enter`（預設為 `no`)。

 **使用 和 適用於 Kotlin 的 AWS SDK Amazon S3 的相依性來設定專案 ** 
+ 在您先前程序中建立的`getstarted`目錄中，將`settings.gradle.kts`檔案的內容取代為下列內容，將 {{X.Y.Z}} 取代為最新版本[https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest)的適用於 Kotlin 的 SDK：

  ```
  dependencyResolutionManagement {
      repositories {
          mavenCentral()
      }
  
      versionCatalogs {
          create("awssdk") {
              from("aws.sdk.kotlin:version-catalog:[https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest)")
          }
      }
  }
  
  plugins {
      // Apply the foojay-resolver plugin to allow automatic download of JDKs.
      id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
  }
  
  rootProject.name = "getstarted"
  include("app")
  ```
+ 導覽至 `gradle`目錄內的 `getstarted`目錄。將名為 的版本目錄檔案的內容取代`libs.versions.toml`為下列內容：

  ```
  [versions]
  junit-jupiter-engine = "5.10.3"
  
  [libraries]
  junit-jupiter-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit-jupiter-engine" }
  
  [plugins]
  kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version = "2.1.0" }
  ```
+ 導覽至 `app` 目錄並開啟 `build.gradle.kts` 檔案。將其內容替換為下列程式碼，然後儲存您的變更：

  ```
  plugins {
      alias(libs.plugins.kotlin.jvm)
      application
  }
  
  
  dependencies {
      implementation(awssdk.services.s3) // Add dependency on the 適用於 Kotlin 的 AWS SDK's S3 client.
  
      testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
      testImplementation(libs.junit.jupiter.engine)
      testRuntimeOnly("org.junit.platform:junit-platform-launcher")
  }
  
  java {
      toolchain {
          languageVersion = JavaLanguageVersion.of(21)
      }
  }
  
  application {
      mainClass = "org.example.AppKt"
  }
  
  tasks.named<Test>("test") {
      useJUnitPlatform()
  }
  ```

  `dependencies` 區段包含 Amazon S3 模組的 `implementation`項目 適用於 Kotlin 的 AWS SDK。Gradle 編譯器在 `java`區段中設定為使用 Java 21。

## 步驟 3：撰寫程式碼
<a name="get-started-code"></a>

建立並設定專案之後，請編輯專案的預設類別`App`，以使用下列範例程式碼。

1. 在您的專案資料夾中`app`，導覽至目錄 `src/main/kotlin/org/example`。開啟 `App.kt` 檔案。

1. 以下列程式碼取代其內容並儲存檔案。

   ```
   package org.example
   
   import aws.sdk.kotlin.services.s3.*
   import aws.sdk.kotlin.services.s3.model.BucketLocationConstraint
   import aws.smithy.kotlin.runtime.content.ByteStream
   import kotlinx.coroutines.runBlocking
   import java.util.UUID
   
   val REGION = "us-west-2"
   val BUCKET = "bucket-${UUID.randomUUID()}"
   val KEY = "key"
   
   fun main(): Unit = runBlocking {
       S3Client
           .fromEnvironment { region = REGION }
           .use { s3 ->
               setupTutorial(s3)
   
               println("Creating object $BUCKET/$KEY...")
   
               s3.putObject {
                   bucket = BUCKET
                   key = KEY
                   body = ByteStream.fromString("Testing with the Kotlin SDK")
               }
   
               println("Object $BUCKET/$KEY created successfully!")
   
               cleanUp(s3)
           }
   }
   
   suspend fun setupTutorial(s3: S3Client) {
       println("Creating bucket $BUCKET...")
       s3.createBucket {
           bucket = BUCKET
           if (REGION != "us-east-1") { // Do not set location constraint for us-east-1.
               createBucketConfiguration {
                   locationConstraint = BucketLocationConstraint.fromValue(REGION)
               }
           }
       }
       println("Bucket $BUCKET created successfully!")
   }
   
   suspend fun cleanUp(s3: S3Client) {
       println("Deleting object $BUCKET/$KEY...")
       s3.deleteObject {
           bucket = BUCKET
           key = KEY
       }
       println("Object $BUCKET/$KEY deleted successfully!")
   
       println("Deleting bucket $BUCKET...")
       s3.deleteBucket {
           bucket = BUCKET
       }
       println("Bucket $BUCKET deleted successfully!")
   }
   ```

## 步驟 4：建置並執行應用程式
<a name="get-started-run"></a>

建立專案並包含範例類別之後，請建置並執行應用程式。

1. 開啟終端機或命令提示視窗，然後導覽至您的專案目錄 `getstarted`。

1. 使用下列命令來建置和執行您的應用程式：

   ```
   gradle run
   ```

**注意**  
如果您取得 `IdentityProviderException`，您可能沒有作用中的單一登入工作階段。執行 `aws sso login` AWS CLI 命令來啟動新的工作階段。

應用程式會呼叫 [createBucket](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/create-bucket.html) API 操作來建立新的 S3 儲存貯體，然後呼叫 [putObject](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/s3/aws.sdk.kotlin.services.s3/put-object.html) 將新物件放入新的 S3 儲存貯體。

在結束時的 `cleanUp()`函數中，應用程式會刪除物件，然後刪除 S3 儲存貯體。

 **在 Amazon S3 主控台中查看結果** 

1. 在 中`App.kt`，註解`runBlocking`區段`cleanUp(s3)`中的行，並儲存檔案。

1. 執行 來重建專案，並將新物件放入新的 S3 儲存貯體`gradle run`。

1. 登入 [Amazon S3 主控台](https://console.aws.amazon.com/s3)，以檢視新 S3 儲存貯體中的新物件。

檢視物件之後，請刪除 S3 儲存貯體。

### 成功
<a name="get-started-success"></a>

如果您的 Gradle 專案建置並執行時沒有錯誤，恭喜您。您已成功使用 建置第一個 Kotlin 應用程式 適用於 Kotlin 的 AWS SDK。

### 清除
<a name="cleanup"></a>

當您完成開發新的應用程式時，請刪除您在本教學課程中建立的任何 AWS 資源，以避免產生任何費用。您也可以刪除或封存您在步驟 2 中建立的專案資料夾 (`get-started`)。

請依照下列步驟清除資源：
+ 如果您已對 `cleanUp()`函數的呼叫進行註解，請使用 Amazon S3 主控台刪除 S3 儲存貯體。 [Amazon S3 ](https://console.aws.amazon.com/s3)

## 後續步驟
<a name="get-started-next"></a>

現在您已完成基本概念，您可以了解以下內容：
+  [使用適用於 Kotlin 的 SDK 的其他設定步驟](setup.md) 
+  [適用於 Kotlin 的 SDK 組態](configuration.md) 
+  [使用適用於 Kotlin 的 SDK](using.md) 
+  [適用於 Kotlin 的 SDK 安全性](security.md)