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

# 使用批次區段任務取得使用者區段
<a name="creating-batch-seg-job"></a>

 如果您使用 USER\_SEGMENTATION 配方，您可以建立批次區段任務，以使用解決方案版本取得使用者區段。每個使用者客群會根據每個使用者與您庫存中的項目互動的機率，以遞減順序排序。根據配方，您的輸入資料必須是 JSON 格式的項目 ([項目親和性配方](item-affinity-recipe.md)) 或項目屬性 ([Item-Attribute-Affinity 配方](item-attribute-affinity-recipe.md)) 清單。您可以使用 Amazon Personalize 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS SDKs建立批次區段任務。

 當您建立批次區段任務時，您可以指定輸入和輸出位置的 Amazon S3 路徑。Amazon S3 以字首為基礎。如果您提供輸入資料位置的字首，Amazon Personalize 會使用符合該字首的所有檔案做為輸入資料。例如，如果您提供 `s3://amzn-s3-demo-bucket/folderName` 且儲存貯體也有路徑為 的資料夾`s3://amzn-s3-demo-bucket/folderName_test`，Amazon Personalize 會使用兩個資料夾中的所有檔案做為輸入資料。若要僅使用特定資料夾中的檔案做為輸入資料，請使用字首分隔符號結束 Amazon S3 路徑，例如`/`：`s3://amzn-s3-demo-bucket/folderName/`如需 Amazon S3 如何組織物件的詳細資訊，請參閱[組織、列出和使用您的物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/organizing-objects.html)。

