本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用批量细分作业来获取用户细分
<a name="creating-batch-seg-job"></a>

 如果您使用了 USER\_SEGMENTATION 食谱，则可以创建批量细分作业，以获取解决方案版本的用户细分。根据每个用户与您库存物品交互的概率，按降序对每个用户细分进行排序。根据食谱，您的输入数据必须是 JSON 格式的物品列表（[Item-Affinity 食谱](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/家](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 资源名称 (ARN)，然后将 `IAM service role ARN` 替换为您在设置期间为 Amazon Personalize 创建的 IAM 服务角色的 ARN。此角色必须分别对您的输入和输出 Amazon S3 存储桶具有读写权限。对于 `num-results`，指定您希望 Amazon Personalize 为每行输入数据预测的用户数量。默认值为 25。最大值为 500 万。（可选）提供 `filter-arn` 来筛选用户细分。如果您的筛选器使用占位符参数，请确保这些参数的值包含在您的输入 JSON 中。有关更多信息，请参阅 [筛选批量建议和用户细分（自定义资源）](filter-batch.md)。

将 `S3 input path` 和 `S3 output 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 资源名称 (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)。