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

# 域数据集组入门 (SDK for Java 2.x)
<a name="domain-getting-started-java"></a>

本教程向您展示如何使用 SDK for Java 2.x 为 VIDEO\$1ON\$1DEMAND 域创建域数据集组。在本教程中，您将为*热门精选* 使用案例创建推荐器。

完成入门练习后，为避免产生不必要的费用，请删除您创建的资源。有关更多信息，请参阅 [删除 Amazon Personalize 资源的要求](deleting-resources.md)。

## 先决条件
<a name="domain-gs-java-prerequisites"></a>

以下是完成本教程的先决条件步骤：
+ 完成[入门先决条件](gs-prerequisites.md)，设置所需权限并创建训练数据。如果您还完成了[域数据集组入门（控制台）](getting-started-console-domain.md)，则可以重复使用相同的源数据。如果您使用自己的源数据，请确保按照先决条件中的步骤设置数据格式。
+ 设置 SDK for Java 2.x 环境和 Amazon 凭证，如《Amazon SDK for Java 2.x 开发人员指南》**中的[设置 Amazon SDK for Java 2.x](https://docs.amazonaws.cn/sdk-for-java/latest/developer-guide/setup.html) 过程所述。

## 教程
<a name="gs-java-domain-tutorial"></a>

在以下步骤中，您将项目设置为使用 Amazon Personalize 程序包并创建 Amazon Personalize SDK for Java 2.x 客户端。然后，导入数据，为*热门精选* 使用案例创建推荐器，并获得建议。

### 步骤 1：设置您的项目以使用 Amazon Personalize 程序包
<a name="domain-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;
   // recommender packages
   import software.amazon.awssdk.services.personalize.model.CreateRecommenderRequest;
   import software.amazon.awssdk.services.personalize.model.CreateRecommenderResponse;
   import software.amazon.awssdk.services.personalize.model.DescribeRecommenderRequest;
   // 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="domain-gs-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="domain-gs-java-import-dataset"></a>

初始化 Amazon Personalize 客户端后，导入您在完成[入门先决条件](gs-prerequisites.md)时创建的历史数据。要将历史数据导入 Amazon Personalize，请执行以下操作：

1.  将以下 Avro 架构作为 JSON 文件保存到您的工作目录中。此架构与您在完成[创建训练数据（域数据集组）](gs-prerequisites.md#gs-data-prep-domain)时创建的 CSV 文件中的列相匹配。

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

1. 使用以下 `createDomainSchema` 方法创建 Amazon Personalize 域架构。将以下内容作为参数传递：Amazon Personalize 服务客户端、架构名称、域的 `VIDEO_ON_DEMAND`，以及您在上一步中创建的架构 JSON 文件的文件路径。该方法将返回新架构的 Amazon 资源名称 (ARN)。请将其存储以便将来使用。

   ```
       public static String createDomainSchema(PersonalizeClient personalizeClient, String schemaName, String domain,
               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)
                       .domain(domain)
                       .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. 创建数据集组。使用以下 `createDomainDatasetGroup` 方法创建域数据集组。将以下内容作为参数传递：Amazon Personalize 服务客户端、数据集组的名称以及域的传递 `VIDEO_ON_DEMAND`。该方法将返回新数据集组的 ARN。请将其存储以便将来使用。

   ```
       public static String createDomainDatasetGroup(PersonalizeClient personalizeClient,
               String datasetGroupName,
               String domain) {
   
           try {
               CreateDatasetGroupRequest createDatasetGroupRequest = CreateDatasetGroupRequest.builder()
                       .name(datasetGroupName)
                       .domain(domain)
                       .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="domain-gs-create-recommender"></a>

数据集导入作业完成后，您就可以创建推荐器了。使用以下 `createRecommender` 方法创建推荐器。将以下内容作为参数传递：Amazon Personalize 服务客户端、推荐器的名称、数据集组的 Amazon 资源名称 (ARN) 以及食谱 ARN 的 `arn:aws:personalize:::recipe/aws-vod-top-picks`。该方法将返回新推荐器的 ARN。请将其存储以便将来使用。

```
    public static String createRecommender(PersonalizeClient personalizeClient,
            String name,
            String datasetGroupArn,
            String recipeArn) {

        long maxTime = 0;
        long waitInMilliseconds = 30 * 1000; // 30 seconds
        String recommenderStatus = "";

        try {
            CreateRecommenderRequest createRecommenderRequest = CreateRecommenderRequest.builder()
                    .datasetGroupArn(datasetGroupArn)
                    .name(name)
                    .recipeArn(recipeArn)
                    .build();

            CreateRecommenderResponse recommenderResponse = personalizeClient
                    .createRecommender(createRecommenderRequest);
            String recommenderArn = recommenderResponse.recommenderArn();
            System.out.println("The recommender ARN is " + recommenderArn);

            DescribeRecommenderRequest describeRecommenderRequest = DescribeRecommenderRequest.builder()
                    .recommenderArn(recommenderArn)
                    .build();

            maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;

            while (Instant.now().getEpochSecond() < maxTime) {

                recommenderStatus = personalizeClient.describeRecommender(describeRecommenderRequest).recommender()
                        .status();
                System.out.println("Recommender status: " + recommenderStatus);

                if (recommenderStatus.equals("ACTIVE") || recommenderStatus.equals("CREATE FAILED")) {
                    break;
                }
                try {
                    Thread.sleep(waitInMilliseconds);
                } catch (InterruptedException e) {
                    System.out.println(e.getMessage());
                }
            }
            return recommenderArn;

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

### 步骤 5：获得建议
<a name="domain-gs-java-get-recommendations"></a>

创建推荐器后，您可以使用它来获取建议。使用以下 `getRecs` 方法为用户获取建议。将以下内容作为参数传递：Amazon Personalize 运行时客户端、您在上一步中创建的推荐器的 Amazon 资源名称 (ARN) 和用户 ID（例如 `123`）。该方法会在屏幕上打印出推荐物品列表。

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

        try {
            GetRecommendationsRequest recommendationsRequest = GetRecommendationsRequest.builder()
                    .recommenderArn(recommenderArn)
                    .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);
        }
    }
```