本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 開始使用 (AWS CLI)
在本練習中，您會使用 AWS Command Line Interface (AWS CLI) 來探索 Amazon Personalize。您可以建立一個行銷活動，該活動會傳回針對特定使用者 ID 的電影建議。
開始本練習之前，請執行以下動作：
+ 檢閱入門[入門先決條件](gs-prerequisites.md)。
+ 設定 AWS CLI，如 中所指定[設定 AWS CLI](aws-personalize-set-up-aws-cli.md)。
當您完成入門練習時，為了避免產生不必要的費用，請刪除您建立的資源。如需詳細資訊，請參閱[刪除 Amazon Personalize 資源的需求](deleting-resources.md)。
**注意**
本練習中的 AWS CLI 命令已在 Linux 上測試。如需有關在 Windows 上使用 AWS CLI 命令的資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[指定 的參數值 AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html)。
## 步驟 1：匯入訓練資料
依照步驟建立資料集群組、將資料集新增至群組，然後使用電影評等資料填入資料集。
1. 執行以下命令來建立資料集群組。您可以透過傳遞[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html)金鑰 ARN 和 IAM 角色的 ARN 來加密資料集群組，該角色具有該金鑰的存取許可做為輸入參數。如需 API (匯入 API) 的詳細資訊，請參閱「[CreateDatasetGroup](API_CreateDatasetGroup.md)」。
```
aws personalize create-dataset-group --name MovieRatingDatasetGroup --kms-key-arn arn:aws:kms:us-west-2:01234567890:key/1682a1e7-a94d-4d92-bbdf-837d3b62315e --role-arn arn:aws:iam::01234567890:KMS-key-access
```
這時會顯示資料集群組 ARN，例如：
```
{
"datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup"
}
```
使用 `describe-dataset-group` 命令指定傳回的資料集群組 ARN，即可顯示您所建立的資料集。
```
aws personalize describe-dataset-group \
--dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup
```
這時會顯示資料集群組及其屬性，例如：
```
{
"datasetGroup": {
"name": "MovieRatingDatasetGroup",
"datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
"status": "ACTIVE",
"creationDateTime": 1542392161.262,
"lastUpdatedDateTime": 1542396513.377
}
}
```
**注意**
等到資料集群組的 `status` 顯示為 ACTIVE，再於群組中建立資料集。這個操作通常很快。
如果您不記得資料集群組 ARN，則可使用 `list-dataset-groups` 命令來顯示建立的所有資料集群組及其 ARN。
```
aws personalize list-dataset-groups
```
**注意**
`describe-object` 和 `list-objects`命令適用於大多數 Amazon Personalize 物件。這些命令沒有顯示在本練習的剩餘部分中，但它們是可用的。
1. 將以下程式碼儲存至名為 `MovieRatingSchema.json` 的檔案，來建立一個採用 JSON 格式的結構描述檔案。結構描述符合您之前新增到 `ratings.csv` 的標頭。結構描述名稱為 `Interactions`，符合 Amazon Personalize 辨識的其中一個資料集類型。如需詳細資訊，請參閱[為 Amazon Personalize 結構描述建立結構描述 JSON 檔案](how-it-works-dataset-schema.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. 執行以下命令來建立結構描述。指定您在上一個步驟中儲存的檔案。此範例會顯示屬於目前資料夾的檔案。如需 API (匯入 API) 的詳細資訊，請參閱「[CreateSchema](API_CreateSchema.md)」。
```
aws personalize create-schema \
--name MovieRatingSchema \
--schema file://MovieRatingSchema.json
```
這時會顯示 Amazon Resource Name (ARN)，例如：
```
{
"schemaArn": "arn:aws:personalize:us-west-2:acct-id:schema/MovieRatingSchema"
}
```
1. 執行以下命令來建立空的資料集。提供先前步驟中所傳回的資料集群組 ARN 和結構描述 ARN。`dataset-type` 必須符合前一個步驟中的結構描述 `name`。如需 API (匯入 API) 的詳細資訊，請參閱「[CreateDataset](API_CreateDataset.md)」。
```
aws personalize create-dataset \
--name MovieRatingDataset \
--dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup \
--dataset-type Interactions \
--schema-arn arn:aws:personalize:us-west-2:acct-id:schema/MovieRatingSchema
```
這時會顯示資料集 ARN，例如：
```
{
"datasetArn": "arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS"
}
```
1. 將訓練資料新增至資料集。
1. 執行以下命令來建立資料集匯入任務。提供先前步驟中傳回的資料集 ARN 和 Amazon S3 儲存貯體名稱。提供您在 中建立的 AWS Identity and Access Management (IAM) 角色 ARN[為 Amazon Personalize 建立 IAM 角色](set-up-required-permissions.md#set-up-create-role-with-permissions)。如需 API (匯入 API) 的詳細資訊，請參閱「[CreateDatasetImportJob](API_CreateDatasetImportJob.md)」。
```
aws personalize create-dataset-import-job \
--job-name MovieRatingImportJob \
--dataset-arn arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS \
--data-source dataLocation=s3://amzn-s3-demo-bucket/ratings.csv \
--role-arn roleArn
```
這時會顯示資料集匯入任務 ARN，例如：
```
{
"datasetImportJobArn": "arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob"
}
```
1. 使用 `describe-dataset-import-job` 命令來檢查狀態。提供在前一個步驟中傳回的資料集匯入任務 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[DescribeDatasetImportJob](API_DescribeDatasetImportJob.md)」。
```
aws personalize describe-dataset-import-job \
--dataset-import-job-arn arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob
```
這時會顯示資料集匯入任務的屬性，包括其狀態。`status` 一開始會顯示為 CREATE PENDING，例如：
```
{
"datasetImportJob": {
"jobName": "MovieRatingImportJob",
"datasetImportJobArn": "arn:aws:personalize:us-west-2:acct-id:dataset-import-job/MovieRatingImportJob",
"datasetArn": "arn:aws:personalize:us-west-2:acct-id:dataset/MovieRatingDatasetGroup/INTERACTIONS",
"dataSource": {
"dataLocation": "s3://amzn-s3-demo-bucket/ratings.csv"
},
"roleArn": "role-arn",
"status": "CREATE PENDING",
"creationDateTime": 1542392161.837,
"lastUpdatedDateTime": 1542393013.377
}
}
```
當狀態顯示為 ACTIVE 時，即表示資料集匯入完成。然後，您就可以使用指定的資料集來訓練模型。
**注意**
匯入需要一些時間。請等到資料集匯入完成，再使用該資料集來訓練模型。
## 步驟 2：建立解決方案 （訓練模型）
若要訓練模型，您可以使用 [CreateSolution](API_CreateSolution.md)操作建立訓練模型的組態，並保留自動訓練。解決方案會在一小時內自動開始訓練第一個解決方案。
您可以使用配方和訓練資料來訓練模型。Amazon Personalize 提供一組預先定義的配方。如需詳細資訊，請參閱[選擇配方](working-with-predefined-recipes.md)。在本練習中，您會使用 User-Personalization-v2 配方。
1. 執行下列命令，以建立用來訓練模型的組態。此命令會建立使用自動訓練的解決方案。它會每七天自動建立新的解決方案版本 （預設值）。
```
aws personalize create-solution \
--name MovieSolution \
--dataset-group-arn arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup \
--recipe-arn arn:aws:personalize:::recipe/aws-user-personalization-v2 \
--perform-auto-training \
--solution-config "{\"autoTrainingConfig\": {\"schedulingExpression\": \"rate(7 days)\"}}"
```
這時會顯示解決方案 ARN，例如：
```
{
"solutionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution"
}
```
1. 使用 `describe-solution`命令檢查*建立*狀態。提供在前一個步驟中傳回的解決方案 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[DescribeSolution](API_DescribeSolution.md)」。
```
aws personalize describe-solution \
--solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution
```
這時會顯示解決方案的屬性和建立 `status`。例如：
```
{
"solution": {
"name": "MovieSolution",
"solutionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution",
"performHPO": false,
"performAutoML": false,
"recipeArn": "arn:aws:personalize:::recipe/aws-user-personalization-v2",
"datasetGroupArn": "arn:aws:personalize:us-west-2:acct-id:dataset-group/MovieRatingDatasetGroup",
"solutionConfig": {
"algorithmHyperParameters": {
"apply_recency_bias": "true"
},
"featureTransformationParameters": {},
"autoTrainingConfig": {
"schedulingExpression": "rate(7 days)"
}
},
"status": "ACTIVE",
"creationDateTime": "2021-05-12T16:27:59.819000-07:00",
"lastUpdatedDateTime": "2021-05-12T16:27:59.819000-07:00"
}
}
```
1. 使用自動訓練時，解決方案版本訓練會在解決方案為 ACTIVE 之後的一個內開始。訓練開始後，您可以使用下列 [ListSolutionVersions](https://docs.aws.amazon.com/personalize/latest/dg/API_ListSolutionVersions.html) 命令取得解決方案版本的 Amazon Resource Name (ARN)：
```
aws personalize list-solution-versions --solution-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution
```
1. 使用 `describe-solution-version`命令檢查解決方案版本的*訓練*狀態。提供在前一個步驟中傳回的解決方案版本 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[DescribeSolutionVersion](API_DescribeSolutionVersion.md)」。
```
aws personalize describe-solution-version \
--solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id
```
這時會顯示解決方案版本的屬性和訓練 `status`。此狀態一開始會顯示為 CREATE PENDING，例如：
```
{
"solutionVersion": {
"solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/",
...,
"status": "CREATE PENDING"
}
}
```
1. 當解決方案版本`status`為 ACTIVE 時，訓練即完成。
現在，您可以檢閱訓練指標，並使用 解決方案版本建立行銷活動。
**注意**
訓練需要一些時間。請等到訓練完成 (解決方案版本的*訓練*狀態顯示為 ACTIVE)，再將此解決方案版本用於行銷活動。
1. 您可以檢閱其指標來驗證解決方案版本的效能。執行以下命令來取得解決方案版本的指標。提供先前傳回的解決方案版本 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[GetSolutionMetrics](API_GetSolutionMetrics.md)」。
```
aws personalize get-solution-metrics \
--solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id
```
這時會顯示範例回應：
```
{
"solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/www-solution/",
"metrics": {
"coverage": 0.0485,
"mean_reciprocal_rank_at_25": 0.0381,
"normalized_discounted_cumulative_gain_at_10": 0.0363,
"normalized_discounted_cumulative_gain_at_25": 0.0984,
"normalized_discounted_cumulative_gain_at_5": 0.0175,
"precision_at_10": 0.0107,
"precision_at_25": 0.0207,
"precision_at_5": 0.0107
}
}
```
## 步驟 3：建立行銷活動 （部署解決方案）
您必須先部署解決方案版本，才能取得建議。部署解決方案也稱為建立行銷活動。一旦您建立了行銷活動，您的用戶端應用程式就可以使用 [GetRecommendations](API_RS_GetRecommendations.md) API 來取得建議。
1. 執行以下命令來建立行銷活動。提供在前一個步驟中傳回的解決方案版本 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[CreateCampaign](API_CreateCampaign.md)」。
```
aws personalize create-campaign \
--name MovieRecommendationCampaign \
--solution-version-arn arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/version-id \
--min-provisioned-tps 1
```
這時會顯示範例回應：
```
{
"campaignArn": "arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign"
}
```
1. 執行下列命令來檢查部署狀態。提供在前一個步驟中傳回的行銷活動 ARN。如需 API (匯入 API) 的詳細資訊，請參閱「[DescribeCampaign](API_DescribeCampaign.md)」。
```
aws personalize describe-campaign \
--campaign-arn arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign
```
這時會顯示範例回應：
```
{
"campaign": {
"name": "MovieRecommendationCampaign",
"campaignArn": "arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign",
"solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/",
"minProvisionedTPS": "1",
"creationDateTime": 1543864775.923,
"lastUpdatedDateTime": 1543864791.923,
"status": "CREATE IN_PROGRESS"
}
}
```
**注意**
等到 `status` 顯示為 ACTIVE，再從行銷活動中取得建議。
## 步驟 4：取得建議
執行下列 `get-recommendations` 命令來取得建議。提供在前一個步驟中傳回的行銷活動 ARN。您可以在請求中，指定來自電影評等資料集的使用者 ID。如需 API (匯入 API) 的詳細資訊，請參閱「[GetRecommendations](API_RS_GetRecommendations.md)」。
**注意**
並不是所有配方都支援 `GetRecommendations` API。如需詳細資訊，請參閱[選擇配方](working-with-predefined-recipes.md)。
您在此步驟中呼叫的 AWS CLI 命令 與先前步驟中的命令`personalize-runtime`不同。
```
aws personalize-runtime get-recommendations \
--campaign-arn arn:aws:personalize:us-west-2:acct-id:campaign/MovieRecommendationCampaign \
--user-id 123
```
行銷活動會在回應中傳回一個清單，其中列出使用者可能喜愛的項目建議 (電影 ID)。清單是依使用者相關性的遞減順序排序。
```
{
"itemList": [
{
"itemId": "14"
},
{
"itemId": "15"
},
{
"itemId": "275"
},
{
"itemId": "283"
},
{
"itemId": "273"
},
...
]
}
```