**Topics**
+ [建立批次區段任務 （主控台）](#batch-segment-console)
+ [建立批次區段任務 (AWS CLI)](#batch-segment-cli)
+ [建立批次區段任務AWS SDKs)](#batch-segment-sdk)

## 建立批次區段任務 （主控台）
<a name="batch-segment-console"></a>

 完成 後[準備批次建議的輸入資料](batch-data-upload.md)，您就可以建立批次區段任務。此程序假設您已使用 USER\_SEGEMENTATION 配方建立解決方案和解決方案版本 （訓練模型）。

**若要建立批次區段任務 （主控台）**

1. 在 [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home)：// 開啟 Amazon Personalize 主控台並登入您的帳戶。

1. 在**資料集群組**頁面上，選擇您的資料集群組。

1. 在導覽窗格中選擇**批次區段任務**，然後選擇**建立批次區段任務**。

1. 在**批次區段任務詳細資訊**中，針對**批次區段任務名稱**，指定批次區段任務的名稱。

1. 針對**解決方案**，選擇解決方案，然後選擇您要用來產生建議**的解決方案版本 ID**。只有在您使用 USER\_SEGEMENTATION 配方時，才能建立批次區段任務。

1. 對於**使用者數量**，選擇性地指定 Amazon Personalize 為每個使用者區段產生的使用者數量。預設為 25。上限為 500 萬。

1.  對於**輸入來源**，指定輸入檔案的 Amazon S3 路徑，或使用**瀏覽 S3** 選擇您的 Amazon S3 儲存貯體。

   使用下列語法： **s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json**

    您的輸入資料必須為解決方案使用的配方的正確格式。如需輸入資料範例，請參閱 [批次區段任務輸入和輸出 JSON 範例](prepare-input-data-user-segment.md#batch-segment-job-json-examples)。

1. 對於**輸出目的地**，指定輸出位置的路徑，或使用**瀏覽 S3** 選擇您的 Amazon S3 儲存貯體。建議您為輸出資料使用不同的位置 （資料夾或不同的 Amazon S3 儲存貯體）。

    使用下列語法： **s3://amzn-s3-demo-bucket/<output folder name>/**

1. 針對 **IAM 角色**，選擇下列其中一項：
   +  選擇**建立並使用新的服務角色**，然後輸入**服務角色名稱**以建立新的角色，或
   +  如果您已使用正確的許可建立角色，請選擇**使用現有的服務角色**，然後選擇 IAM 角色。

    您使用的角色必須分別具有輸入和輸出 Amazon S3 儲存貯體的讀取和寫入存取權。

1.  對於**篩選條件組態**，選擇性地選擇要將篩選條件套用至使用者區段的篩選條件。如果您的篩選條件使用預留位置參數，請確定參數的值包含在您的輸入 JSON 中。如需詳細資訊，請參閱[在輸入 JSON 中提供篩選條件值](filter-batch.md#providing-filter-values)。

1. 對於**標籤**，選擇性地新增任何標籤。如需標記 Amazon Personalize 資源的詳細資訊，請參閱 [標記 Amazon Personalize 資源](tagging-resources.md)。

1.  選擇**建立批次區段任務**。批次區段任務建立開始，批次**區段任務**頁面隨即出現，並顯示**批次區段任務詳細資訊**區段。

1.  當批次區段任務的狀態變更為**作用中**時，您可以從指定的輸出 Amazon S3 儲存貯體擷取任務的輸出。輸出檔案的名稱格式為 `{{input-name}}.out`。

## 建立批次區段任務 (AWS CLI)
<a name="batch-segment-cli"></a>

完成 後[準備批次建議的輸入資料](batch-data-upload.md)，您就可以使用下列`create-batch-segment-job`程式碼建立批次區段任務。指定任務名稱、`Solution version ARN`將 取代為您解決方案版本的 Amazon Resource Name (ARN)，並將 取代`IAM service role ARN`為您在設定期間為 Amazon Personalize 建立的 IAM 服務角色的 ARN。此角色必須分別具有輸入和輸出 Amazon S3 儲存貯體的讀取和寫入存取權。對於 `num-results` ，指定您希望 Amazon Personalize 針對每一行輸入資料預測的使用者數量。預設為 25。上限為 500 萬。選擇性地提供 `filter-arn`來篩選使用者客群。如果您的篩選條件使用預留位置參數，請確定參數的值包含在您的輸入 JSON 中。如需詳細資訊，請參閱[篩選批次建議和使用者區段 （自訂資源）](filter-batch.md)。

`S3 output path` 使用輸入檔案`S3 input path`和輸出位置的 Amazon S3 路徑取代 和 。建議您為輸出資料使用不同的位置 （資料夾或不同的 Amazon S3 儲存貯體）。輸入和輸出位置請使用下列語法： **s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json**和 **s3://amzn-s3-demo-bucket/<output folder name>/**。

```
aws personalize create-batch-segment-job \
                --job-name {{Job name}} \
                --solution-version-arn {{Solution version ARN}} \
                --num-results {{The number of predicted users}} \
                --filter-arn {{Filter ARN}} \
                --job-input s3DataSource={path=s3://{{S3 input path}}} \
                --job-output s3DataDestination={path=s3://{{S3 output path}}} \
                --role-arn {{IAM service role ARN}}
{
   "batchSegmentJobArn": "arn:aws:personalize:us-west-2:acct-id:batch-segment-job/batchSegmentJobName"
}
```

## 建立批次區段任務AWS SDKs)
<a name="batch-segment-sdk"></a>

完成 後[準備批次建議的輸入資料](batch-data-upload.md)，您就可以使用 `CreateBatchSegmentJob`操作建立批次區段任務。下列程式碼示範如何建立批次區段任務。為任務命名、指定要使用的解決方案版本的 Amazon Resource Name (ARN)、指定 Amazon Personalize IAM 角色的 ARN，以及指定輸入檔案和輸出位置的 Amazon S3 路徑。您的 IAM 服務角色必須分別具有輸入和輸出 Amazon S3 儲存貯體的讀取和寫入存取權。

建議您為輸出資料使用不同的位置 （資料夾或不同的 Amazon S3 儲存貯體）。輸入和輸出位置請使用下列語法： **s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json**和 **s3://amzn-s3-demo-bucket/<output folder name>/**。

 針對 `numResults`，指定您希望 Amazon Personalize 針對每一行輸入資料預測的使用者數量。預設為 25。上限為 500 萬。選擇性地提供 `filterArn`來篩選使用者客群。如果您的篩選條件使用預留位置參數，請確定參數的值包含在您的輸入 JSON 中。如需詳細資訊，請參閱[篩選批次建議和使用者區段 （自訂資源）](filter-batch.md)。

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize_rec = boto3.client(service_name='personalize')

personalize_rec.create_batch_segment_job (
    solutionVersionArn = "{{Solution version ARN}}",
    jobName = "{{Job name}}",
    numResults = {{25}},
    filterArn = "{{Filter ARN}}",
    roleArn = "{{IAM service role ARN}}",
    jobInput = 
       {"s3DataSource": {"path": "s3://amzn-s3-demo-bucket/<folder name>/<input JSON file name>.json"}},
    jobOutput = 
       {"s3DataDestination": {"path": "s3://amzn-s3-demo-bucket/<output folder name>/"}}
)
```

------
#### [ SDK for Java 2.x ]

```
public static String createBatchSegmentJob(PersonalizeClient personalizeClient,
                                                        String solutionVersionArn,
                                                        String jobName,
                                                        String filterArn,
                                                        int numResults,
                                                        String s3InputDataSourcePath,
                                                        String s3DataDestinationPath,
                                                        String roleArn,
                                                        String explorationWeight,
                                                        String explorationItemAgeCutOff) {

  long waitInMilliseconds = 60 * 1000;
  String status;
  String batchSegmentJobArn;

  try {
      // Set up data input and output parameters.
      S3DataConfig inputSource = S3DataConfig.builder()
              .path(s3InputDataSourcePath)
              .build();
      S3DataConfig outputDestination = S3DataConfig.builder()
              .path(s3DataDestinationPath)
              .build();

      BatchSegmentJobInput jobInput = BatchSegmentJobInput.builder()
              .s3DataSource(inputSource)
              .build();
      BatchSegmentJobOutput jobOutputLocation = BatchSegmentJobOutput.builder()
              .s3DataDestination(outputDestination)
              .build();


      CreateBatchSegmentJobRequest createBatchSegmentJobRequest = CreateBatchSegmentJobRequest.builder()
              .solutionVersionArn(solutionVersionArn)
              .filterArn(filterArn)
              .jobInput(jobInput)
              .jobOutput(jobOutputLocation)
              .jobName(jobName)
              .numResults(numResults)
              .roleArn(roleArn)
              .build();

      batchSegmentJobArn = personalizeClient.createBatchSegmentJob(createBatchSegmentJobRequest)
              .batchSegmentJobArn();
      DescribeBatchSegmentJobRequest describeBatchSegmentJobRequest = DescribeBatchSegmentJobRequest.builder()
              .batchSegmentJobArn(batchSegmentJobArn)
              .build();

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

      // wait until the batch segment job is complete.
      while (Instant.now().getEpochSecond() < maxTime) {

          BatchSegmentJob batchSegmentJob = personalizeClient
                  .describeBatchSegmentJob(describeBatchSegmentJobRequest)
                  .batchSegmentJob();

          status = batchSegmentJob.status();
          System.out.println("batch segment 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 batchSegmentJobArn;

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

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateBatchSegmentJobCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";

// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the batch segment job's parameters.

export const createBatchSegmentJobParam = {
  jobName: "NAME",
  jobInput: {
    s3DataSource: {
      path: "INPUT_PATH",
    },
  },
  jobOutput: {
    s3DataDestination: {
      path: "OUTPUT_PATH",
    },
  },
  roleArn: "ROLE_ARN",
  solutionVersionArn: "SOLUTION_VERSION_ARN",
  numResults: 20,
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateBatchSegmentJobCommand(createBatchSegmentJobParam),
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

處理批次任務可能需要一段時間才能完成。您可以藉由呼叫 [DescribeBatchSegmentJob](API_DescribeBatchSegmentJob.md) 並傳遞 `batchSegmentJobArn` 作為輸入參數來檢查任務的狀態。您也可以呼叫 ，列出 AWS 環境中所有 Amazon Personalize 批次區段任務[ListBatchSegmentJobs](API_ListBatchSegmentJobs.md)。