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

# 入門 (SDK for Python (Boto3))
<a name="getting-started-python"></a>

本教學課程說明如何使用適用於 Python 的 SDK (Boto3) 從頭到尾完成 Amazon Personalize 工作流程。

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

**Topics**
+ [先決條件](#gs-sdk-prerequisites)
+ [教學課程](#gs-python-custom-tutorial)
+ [開始使用 Amazon Personalize APIs搭配 Jupyter (iPython) 筆記本](#gs-jupyter-notebook)

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

以下是在本指南中使用 Python 範例的先決條件：
+ 完成 [入門先決條件](gs-prerequisites.md)以設定所需的許可並建立訓練資料。如果您使用自己的來源資料，請確定您的資料格式與先決條件相同。
+ 依照 中的指定設定您的 適用於 Python (Boto3) 的 AWS SDK 環境[設定 AWS SDKs](aws-personalize-set-up-sdks.md)。

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

在下列步驟中，您可以驗證您的環境，並為 Amazon Personalize 建立適用於 Python (Boto3) 的 SDK 用戶端。然後，您可以匯入資料、使用行銷活動建立和部署解決方案版本，以及取得建議。

### 步驟 1：驗證您的 Python 環境並建立 boto3 用戶端
<a name="gs-python-example"></a>

當您完成事前準備之後，請執行下列 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：匯入資料
<a name="getting-started-python-import-dataset"></a>

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

1. 使用下列程式碼在 Amazon Personalize 中建立結構描述。`getting-started-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": "TIMESTAMP",
             "type": "long"
         }
     ],
     "version": "1.0"
   }
   
   create_interactions_schema_response = personalize.create_schema(
       name='getting-started-schema',
       schema=json.dumps(schema)
   )
   
   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')
   dataset_group_arn = response['datasetGroupArn']
   
   description = personalize.describe_dataset_group(datasetGroupArn = dataset_group_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 = 'datase_name',
       schemaArn = 'schema_arn',
       datasetGroupArn = 'dataset_group_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',
       importMode = 'FULL'
   )
   
   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)
   ```

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

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

1.  使用下列程式碼建立新的解決方案。將以下內容做為參數傳遞：`dataset_group_arn`來自先前版本的 、解決方案的名稱，以及 User-Personalization-v2 配方的 ARN (`arn:aws:personalize:::recipe/aws-user-personalization-v2`)。存放新解決方案的 ARN 以供日後使用。

   ```
   create_solution_response = personalize.create_solution(
     name='solution name', 
     recipeArn= 'arn:aws:personalize:::recipe/aws-user-personalization-v2', 
     datasetGroupArn = 'dataset group arn'
   )
   solution_arn = create_solution_response['solutionArn']
   print('solution_arn: ', solution_arn)
   ```

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

   ```
   import time
   import json
   
   create_solution_version_response = personalize.create_solution_version(
       solutionArn = solution_arn
   )
   
   solution_version_arn = create_solution_version_response['solutionVersionArn']
   print(json.dumps(create_solution_version_response, indent=2))
   
   max_time = time.time() + 3*60*60 # 3 hours
   while time.time() < max_time:
       describe_solution_version_response = personalize.describe_solution_version(
           solutionVersionArn = solution_version_arn
       )
       status = describe_solution_version_response["solutionVersion"]["status"]
       print("SolutionVersion: {}".format(status))
       
       if status == "ACTIVE" or status == "CREATE FAILED":
           break
           
       time.sleep(60)
   ```

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

建立解決方案版本後，請使用 Amazon Personalize 行銷活動進行部署。使用下列程式碼來建立部署解決方案版本的行銷活動。將以下內容做為參數傳遞： `solution_version_arn`和行銷活動的名稱。方法會傳回新行銷活動的 Amazon Resource Name (ARN)。存放它以供日後使用。

```
response = personalize.create_campaign(
    name = 'campaign name',
    solutionVersionArn = 'solution version arn'
)

arn = response['campaignArn']

description = personalize.describe_campaign(campaignArn = arn)['campaign']
print('Name: ' + description['name'])
print('ARN: ' + description['campaignArn'])
print('Status: ' + description['status'])
```

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

建立行銷活動後 , 您可以使用行銷活動來取得建議。下列程式碼說明如何從行銷活動取得建議，並列印出每個建議項目的 ID。傳遞您在上一個步驟中建立之行銷活動的 ARN。對於使用者 ID，您可以從訓練資料傳遞使用者的 ID，例如 `123`。

```
response = personalizeRt.get_recommendations(
    campaignArn = 'Campaign ARN',
    userId = '123',
    numResults = 10
)

print("Recommended items")
for item in response['itemList']:
    print (item['itemId'])
```

## 開始使用 Amazon Personalize APIs搭配 Jupyter (iPython) 筆記本
<a name="gs-jupyter-notebook"></a>

 若要使用 Jupyter 筆記本開始使用 Amazon Personalize，請複製或下載一系列在 [Amazon Personalize 範例](https://github.com/aws-samples/amazon-personalize-samples)儲存庫的 [get\$1started](https://github.com/aws-samples/amazon-personalize-samples/tree/master/getting_started) 資料夾中找到的筆記本。筆記本會逐步引導您匯入訓練資料、建立解決方案、建立行銷活動，以及使用 Amazon Personalize 取得建議。

**注意**  
 開始使用筆記本之前，請務必依照 https：//[README.md](https://github.com/aws-samples/amazon-personalize-samples/blob/master/getting_started/README.md) 中的步驟建置您的環境