開始使SDK用 (適用於 Java 2.x) - Amazon Personalize
必要條件完整的 Amazon Personalize 化

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

開始使SDK用 (適用於 Java 2.x)

本教程向您展示如何從頭到尾完成 Amazon Personalize 化工作流程 AWS SDK for Java 2.x.

完成入門練習後，若要避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱刪除 Amazon Personalize 化資源的要求。

如需更多範例，請參閱完整的 Amazon Personalize 化。

必要條件

以下是完成此教學課程的先決條件步驟：

教學課程

在以下步驟中，您將項目設置為使用 Amazon Personalize 化軟件包，並SDK為 Java 2.x 客戶端創建 Amazon Personalize 化。然後，您可以匯入資料、建立和部署含有行銷活動的解決方案版本，以及取得建議。

完成先決條件後，將 Amazon 個人化相依性新增至您的 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>

  2. 將以下導入語句添加到您的項目中。

    // 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;

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

PersonalizeClient personalizeClient = PersonalizeClient.builder()
  .region(region)
  .build();

PersonalizeRuntimeClient personalizeRuntimeClient = PersonalizeRuntimeClient.builder() 
  .region(region)
  .build();

在您初始 Amazon Personalize 用戶端之後，請匯入您在完成入門先決條件. 若要將歷史資料匯入 Amazon Personalize，請執行下列操作：

  1. 將下列 Avro 結構描述儲存為工作目錄中的JSON檔案。此結構描述與您在完成時建立的CSV檔案中的欄相符入門先決條件。

    {
  "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"
}

  2. 使用以下createSchema方法在 Amazon Personalize 化中創建模式。將下列項目當做參數傳遞：Amazon Personalize 服務用戶端、結構描述的名稱，以及您在上一個步驟中建立的結構描述JSON檔案的檔案路徑。該方法返回您的新模式的 Amazon 資源名稱（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 "";
    }

  3. 建立資料集群組。使用下列createDatasetGroup方法建立資料集群組。將下列項目當做參數傳遞：Amazon 個人化服務用戶端和資料集群組的名稱。此方法會傳回新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 "";
    }

  4. 建立項目互動資料集。使用下列createDataset方法建立 Item 互動資料集。將下列項目當做參數傳遞：Amazon Personalize 服務用戶端、資料集的名稱ARN、結構描述、資料集群組以及Interactions資料集類型。ARN此方法會傳回新資料集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 "";
    }

  5. 使用資料集匯入工作匯入資料。使用下列createPersonalizeDatasetImportJob方法建立資料集匯入工作。

    將下列項目當作參數傳遞：Amazon Personalize 服務用戶端、任務名稱、您的項目互動資料集ARN、存放訓練資料的 Amazon S3 儲存貯體路徑 (s3://bucket name/folder name/ratings.csv)，以及您的服務角色 ARN (您建立此角色作為其中的一部分入門先決條件)。此方法會傳回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 "";
    }

匯入資料之後，您可以建立解決方案和解決方案版本，如下所示。該解決方案包含用於訓練模型的配置，解決方案版本是訓練有素的模型。

  1. 使用以下createPersonalizeSolution方法創建一個新的解決方案。將下列項目當做參數傳遞：Amazon Personalize 服務用戶端、您的資料集將 Amazon 資源名稱 (ARN) 分組、解決方案的名稱，以及使用者個人化 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 "";
    }

  2. 使用下列方法建立解決createPersonalizeSolutionVersion方案版本。作為上一步ARN的解決方案的參數傳遞。下列程式碼會先檢查您的解決方案是否已準備就緒，然後建立解決方案版本。在訓練期間，程式碼會使用DescribeSolutionVersion作業來擷取解決方案版本的狀態。訓練完成後，此方法會傳回新解決方案版本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 "";
    }

如需詳細資訊，請參閱手動建立解決方案版本。建立解決方案版本時，您可以在繼續之前評估其效能。如需詳細資訊，請參閱使用指標評估 Amazon Personalize 解決方案版本。

在訓練和評估解決方案版本之後，請使用 Amazon 個人化行銷活動進行部署。使用下列createPersonalCampaign方法部署解決方案版本。將下列項目當做參數傳遞：Amazon 個人化服務用戶端、您在上一步中建立的解決方案版本的 Amazon 資源名稱 (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 解決方案版本。

建立行銷活動後，您可以使用它來取得建議。使用下列getRecs方法取得使用者的建議。作為參數傳遞 Amazon Personalize 執行時間用戶端、您在上一步中建立的廣告活動的 Amazon 資源名稱 (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 化

對於向您 all-in-one 展示如何使用 Java 2.x 完成 Amazon Personalize 化工作流程的SDK項目，請參閱上的 Amazon 個性化 Java 應用程序。 GitHub該項目包括使用不同配方培訓多個解決方案版本，並記錄 PutEvents 操作的事件。

如需其他範例，請參閱的個人化資料夾中找到的程式碼 AWS SDK實例存儲庫。