本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 網域資料集群組入門
在本入門教學課程中，您會為 VIDEO\$1ON\$1DEMAND 網域建立網域資料集群組、從 CSV 檔案匯入互動資料，以及使用*最適合您的*使用案例建立推薦者。然後，您可以使用 建議程式來取得使用者的個人化電影建議。本教學課程使用歷史資料，其中包含來自 600 位使用者的 9，700 部電影的 100，000 部電影評分。
若要開始，請完成 ，[入門先決條件](gs-prerequisites.md)然後根據您要建立 Amazon Personalize 資源的方式，繼續執行 [網域資料集群組入門 （主控台）](getting-started-console-domain.md)、[網域資料集群組入門 （適用於 Java 的 SDK 2.x)](domain-getting-started-java.md)、 [開始使用網域資料集群組 (SDK for Python (Boto3))](getting-started-domain-python.md)或 [網域資料集群組入門 (SDK for JavaScript v3)](getting-started-domain-js.md)。
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
**Topics**
+ [網域資料集群組入門 （主控台）](getting-started-console-domain.md)
+ [網域資料集群組入門 （適用於 Java 的 SDK 2.x)](domain-getting-started-java.md)
+ [開始使用網域資料集群組 (SDK for Python (Boto3))](getting-started-domain-python.md)
+ [網域資料集群組入門 (SDK for JavaScript v3)](getting-started-domain-js.md)
# 網域資料集群組入門 （主控台）
在本練習中，您可以使用 Amazon Personalize 主控台來建立網域資料集群組，以及傳回給指定使用者的電影建議的建議者。
開始本練習之前，請檢閱 [入門先決條件](gs-prerequisites.md)。
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
## 步驟 1：建立網域資料集群組
在此程序中，您會為 VIDEO\$1ON\$1DEMAND 網域建立網域資料集群組、使用 VIDEO\$1ON\$1DEMAND 網域的預設結構描述建立項目互動資料集，以及匯入您在 中建立的項目互動資料[建立訓練資料 （網域資料集群組）](gs-prerequisites.md#gs-data-prep-domain)。
**建立網域資料集群組**
1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。
1. 在導覽窗格中，選擇**建立資料集群組**。
1. 在**資料集群組詳細資訊**中，指定資料集群組的名稱。
1. 針對**網域**，選擇**隨選視訊**。您選擇的網域會決定您在匯入資料時使用的預設結構描述。它也會決定哪些使用案例可供推薦者使用。您的畫面如下所示。
![\[描述 使用名稱和網域欄位建立資料集群組頁面。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/gs-domain-1-create-dsg.png)
1. 選擇 **Create dataset group (建立資料集群組)**。概觀頁面隨即出現。繼續執行「[步驟 2：匯入資料](#getting-started-import-data-domain)」。
## 步驟 2：匯入資料
在此程序中，您會使用預設 VIDEO\$1ON\$1DEMAND 網域結構描述建立項目互動資料集。然後，匯入您在 中建立的項目互動資料[建立訓練資料 （網域資料集群組）](gs-prerequisites.md#gs-data-prep-domain)。
**匯入資料**
1. 在概觀頁面**的步驟 1 中。建立資料集和匯入資料**，選擇**建立資料集**，然後選擇**項目互動資料集**。
1. 選擇將**資料直接匯入 Amazon Personalize 資料集**，然後選擇**下一步**。
1. 在**設定項目互動結構描述**頁面上，**資料集名稱**提供項目互動資料集的名稱。
1. 對於**資料集結構描述**，請**修改網域的現有預設結構描述，並輸入結構描述的名稱，以選擇建立新網域**結構描述。**結構描述定義**會更新以顯示 VIDEO\$1ON\$1DEMAND 網域的預設結構描述。讓結構描述保持不變。您的畫面如下所示。
![\[描述使用資料集和結構描述欄位來設定項目互動結構描述頁面。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/gs-domain-2-create-dataset.png)
1. 選擇**下一步**。**設定項目互動資料集匯入任務**頁面隨即出現。
1. 在**設定項目互動資料集匯入任務**頁面上，將**資料匯入來源**保留為**從 S3 匯入資料**。
1. 對於**資料集匯入任務名稱**，請為您的匯入任務命名。
1. 在**資料匯入來源**中，指定資料存放在 Amazon Simple Storage Service (S3) 中的位置。使用下列語法：
**s3://amzn-s3-demo-bucket//**
1. 在 **IAM 角色**中，針對 **IAM 服務角色**選擇**輸入自訂 IAM 角色 ARN**，然後輸入您在 中建立之角色的 Amazon Resource Name (ARN)[為 Amazon Personalize 建立 IAM 角色](set-up-required-permissions.md#set-up-create-role-with-permissions)。您的畫面如下所示。
![\[顯示使用匯入任務欄位設定項目互動資料集匯入任務頁面。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/gs-domain-3-import-job.png)
1. 選擇**開始匯入**以匯入資料。網域資料集群組的**概觀**頁面隨即出現。在**設定資料集**區段中記下匯入的狀態。當狀態`Interaction data active`進入 時[步驟 3：建立推薦者](#getting-started-console-create-recommenders)。
## 步驟 3：建立推薦者
在此程序中，您會為 VIDEO\$1ON\$1DEMAND 網域的使用案例建立*最佳挑選*的推薦者。
**建立推薦者**
1. 在網域資料集群組的**概觀**頁面上，在**步驟 3** 選擇**隨需使用影片建議程式**索引標籤，然後選擇**建立建議程式**。
1. 在**選擇使用案例**頁面上，選擇**最適合您的選項**，並提供**建議者名稱**。您的畫面應如下所示。
![\[顯示選擇使用案例頁面，其中包含要選擇的清單使用案例選項。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/gs-domain-4-create-recommender.png)
1. 選擇**下一步**。
1. 將**進階組態**頁面上的欄位保持不變，然後選擇**下一步**。
1. 檢閱建議者詳細資訊，然後選擇**建立建議者**以建立您的建議者。
您可以在建議程式頁面上監控每個**建議程式**的狀態。當您的推薦者狀態為**作用中**時，您可以使用它在 中取得建議[步驟 4：取得建議](#getting-started-console-get-recommendations-domain)。
## 步驟 4：取得建議
在此程序中，您會使用您在上一個步驟中建立的建議程式來取得建議。
**取得建議**
1. 在網域資料集群組的概觀頁面上，於導覽窗格中選擇**建議者**。
1. 在**建議者**頁面上，選擇您的建議者。
1. 在右上角，選擇**測試**。
1. 在**建議參數**中，輸入使用者 ID。保留其他欄位不變。
1. 選擇 **Get recommendations (取得建議)**。包含使用者前 25 個建議項目的資料表隨即出現。您的畫面如下所示。
![\[顯示測試建議程式頁面，其中包含建議請求的欄位。\]](http://docs.aws.amazon.com/zh_tw/personalize/latest/dg/images/gs-domain-5-get-recc.png)
# 網域資料集群組入門 （適用於 Java 的 SDK 2.x)
本教學課程說明如何使用適用於 Java 的 SDK 2.x 為 VIDEO\$1ON\$1DEMAND 網域建立網域資料集群組。在本教學課程中，您會為使用案例建立*最佳挑選*的推薦者。
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
## 先決條件
以下是完成本教學課程的先決條件步驟：
+ 完成 [入門先決條件](gs-prerequisites.md)以設定所需的許可並建立訓練資料。如果您也已完成 [網域資料集群組入門 （主控台）](getting-started-console-domain.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 登入資料。
## 教學課程
在下列步驟中，您將專案設定為使用 Amazon Personalize 套件，並建立 Amazon Personalize SDK for Java 2.x 用戶端。然後，您可以匯入資料、為您使用案例建立*最佳挑選*的建議者，並取得建議。
### 步驟 1：設定您的專案以使用 Amazon Personalize 套件
完成先決條件後，請將 Amazon Personalize 相依性新增至 pom.xml 檔案，並匯入 Amazon Personalize 套件。
1. 將下列相依性新增至 pom.xml 檔案。最新版本號碼可能與範例程式碼不同。
```
software.amazon.awssdk
personalize
2.16.83
software.amazon.awssdk
personalizeruntime
2.16.83
software.amazon.awssdk
personalizeevents
2.16.83
```
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 用戶端
將 Amazon Personalize 相依性新增至 pom.xml 檔案並匯入必要的套件後，請建立下列 Amazon Personalize 用戶端：
```
PersonalizeClient personalizeClient = PersonalizeClient.builder()
.region(region)
.build();
PersonalizeRuntimeClient personalizeRuntimeClient = PersonalizeRuntimeClient.builder()
.region(region)
.build();
```
### 步驟 3：匯入資料
在您初始化 Amazon Personalize 用戶端之後，匯入您完成 時建立的歷史資料[入門先決條件](gs-prerequisites.md)。若要將歷史資料匯入 Amazon Personalize，請執行下列動作：
1. 將下列 Avro 結構描述儲存為工作目錄中的 JSON 檔案。此結構描述符合您在完成 時所建立 CSV 檔案中的資料欄[建立訓練資料 （網域資料集群組）](gs-prerequisites.md#gs-data-prep-domain)。
```
{
"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 Resource Name (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：建立推薦者
資料集匯入任務完成後，您就可以建立建議者。使用下列`createRecommender`方法來建立推薦者。傳遞下列參數：Amazon Personalize 服務用戶端、建議者的名稱、資料集群組的 Amazon Resource Name (ARN)，以及`arn:aws:personalize:::recipe/aws-vod-top-picks`配方 ARN。方法會傳回新推薦者的 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：取得建議
建立建議程式之後，您可以使用它來取得建議。使用下列`getRecs`方法取得使用者的建議。將 做為參數傳遞給 Amazon Personalize 執行期用戶端、您在上一個步驟中建立的推薦者的 Amazon Resource Name (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 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);
}
}
```
# 開始使用網域資料集群組 (SDK for Python (Boto3))
本教學課程說明如何使用適用於 Python 的 SDK (Boto3) 為 VIDEO\$1ON\$1DEMAND 網域建立網域資料集群組。在本教學課程中，您會為使用案例建立*最佳挑選*的推薦者。
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
**Topics**
+ [先決條件](#gs-sdk-domain-prerequisites)
+ [教學課程](#gs-python-tutorial)
+ [開始使用 Amazon Personalize APIs搭配 Jupyter (iPython) 筆記本](#gs-jupyter-domain-notebook)
## 先決條件
以下是在本指南中使用 Python 範例的先決條件：
+ 完成 [入門先決條件](gs-prerequisites.md)以設定所需的許可並建立訓練資料。如果您使用的是自己的來源資料，請確定您的資料格式與先決條件相同。
+ 依照 中的指定設定您的 適用於 Python (Boto3) 的 AWS SDK 環境[設定 AWS SDKs](aws-personalize-set-up-sdks.md)。
## 教學課程
在下列步驟中，您會驗證您的環境，並為 Amazon Personalize 建立適用於 Python (Boto3) 的 SDK 用戶端。然後，您可以匯入資料、為您使用案例建立*最佳挑選*的建議者，並取得建議。
### 步驟 1：驗證您的 Python 環境並建立 boto3 用戶端
當您完成事前準備之後，請執行下列 Python 範例，以確認您的環境設定正確。此程式碼也會建立您在本教學課程中使用的 Amazon Personalize boto3 用戶端。如果您的環境設定正確，則會顯示可用配方的清單，而且您可以執行本教學課程中的其他範例。
```
import boto3
personalizeRt = boto3.client('personalize-runtime')
personalize = boto3.client('personalize')
response = personalize.list_recipes()
for recipe in response['recipes']:
print (recipe)
```
### 步驟 2：匯入資料
在您建立 Amazon Personalize boto3 用戶端並驗證環境之後，匯入您完成 時建立的歷史資料[入門先決條件](gs-prerequisites.md)。若要將歷史資料匯入 Amazon Personalize，請執行下列動作：
1. 使用下列程式碼在 Amazon Personalize 中建立結構描述。`gs-domain-interactions-schema` 將 取代為結構描述的名稱。
```
import json
schema = {
"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"
}
create_interactions_schema_response = personalize.create_schema(
name='gs-domain-interactions-schema',
schema=json.dumps(schema),
domain='VIDEO_ON_DEMAND'
)
interactions_schema_arn = create_interactions_schema_response['schemaArn']
print(json.dumps(create_interactions_schema_response, indent=2))
```
1. 使用下列程式碼建立資料集群組。`dataset group name` 將 取代為資料集群組的名稱。
```
response = personalize.create_dataset_group(
name = 'dataset group name',
domain = 'VIDEO_ON_DEMAND'
)
dsg_arn = response['datasetGroupArn']
description = personalize.describe_dataset_group(datasetGroupArn = dsg_arn)['datasetGroup']
print('Name: ' + description['name'])
print('ARN: ' + description['datasetGroupArn'])
print('Status: ' + description['status'])
```
1. 使用下列程式碼，在您的新資料集群組中建立項目互動資料集。為資料集命名，並提供先前步驟`dataset_group_arn`的 `schema_arn`和 。
```
response = personalize.create_dataset(
name = 'interactions-dataset-name',
schemaArn = interactions_schema_arn,
datasetGroupArn = dsg_arn,
datasetType = 'INTERACTIONS'
)
dataset_arn = response['datasetArn']
```
1. 使用以下程式碼，使用資料集匯入任務匯入您的資料。此程式碼使用 describe\$1dataset\$1import\$1job 方法來追蹤任務的狀態。
將下列項目做為參數傳遞：任務的名稱、上一個步驟`dataset_arn`的 、存放訓練資料的 Amazon S3 儲存貯體路徑 (`s3://bucket name/folder name/ratings.csv`)，以及 IAM 服務角色的 ARN。您已將此角色建立為 的一部分[入門先決條件](gs-prerequisites.md)。Amazon Personalize 需要存取儲存貯體的許可。如需授予存取權的詳細資訊，請參閱 [讓 Amazon Personalize 存取 Amazon S3 資源](granting-personalize-s3-access.md)。
```
import time
response = personalize.create_dataset_import_job(
jobName = 'JobName',
datasetArn = 'dataset_arn',
dataSource = {'dataLocation':'s3://amzn-s3-demo-bucket/filename.csv'},
roleArn = 'role_arn'
)
dataset_interactions_import_job_arn = response['datasetImportJobArn']
description = personalize.describe_dataset_import_job(
datasetImportJobArn = dataset_interactions_import_job_arn)['datasetImportJob']
print('Name: ' + description['jobName'])
print('ARN: ' + description['datasetImportJobArn'])
print('Status: ' + description['status'])
max_time = time.time() + 3*60*60 # 3 hours
while time.time() < max_time:
describe_dataset_import_job_response = personalize.describe_dataset_import_job(
datasetImportJobArn = dataset_interactions_import_job_arn
)
status = describe_dataset_import_job_response["datasetImportJob"]['status']
print("Interactions DatasetImportJob: {}".format(status))
if status == "ACTIVE" or status == "CREATE FAILED":
break
time.sleep(60)
```
### 步驟 4：建立推薦者
資料集匯入任務完成後，您就可以建立建議者。使用下列程式碼來建立推薦者。將以下內容做為參數傳遞：建議者的名稱、資料集群組的 Amazon Resource Name (ARN)，以及`arn:aws:personalize:::recipe/aws-vod-top-picks`配方 ARN。此程式碼使用 describe\$1recommender 方法來追蹤建議者的狀態。
```
import time
create_recommender_response = personalize.create_recommender(
name = 'gs-python-top-picks',
recipeArn = 'arn:aws:personalize:::recipe/aws-vod-top-picks',
datasetGroupArn = dsg_arn
)
recommender_arn = create_recommender_response['recommenderArn']
print('Recommender ARN:' + recommender_arn)
max_time = time.time() + 3*60*60 # 3 hours
while time.time() < max_time:
version_response = personalize.describe_recommender(
recommenderArn = recommender_arn
)
status = version_response["recommender"]["status"]
if status == "ACTIVE":
print("Creation succeeded for {}".format(recommender_arn))
elif status == "CREATE FAILED":
print("Creation failed for {}".format(recommender_arn))
if status == "ACTIVE":
break
else:
print("Recommender creation is still in progress")
time.sleep(60)
```
### 步驟 5：取得建議
建立推薦者之後，您可以使用它來取得具有下列程式碼的建議。以參數形式傳遞您在上一個步驟中建立的推薦者的 Amazon Resource Name (ARN)，以及使用者 ID （例如，`123`)。方法會列印建議項目的清單。
```
response = personalizeRt.get_recommendations(
recommenderArn = "arn:aws:personalize:us-west-2:014025156336:recommender/gs-python-top-picks-89",
userId = '123'
)
print("Recommended items")
for item in response['itemList']:
print (item['itemId'])
```
## 開始使用 Amazon Personalize APIs搭配 Jupyter (iPython) 筆記本
若要開始使用 Jupyter 筆記本建立網域資料集群組，請複製或下載一系列筆記本，這些筆記本位於 [Amazon Personalize 範例](https://github.com/aws-samples/amazon-personalize-samples)儲存庫的 [notebooks\$1managed\$1domains](https://github.com/aws-samples/amazon-personalize-samples/tree/master/getting_started/notebooks_managed_domains) 資料夾中。筆記本會逐步引導您匯入訓練資料、建立推薦者，以及使用 Amazon Personalize 取得建議。
**注意**
開始使用筆記本之前，請務必依照 https：//[README.md](https://github.com/aws-samples/amazon-personalize-samples/blob/master/getting_started/README.md) 中的步驟建置您的環境
# 網域資料集群組入門 (SDK for JavaScript v3)
本教學課程說明如何使用 適用於 JavaScript 的 AWS SDK v3 為 VIDEO\$1ON\$1DEMAND 網域建立網域資料集群組。在本教學課程中，您會為使用案例建立*最佳挑選*的推薦者。
若要在 GitHub 上檢視本教學中使用的程式碼，請參閱《SDK [程式碼範例儲存庫》中適用於 JavaScript v3 的 SDK 的 Amazon Personalize](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/personalize) 程式碼範例。* AWS *
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
**Topics**
+ [先決條件](#gs-js-sdk-domain-prerequisites)
+ [教學課程](#domain-gs-js-domain-tutorial)
## 先決條件
以下是完成本教學課程的先決條件步驟：
+ 完成 [入門先決條件](gs-prerequisites.md)以設定所需的許可並建立訓練資料。如果您也已完成 [網域資料集群組入門 （主控台）](getting-started-console-domain.md)，則可以重複使用相同的來源資料。如果您使用自己的來源資料，請確定您的資料格式與先決條件相同。
+ 如《 *適用於 JavaScript 的 AWS SDK 開發人員指南*》中的設定適用於 JavaScript 的 SDK 程序所指定，[設定適用於 JavaScript 的 SDK](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-up.html) 和 AWS 登入資料。
## 教學課程
在下列步驟中，您會安裝所需的相依性。然後，您可以建立資料集群組、匯入資料、為您使用案例建立*最佳挑選*的建議者，以及取得建議。
如果您使用 Node.js，您可以將範例儲存為 JavaScript 檔案，然後執行 ，以執行每個程式碼範例`node `。
### 步驟 1：安裝 Amazon Personalize 相依性
完成先決條件後，請安裝下列 Amazon Personalize 相依性：
+ @aws-sdk/client-personalize
+ @aws-sdk/client-personalize-runtime
+ @aws-sdk/client-personalize-events （本教學課程為選用，但如果您想要在建立推薦者後[記錄事件](recording-events.md)，則為必要）
以下是`package.json`您可以使用的檔案範例。若要使用 Node.js 安裝相依性，請導覽至您儲存`package.json`檔案的位置並執行 `npm install`。
```
{
"name": "personalize-js-project",
"version": "1.0.0",
"description": "personalize operations",
"type": "module",
"author": "Author Name ",
"license": "ISC",
"dependencies": {
"@aws-sdk/client-personalize": "^3.350.0",
"@aws-sdk/client-personalize-events": "^3.350.0",
"@aws-sdk/client-personalize-runtime": "^3.350.0",
"fs": "^0.0.1-security"
},
"compilerOptions": {
"resolveJsonModule": true,
"esModuleInterop": true
}
}
```
### 步驟 2：建立 Amazon Personalize 用戶端
安裝相依性之後，請建立 Amazon Personalize 用戶端。在本教學課程中，程式碼範例假設您在名為 的檔案中建立用戶端，該檔案`personalizeClients.js`存放在名為 的目錄中`libs`。
以下是 `personalizeClient.js` 檔案的範例。
```
import { PersonalizeClient } from "@aws-sdk/client-personalize";
import { PersonalizeRuntimeClient } from "@aws-sdk/client-personalize-runtime";
import { PersonalizeEventsClient } from "@aws-sdk/client-personalize-events";
// Set your AWS region.
const REGION = "region"; //e.g. "us-east-1"
const personalizeClient = new PersonalizeClient({ region: REGION});
const personalizeEventsClient = new PersonalizeEventsClient({ region: REGION});
const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: REGION});
export { personalizeClient, personalizeEventsClient, personalizeRuntimeClient };
```
### 步驟 3：匯入資料
建立 Amazon Personalize 用戶端後，匯入您在完成 時建立的歷史資料[入門先決條件](gs-prerequisites.md)。若要將歷史資料匯入 Amazon Personalize，請執行下列動作：
1. 將下列 Avro 結構描述儲存為工作目錄中的 JSON 檔案。此結構描述符合您在完成 時所建立 CSV 檔案中的資料欄[建立訓練資料 （網域資料集群組）](gs-prerequisites.md#gs-data-prep-domain)。
```
{
"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.js`程式碼在 Amazon Personalize 中建立網域結構描述。`SCHEMA_PATH` 將 取代為您剛建立之 schema.json 檔案的路徑。更新 `createSchemaParam`以指定結構描述的名稱，並`domain`指定 `VIDEO_ON_DEMAND`。
```
// Get service clients module and commands using ES6 syntax.
import { CreateSchemaCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
import fs from "node:fs";
const schemaFilePath = "SCHEMA_PATH";
let mySchema = "";
try {
mySchema = fs.readFileSync(schemaFilePath).toString();
} catch (err) {
mySchema = "TEST"; // for unit tests.
}
// Set the domain schema parameters.
export const createDomainSchemaParam = {
name: "NAME" /* required */,
schema: mySchema /* required */,
domain:
"DOMAIN" /* required for a domain dataset group, specify ECOMMERCE or VIDEO_ON_DEMAND */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateSchemaCommand(createDomainSchemaParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
1. 使用下列`createDomainDatasetGroup.js`程式碼在 Amazon Personalize 中建立網域資料集群組。更新 `domainDatasetGroupParams`以指定資料集群組的名稱，並`domain`指定 `VIDEO_ON_DEMAND`。
```
// Get service clients module and commands using ES6 syntax.
import { CreateDatasetGroupCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the domain dataset group parameters.
export const domainDatasetGroupParams = {
name: "NAME" /* required */,
domain:
"DOMAIN" /* required for a domain dsg, specify ECOMMERCE or VIDEO_ON_DEMAND */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateDatasetGroupCommand(domainDatasetGroupParams),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
1. 使用下列`createDataset.js`程式碼在 Amazon Personalize 中建立項目互動資料集。更新 `createDatasetParam`以指定您剛建立之資料集群組和結構描述的 Amazon Resource Name (ARN)，為資料集命名，並為 `datasetType`指定 `Interactions`。
```
// Get service clients module and commands using ES6 syntax.
import { CreateDatasetCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the dataset's parameters.
export const createDatasetParam = {
datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
datasetType: "DATASET_TYPE" /* required */,
name: "NAME" /* required */,
schemaArn: "SCHEMA_ARN" /* required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateDatasetCommand(createDatasetParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
1. 使用下列`createDatasetImportJob.js`程式碼匯入您的資料。更新 `datasetImportJobParam`以指定下列項目：
+ 指定任務的名稱，並指定互動資料集的 ARN。
+ 針對 `dataLocation`，指定您存放訓練資料的 Amazon S3 儲存貯體路徑 (`s3://https://amzn-s3-demo-bucket.s3.region-code.amazonaws.com/folder name/ratings.csv`)。
+ 針對 `roleArn`指定 Amazon Personalize 服務角色的 Amazon Resource Name。您已將此角色建立為 的一部分[入門先決條件](gs-prerequisites.md)。
```
// Get service clients module and commands using ES6 syntax.
import { CreateDatasetImportJobCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the dataset import job parameters.
export const datasetImportJobParam = {
datasetArn: "DATASET_ARN" /* required */,
dataSource: {
/* required */
dataLocation: "S3_PATH",
},
jobName: "NAME" /* required */,
roleArn: "ROLE_ARN" /* required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateDatasetImportJobCommand(datasetImportJobParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
### 步驟 4：建立推薦者
資料集匯入任務完成後，您就可以建立建議者。若要建立推薦者，請使用下列`createRecommender.js`程式碼。`createRecommenderParam` 使用下列項目更新 ：指定建議者的名稱、指定資料集群組的 ARN，以及`recipeArn`指定 `arn:aws:personalize:::recipe/aws-vod-top-picks`。
```
// Get service clients module and commands using ES6 syntax.
import { CreateRecommenderCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});
// Set the recommender's parameters.
export const createRecommenderParam = {
name: "NAME" /* required */,
recipeArn: "RECIPE_ARN" /* required */,
datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
};
export const run = async () => {
try {
const response = await personalizeClient.send(
new CreateRecommenderCommand(createRecommenderParam),
);
console.log("Success", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```
### 步驟 5：取得建議
建立推薦者之後，您可以使用它來取得建議。使用下列`getRecommendations.js`程式碼取得使用者的建議。更新 `getRecommendationsParam`以指定您在上一個步驟中建立之推薦者的 ARN，並指定使用者 ID （例如 `123`)。
```
// Get service clients module and commands using ES6 syntax.
import { GetRecommendationsCommand } from "@aws-sdk/client-personalize-runtime";
import { personalizeRuntimeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeRuntimeClient = new PersonalizeRuntimeClient({ region: "REGION"});
// Set the recommendation request parameters.
export const getRecommendationsParam = {
recommenderArn: "RECOMMENDER_ARN" /* required */,
userId: "USER_ID" /* required */,
numResults: 15 /* optional */,
};
export const run = async () => {
try {
const response = await personalizeRuntimeClient.send(
new GetRecommendationsCommand(getRecommendationsParam),
);
console.log("Success!", response);
return response; // For unit tests.
} catch (err) {
console.log("Error", err);
}
};
run();
```