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

# 入門 （適用於 Java 的 SDK 2.x)
<a name="getting-started-java"></a>

本教學課程說明如何從頭到尾完成 Amazon Personalize 工作流程 AWS SDK for Java 2.x。

當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。

如需更多範例，請參閱[完成 Amazon Personalize 專案](#gs-java-example)。

**Topics**
+ [先決條件](#gs-java-prerequisites)
+ [完成 Amazon Personalize 專案](#gs-java-example)

## 先決條件
<a name="gs-java-prerequisites"></a>

以下是完成本教學課程的先決條件步驟：
+ 完成 [入門先決條件](gs-prerequisites.md)，以設定所需的許可並建立訓練資料。您可以使用與 [開始使用 (主控台)](getting-started-console.md)或 [開始使用 (AWS CLI)](getting-started-cli.md)練習中使用的相同來源資料。如果您使用自己的來源資料，請確定您的資料格式與先決條件相同。
+ 如《 *AWS SDK for Java 2.x 開發人員指南*》中的[設定 AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html)程序所指定，設定適用於 Java 的 SDK 2.x 環境和 AWS 登入資料。

### 教學課程
<a name="gs-custom-java-tutorial"></a>

在下列步驟中，您將專案設定為使用 Amazon Personalize 套件，並建立 Amazon Personalize SDK for Java 2.x 用戶端。然後，您可以匯入資料、使用行銷活動建立和部署解決方案版本，以及取得建議。

#### 步驟 1：設定您的專案以使用 Amazon Personalize 套件
<a name="gs-java-set-up-project"></a>

完成先決條件後，請將 Amazon Personalize 相依性新增至 pom.xml 檔案，並匯入 Amazon Personalize 套件。

1.  將下列相依性新增至您的 pom.xml 檔案。最新版本號碼可能與範例程式碼不同。

   ```
   <dependency>
   	<groupId>software.amazon.awssdk</groupId>
   	<artifactId>personalize</artifactId>
   	<version>2.16.83</version>
   </dependency>
   <dependency>
   	<groupId>software.amazon.awssdk</groupId>
   	<artifactId>personalizeruntime</artifactId>
   	<version>2.16.83</version>
   </dependency>
   <dependency>
   	<groupId>software.amazon.awssdk</groupId>
   	<artifactId>personalizeevents</artifactId>
   	<version>2.16.83</version>
   </dependency>
   ```

1.  將下列匯入陳述式新增至您的專案。

   ```
   // import client packages
   import software.amazon.awssdk.services.personalize.PersonalizeClient;
   import software.amazon.awssdk.services.personalizeruntime.PersonalizeRuntimeClient;
   // Amazon Personalize exception package
   import software.amazon.awssdk.services.personalize.model.PersonalizeException;
   // schema packages
   import software.amazon.awssdk.services.personalize.model.CreateSchemaRequest;
   // dataset group packages
   import software.amazon.awssdk.services.personalize.model.CreateDatasetGroupRequest;
   import software.amazon.awssdk.services.personalize.model.DescribeDatasetGroupRequest;
   // dataset packages
   import software.amazon.awssdk.services.personalize.model.CreateDatasetRequest;
   // dataset import job packages
   import software.amazon.awssdk.services.personalize.model.CreateDatasetImportJobRequest;
   import software.amazon.awssdk.services.personalize.model.DataSource;
   import software.amazon.awssdk.services.personalize.model.DatasetImportJob;
   import software.amazon.awssdk.services.personalize.model.DescribeDatasetImportJobRequest;
   // solution packages
   import software.amazon.awssdk.services.personalize.model.CreateSolutionRequest;
   import software.amazon.awssdk.services.personalize.model.CreateSolutionResponse;
   // solution version packages
   import software.amazon.awssdk.services.personalize.model.DescribeSolutionRequest;
   import software.amazon.awssdk.services.personalize.model.CreateSolutionVersionRequest;
   import software.amazon.awssdk.services.personalize.model.CreateSolutionVersionResponse;
   import software.amazon.awssdk.services.personalize.model.DescribeSolutionVersionRequest;
   // campaign packages
   import software.amazon.awssdk.services.personalize.model.CreateCampaignRequest;
   import software.amazon.awssdk.services.personalize.model.CreateCampaignResponse;
   // get recommendations packages
   import software.amazon.awssdk.services.personalizeruntime.model.GetRecommendationsRequest;
   import software.amazon.awssdk.services.personalizeruntime.model.GetRecommendationsResponse;
   import software.amazon.awssdk.services.personalizeruntime.model.PredictedItem;
   // Java time utility package
   import java.time.Instant;
   ```

#### 步驟 2：建立 Amazon Personalize 用戶端
<a name="getting-started-java-clients"></a>

將 Amazon Personalize 相依性新增至 pom.xml 檔案並匯入必要的套件後，請建立下列 Amazon Personalize 用戶端：

```
PersonalizeClient personalizeClient = PersonalizeClient.builder()
  .region({{region}})
  .build();

PersonalizeRuntimeClient personalizeRuntimeClient = PersonalizeRuntimeClient.builder() 
  .region({{region}})
  .build();
```

#### 步驟 3：匯入資料
<a name="getting-started-java-import-dataset"></a>

在您初始化 Amazon Personalize 用戶端之後，匯入您完成 時建立的歷史資料[入門先決條件](gs-prerequisites.md)。若要將歷史資料匯入 Amazon Personalize，請執行下列動作：

1.  將下列 Avro 結構描述儲存為工作目錄中的 JSON 檔案。此結構描述與您完成 時建立的 CSV 檔案中的資料欄相符[入門先決條件](gs-prerequisites.md)。

   ```
   {
     "type": "record",
     "name": "Interactions",
     "namespace": "com.amazonaws.personalize.schema",
     "fields": [
         {
             "name": "USER_ID",
             "type": "string"
         },
         {
             "name": "ITEM_ID",
             "type": "string"
         },
         {
             "name": "TIMESTAMP",
             "type": "long"
         }
     ],
     "version": "1.0"
   }
   ```

1. 使用下列`createSchema`方法在 Amazon Personalize 中建立結構描述。傳遞下列參數：Amazon Personalize 服務用戶端、結構描述的名稱，以及您在上一個步驟中建立之結構描述 JSON 檔案的檔案路徑。方法會傳回新結構描述的 Amazon Resource Name (ARN)。存放它以供日後使用。

   ```
       public static String createSchema(PersonalizeClient personalizeClient, String schemaName, String filePath) {
   
           String schema = null;
           try {
               schema = new String(Files.readAllBytes(Paths.get(filePath)));
           } catch (IOException e) {
               System.out.println(e.getMessage());
           }
   
           try {
               CreateSchemaRequest createSchemaRequest = CreateSchemaRequest.builder()
                       .name(schemaName)
                       .schema(schema)
                       .build();
   
               String schemaArn = personalizeClient.createSchema(createSchemaRequest).schemaArn();
   
               System.out.println("Schema arn: " + schemaArn);
   
               return schemaArn;
   
           } catch (PersonalizeException e) {
               System.err.println(e.awsErrorDetails().errorMessage());
               System.exit(1);
           }
           return "";
       }
   ```

1. 建立資料集群組。使用下列`createDatasetGroup`方法建立資料集群組。將以下內容做為參數傳遞：Amazon Personalize 服務用戶端和資料集群組的名稱。方法會傳回新資料集群組的 ARN。存放它以供日後使用。

   ```
       public static String createDatasetGroup(PersonalizeClient personalizeClient, String datasetGroupName) {
   
           try {
               CreateDatasetGroupRequest createDatasetGroupRequest = CreateDatasetGroupRequest.builder()
                       .name(datasetGroupName)
                       .build();
               return personalizeClient.createDatasetGroup(createDatasetGroupRequest).datasetGroupArn();
           } catch (PersonalizeException e) {
               System.out.println(e.awsErrorDetails().errorMessage());
           }
           return "";
       }
   ```

1. 建立項目互動資料集。使用下列`createDataset`方法建立項目互動資料集。將下列項目做為參數傳遞：Amazon Personalize 服務用戶端、資料集的名稱、結構描述的 ARN、資料集群組的 ARN，以及`Interactions`資料集類型。方法會傳回新資料集的 ARN。存放它以供日後使用。

   ```
       public static String createDataset(PersonalizeClient personalizeClient,
               String datasetName,
               String datasetGroupArn,
               String datasetType,
               String schemaArn) {
           try {
               CreateDatasetRequest request = CreateDatasetRequest.builder()
                       .name(datasetName)
                       .datasetGroupArn(datasetGroupArn)
                       .datasetType(datasetType)
                       .schemaArn(schemaArn)
                       .build();
   
               String datasetArn = personalizeClient.createDataset(request)
                       .datasetArn();
               System.out.println("Dataset " + datasetName + " created.");
               return datasetArn;
   
           } catch (PersonalizeException e) {
               System.err.println(e.awsErrorDetails().errorMessage());
               System.exit(1);
           }
           return "";
       }
   ```

1. 使用資料集匯入任務匯入您的資料。使用下列`createPersonalizeDatasetImportJob`方法建立資料集匯入任務。

   將以下內容做為參數傳遞：Amazon Personalize 服務用戶端、任務的名稱、項目互動資料集的 ARN、存放訓練資料的 Amazon S3 儲存貯體路徑 (`s3://{{bucket name}}/{{folder name}}/ratings.csv`)，以及服務角色的 ARN （您建立此角色做為 的一部分[入門先決條件](gs-prerequisites.md))。方法會傳回資料集匯入任務的 ARN。選擇性地存放它以供日後使用。

   ```
       public static String createPersonalizeDatasetImportJob(PersonalizeClient personalizeClient,
               String jobName,
               String datasetArn,
               String s3BucketPath,
               String roleArn) {
   
           long waitInMilliseconds = 60 * 1000;
           String status;
           String datasetImportJobArn;
   
           try {
               DataSource importDataSource = DataSource.builder()
                       .dataLocation(s3BucketPath)
                       .build();
   
               CreateDatasetImportJobRequest createDatasetImportJobRequest = CreateDatasetImportJobRequest.builder()
                       .datasetArn(datasetArn)
                       .dataSource(importDataSource)
                       .jobName(jobName)
                       .roleArn(roleArn)
                       .build();
   
               datasetImportJobArn = personalizeClient.createDatasetImportJob(createDatasetImportJobRequest)
                       .datasetImportJobArn();
               DescribeDatasetImportJobRequest describeDatasetImportJobRequest = DescribeDatasetImportJobRequest.builder()
                       .datasetImportJobArn(datasetImportJobArn)
                       .build();
   
               long maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;
   
               while (Instant.now().getEpochSecond() < maxTime) {
   
                   DatasetImportJob datasetImportJob = personalizeClient
                           .describeDatasetImportJob(describeDatasetImportJobRequest)
                           .datasetImportJob();
   
                   status = datasetImportJob.status();
                   System.out.println("Dataset import job status: " + status);
   
                   if (status.equals("ACTIVE") || status.equals("CREATE FAILED")) {
                       break;
                   }
                   try {
                       Thread.sleep(waitInMilliseconds);
                   } catch (InterruptedException e) {
                       System.out.println(e.getMessage());
                   }
               }
               return datasetImportJobArn;
   
           } catch (PersonalizeException e) {
               System.out.println(e.awsErrorDetails().errorMessage());
           }
           return "";
       }
   ```

#### 步驟 4：建立解決方案
<a name="getting-started-java-create-solution"></a>

匯入資料後，您可以建立解決方案和解決方案版本，如下所示。*解決方案*包含訓練模型的組態，而*解決方案版本*是訓練過的模型。

1. 使用下列`createPersonalizeSolution`方法建立新的解決方案。將以下內容做為參數傳遞：Amazon Personalize 服務用戶端、您的資料集群組 Amazon Resource Name (ARN)、解決方案的名稱，以及 User-Personalization-v2 配方的 ARN (`arn:aws:personalize:::recipe/aws-user-personalization-v2`)。方法會傳回您新解決方案的 ARN。存放它以供日後使用。

   ```
       public static String createPersonalizeSolution(PersonalizeClient personalizeClient,
               String datasetGroupArn,
               String solutionName,
               String recipeArn) {
   
           try {
               CreateSolutionRequest solutionRequest = CreateSolutionRequest.builder()
                       .name(solutionName)
                       .datasetGroupArn(datasetGroupArn)
                       .recipeArn(recipeArn)
                       .build();
   
               CreateSolutionResponse solutionResponse = personalizeClient.createSolution(solutionRequest);
               return solutionResponse.solutionArn();
   
           } catch (PersonalizeException e) {
               System.err.println(e.awsErrorDetails().errorMessage());
               System.exit(1);
           }
           return "";
       }
   ```

1. 使用下列`createPersonalizeSolutionVersion`方法建立解決方案版本。將解決方案的 ARN 做為參數傳遞到上一個步驟。下列程式碼會先檢查您的解決方案是否已就緒，然後建立解決方案版本。在訓練期間，程式碼會使用 [DescribeSolutionVersion](API_DescribeSolutionVersion.md)操作來擷取解決方案版本的狀態。訓練完成後， 方法會傳回新解決方案版本的 ARN。存放它以供日後使用。

   ```
       public static String createPersonalizeSolutionVersion(PersonalizeClient personalizeClient, String solutionArn) {
           long maxTime = 0;
           long waitInMilliseconds = 30 * 1000; // 30 seconds
           String solutionStatus = "";
           String solutionVersionStatus = "";
           String solutionVersionArn = "";
   
           try {
               DescribeSolutionRequest describeSolutionRequest = DescribeSolutionRequest.builder()
                       .solutionArn(solutionArn)
                       .build();
   
               maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;
   
               // Wait until solution is active.
               while (Instant.now().getEpochSecond() < maxTime) {
   
                   solutionStatus = personalizeClient.describeSolution(describeSolutionRequest).solution().status();
                   System.out.println("Solution status: " + solutionStatus);
   
                   if (solutionStatus.equals("ACTIVE") || solutionStatus.equals("CREATE FAILED")) {
                       break;
                   }
                   try {
                       Thread.sleep(waitInMilliseconds);
                   } catch (InterruptedException e) {
                       System.out.println(e.getMessage());
                   }
               }
   
               if (solutionStatus.equals("ACTIVE")) {
   
                   CreateSolutionVersionRequest createSolutionVersionRequest = CreateSolutionVersionRequest.builder()
                           .solutionArn(solutionArn)
                           .build();
   
                   CreateSolutionVersionResponse createSolutionVersionResponse = personalizeClient
                           .createSolutionVersion(createSolutionVersionRequest);
                   solutionVersionArn = createSolutionVersionResponse.solutionVersionArn();
   
                   System.out.println("Solution version ARN: " + solutionVersionArn);
   
                   DescribeSolutionVersionRequest describeSolutionVersionRequest = DescribeSolutionVersionRequest.builder()
                           .solutionVersionArn(solutionVersionArn)
                           .build();
   
                   while (Instant.now().getEpochSecond() < maxTime) {
   
                       solutionVersionStatus = personalizeClient.describeSolutionVersion(describeSolutionVersionRequest)
                               .solutionVersion().status();
                       System.out.println("Solution version status: " + solutionVersionStatus);
   
                       if (solutionVersionStatus.equals("ACTIVE") || solutionVersionStatus.equals("CREATE FAILED")) {
                           break;
                       }
                       try {
                           Thread.sleep(waitInMilliseconds);
                       } catch (InterruptedException e) {
                           System.out.println(e.getMessage());
                       }
                   }
                   return solutionVersionArn;
               }
           } catch (PersonalizeException e) {
               System.err.println(e.awsErrorDetails().errorMessage());
               System.exit(1);
           }
           return "";
       }
   ```

如需詳細資訊，請參閱[手動建立解決方案版本](creating-a-solution-version.md)。當您建立解決方案版本時，您可以在繼續之前評估其效能。如需詳細資訊，請參閱[使用指標評估 Amazon Personalize 解決方案版本](working-with-training-metrics.md)。

#### 步驟 5：建立行銷活動
<a name="getting-started-java-deploy-solution"></a>

在您訓練和評估解決方案版本之後，請使用 Amazon Personalize 行銷活動進行部署。使用下列`createPersonalCampaign`方法部署解決方案版本。傳遞下列參數：Amazon Personalize 服務用戶端、您在上一個步驟中建立的解決方案版本的 Amazon Resource Name (ARN)，以及行銷活動的名稱。方法會傳回新行銷活動的 ARN。存放它以供日後使用。

```
public static String createPersonalCompaign(PersonalizeClient personalizeClient, String solutionVersionArn, String name) {

    try {
        CreateCampaignRequest createCampaignRequest = CreateCampaignRequest.builder()
            .minProvisionedTPS(1)
            .solutionVersionArn(solutionVersionArn)
            .name(name)
            .build();

        CreateCampaignResponse campaignResponse = personalizeClient.createCampaign(createCampaignRequest);
        System.out.println("The campaign ARN is "+campaignResponse.campaignArn());
        return campaignResponse.campaignArn();

    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}
```

如需 Amazon Personalize 行銷活動的詳細資訊，請參閱 [使用行銷活動部署 Amazon Personalize 解決方案版本建立行銷活動](campaigns.md)。

#### 步驟 6：取得建議
<a name="getting-started-java-get-recommendations"></a>

建立行銷活動後，您可以使用它來取得建議。使用下列`getRecs`方法取得使用者的建議。將 做為參數傳遞給 Amazon Personalize 執行期用戶端、您在上一個步驟中建立之行銷活動的 Amazon Resource Name (ARN)，以及您匯入的歷史資料中的使用者 ID （例如，`123`)。方法會將建議項目清單列印至畫面。

```
    public static void getRecs(PersonalizeRuntimeClient personalizeRuntimeClient, String campaignArn, String userId) {

        try {
            GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
                    .campaignArn(campaignArn)
                    .numResults(20)
                    .userId(userId)
                    .build();

            GetRecommendationsResponse recommendationsResponse = personalizeRuntimeClient
                    .getRecommendations(recommendationsRequest);
            List<PredictedItem> items = recommendationsResponse.itemList();
            for (PredictedItem item : items) {
                System.out.println("Item Id is : " + item.itemId());
                System.out.println("Item score is : " + item.score());
            }

        } catch (AwsServiceException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
    }
```

## 完成 Amazon Personalize 專案
<a name="gs-java-example"></a>

如需展示如何使用適用於 Java 的 SDK 2.x 完成 Amazon Personalize 工作流程all-in-one專案，請參閱 GitHub 上的 [Amazon-Personalize-Java-App](https://github.com/seashman/Amazon-Personalize-Java-App)。此專案包括使用不同的配方訓練多個解決方案版本，以及使用 PutEvents 操作記錄事件。

 如需其他範例，請參閱 AWS SDK 範例儲存庫[的個人化](https://github.com/awsdocs/aws-doc-sdk-examples/tree/master/javav2/example_code/personalize/src/main/java/com/example/personalize)資料夾中找到的程式碼。