终止支持通知： AWS 将于 2026 年 10 月 30 日终止对亚马逊 Pinpoint 的支持。2026 年 10 月 30 日之后，您将无法再访问亚马逊 Pinpoint 控制台或亚马逊 Pinpoint 资源（终端节点、区段、活动、旅程和分析）。有关更多信息，请参阅 Amazon Pinpoint 终止支持。注意： APIs 与短信相关、语音、移动推送、OTP 和电话号码验证不受此更改的影响，并受 AWS 最终用户消息的支持。

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

将端点导入 Amazon Pinpoint

可以通过从 Amazon S3 存储桶导入大量端点的方式来添加或更新端点。如果您在 Amazon Pinpoint 之外拥有受众的记录，并且想要将这些信息添加到 Amazon Pinpoint 项目中，则导入端点的方法很有用。在此情况下，请：

创建基于您自己的受众数据的端点定义。
将这些端点定义保存到一个或多个文件中，然后将这些文件上传到 Amazon S3 存储桶。
通过从存储桶导入端点来将端点添加到 Amazon Pinpoint 项目中。

每个导入任务可传输多达 1 GB 数据。在典型任务（其中每个端点为 4 KB 或更小）中，可以导入约 250,000 个端点。每个 AWS 账户最多可以运行两个并发导入任务。如果您需要更多带宽来完成导入任务，可以向提交增加服务配额的请求支持。有关更多信息，请参阅请求提高限额。

开始前的准备工作

要导入端点，您的 AWS 账户中需要具备以下资源：

Amazon S3 存储桶。要创建存储桶，请参阅《Amazon Simple Storage Service 用户指南》中的创建存储桶。
一个 AWS Identity and Access Management (IAM) 角色，用于向 Amazon Pinpoint 授予您的 Amazon S3 存储桶的读取权限。要创建该角色，请参阅用于导入端点或分段的 IAM 角色。

示例

以下示例演示如何将端点定义添加到您的 Amazon S3 存储桶，然后再将这些端点导入 Amazon Pinpoint 项目。

包含端点定义的文件

添加到您的 Amazon S3 存储桶的文件可以包含 CSV 或以换行符分隔的 JSON 格式的端点定义。有关可用于定义终端节点的属性，请参阅《亚马逊 Pinpoint API 参考》中的 EndpointRequestJSON 架构。

导入任务请求

以下示例演示如何通过将本地文件上传到存储桶，来将端点定义添加到 Amazon S3。然后，示例将端点定义导入 Amazon Pinpoint 项目。

AWS CLI

可以通过在 AWS CLI中运行命令来使用 Amazon Pinpoint。

例 S3 CP 命令

要将本地文件上传到 Amazon S3 存储桶，请使用 Amazon S3 cp 命令：


$ aws s3 cp ./endpoints-file s3://bucket-name/prefix/

其中：

./endpoints-file 是包含端点定义的本地文件的文件路径。
bucket-name/prefix/ 是 Amazon S3 存储桶的名称，并且还可以选择使用前缀，以帮助您按层次组织存储桶中的对象。例如，pinpoint/imports/endpoints/ 就是一个有用的前缀。

例创建导入任务命令

要从 Amazon S3 存储桶导入端点定义，请使用 create-import-job 命令：


$ aws pinpoint create-import-job \
> --application-id application-id \
> --import-job-request \
> S3Url=s3://bucket-name/prefix/key,\
> RoleArn=iam-import-role-arn,\
> Format=format,\
> RegisterEndpoints=true

其中：

application-id 是要为之导入端点的 Amazon Pinpoint 项目的 ID。
存储桶name/prefix/key是 Amazon S3 中包含一个或多个要导入的对象的位置。此位置可以用单个对象的键结尾，也可以用符合多个对象条件的前缀结尾。
iam-import-role-arn是 IAM 角色的亚马逊资源名称 (ARN)，该角色授予 Amazon Pinpoint 对存储桶的读取权限。
format 可以为 JSON 或 CSV，具体情况取决于定义端点时使用的格式。如果 Amazon S3 位置包含多个混合格式的对象，则 Amazon Pinpoint 将仅导入与指定格式匹配的对象。

RegisterEndpoints 可以是 true 或 false。当设置为 true 时，导入任务会在导入端点定义时向 Amazon Pinpoint 注册端点。

RegisterEndpoints 和 DefineSegments 组合
RegisterEndpoints	DefineSegments	描述
true	true	Amazon Pinpoint 将导入端点并创建一个包含端点的分段。
true	false	Amazon Pinpoint 将导入端点但不创建分段。
false	true	Amazon Pinpoint 将导入端点并创建一个包含端点的分段。将不保存端点，也不覆盖现有的端点。
false	false	Amazon Pinpoint 将拒绝此请求。

响应包含有关导入任务的详细信息：


{
    "ImportJobResponse": {
        "CreationDate": "2018-05-24T21:26:33.995Z",
        "Definition": {
            "DefineSegment": false,
            "ExternalId": "463709046829",
            "Format": "JSON",
            "RegisterEndpoints": true,
            "RoleArn": "iam-import-role-arn",
            "S3Url": "s3://bucket-name/prefix/key"
        },
        "Id": "d5ecad8e417d498389e1d5b9454d4e0c",
        "JobStatus": "CREATED",
        "Type": "IMPORT"
    }
}

响应通过 Id 属性提供任务 ID。可以使用此 ID 检查导入任务的当前状态。

例获取导入任务命令

要检查导入任务的当前状态，请使用 get-import-job 命令：


$ aws pinpoint get-import-job \
> --application-id application-id \
> --job-id job-id

其中：

application-id 是要为之启动导入任务的 Amazon Pinpoint 项目的 ID。
job-id 是正检查的导入任务的 ID。

此命令的响应提供导入任务的当前状态：


{
    "ImportJobResponse": {
        "ApplicationId": "application-id",
        "CompletedPieces": 1,
        "CompletionDate": "2018-05-24T21:26:45.308Z",
        "CreationDate": "2018-05-24T21:26:33.995Z",
        "Definition": {
            "DefineSegment": false,
            "ExternalId": "463709046829",
            "Format": "JSON",
            "RegisterEndpoints": true,
            "RoleArn": "iam-import-role-arn",
            "S3Url": "s3://s3-bucket-name/prefix/endpoint-definitions.json"
        },
        "FailedPieces": 0,
        "Id": "job-id",
        "JobStatus": "COMPLETED",
        "TotalFailures": 0,
        "TotalPieces": 1,
        "TotalProcessed": 3,
        "Type": "IMPORT"
    }
}

响应通过 JobStatus 属性提供任务状态。

适用于 Java 的 AWS SDK

您可以通过使用适用于 Java 的 AWS SDK提供的客户端在您的 Java 应用程序中使用 Amazon Pinpoint API。

例代码

要将包含端点定义的文件上传到 Amazon S3，请使用 AmazonS3 客户端的 putObject 方法。

要将端点导入 Amazon Pinpoint 项目，请初始化 CreateImportJobRequest 对象。然后，将此对象传递到 AmazonPinpoint 客户端的 createImportJob 方法。



package com.amazonaws.examples.pinpoint;

import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.CreateImportJobRequest;
import com.amazonaws.services.pinpoint.model.CreateImportJobResult;
import com.amazonaws.services.pinpoint.model.Format;
import com.amazonaws.services.pinpoint.model.GetImportJobRequest;
import com.amazonaws.services.pinpoint.model.GetImportJobResult;
import com.amazonaws.services.pinpoint.model.ImportJobRequest;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AmazonS3Exception;
import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import java.util.concurrent.TimeUnit;

public class ImportEndpoints {

    public static void main(String[] args) {

        final String USAGE = "\n" +
                "ImportEndpoints - Adds endpoints to an Amazon Pinpoint application by: \n" +
                "1.) Uploading the endpoint definitions to an Amazon S3 bucket. \n" +
                "2.) Importing the endpoint definitions from the bucket to an Amazon Pinpoint " +
                "application.\n\n" +
                "Usage: ImportEndpoints <endpointsFileLocation> <s3BucketName> <iamImportRoleArn> " +
                "<applicationId>\n\n" +
                "Where:\n" +
                "  endpointsFileLocation - The relative location of the JSON file that contains the " +
                "endpoint definitions.\n" +
                "  s3BucketName - The name of the Amazon S3 bucket to upload the JSON file to. If the " +
                "bucket doesn't exist, a new bucket is created.\n" +
                "  iamImportRoleArn - The ARN of an IAM role that grants Amazon Pinpoint read " +
                "permissions to the S3 bucket.\n" +
                "  applicationId - The ID of the Amazon Pinpoint application to add the endpoints to.";

        if (args.length < 1) {
            System.out.println(USAGE);
            System.exit(1);
        }

        String endpointsFileLocation = args[0];
        String s3BucketName = args[1];
        String iamImportRoleArn = args[2];
        String applicationId = args[3];

        Path endpointsFilePath = Paths.get(endpointsFileLocation);
        File endpointsFile = new File(endpointsFilePath.toAbsolutePath().toString());
        uploadToS3(endpointsFile, s3BucketName);

        importToPinpoint(endpointsFile.getName(), s3BucketName, iamImportRoleArn, applicationId);

    }

    private static void uploadToS3(File endpointsFile, String s3BucketName) {

        // Initializes Amazon S3 client.
        final AmazonS3 s3 = AmazonS3ClientBuilder.defaultClient();

        // Checks whether the specified bucket exists. If not, attempts to create one.
        if (!s3.doesBucketExistV2(s3BucketName)) {
            try {
                s3.createBucket(s3BucketName);
                System.out.format("Created S3 bucket %s.\n", s3BucketName);
            } catch (AmazonS3Exception e) {
                System.err.println(e.getErrorMessage());
                System.exit(1);
            }
        }

        // Uploads the endpoints file to the bucket.
        String endpointsFileName = endpointsFile.getName();
        System.out.format("Uploading %s to S3 bucket %s . . .\n", endpointsFileName, s3BucketName);
        try {
            s3.putObject(s3BucketName, "imports/" + endpointsFileName, endpointsFile);
            System.out.println("Finished uploading to S3.");
        } catch (AmazonServiceException e) {
            System.err.println(e.getErrorMessage());
            System.exit(1);
        }
    }

    private static void importToPinpoint(String endpointsFileName, String s3BucketName,
            String iamImportRoleArn, String applicationId) {

        // The S3 URL that Amazon Pinpoint requires to find the endpoints file.
        String s3Url = "s3://" + s3BucketName + "/imports/" + endpointsFileName;

        // Defines the import job that Amazon Pinpoint runs.
        ImportJobRequest importJobRequest = new ImportJobRequest()
                .withS3Url(s3Url)
                .withRegisterEndpoints(true)
                .withRoleArn(iamImportRoleArn)
                .withFormat(Format.JSON);
        CreateImportJobRequest createImportJobRequest = new CreateImportJobRequest()
                .withApplicationId(applicationId)
                .withImportJobRequest(importJobRequest);

        // Initializes the Amazon Pinpoint client.
        AmazonPinpoint pinpointClient = AmazonPinpointClientBuilder.standard()
                .withRegion(Regions.US_EAST_1).build();

        System.out.format("Importing endpoints in %s to Amazon Pinpoint application %s . . .\n",
                endpointsFileName, applicationId);

        try {

            // Runs the import job with Amazon Pinpoint.
            CreateImportJobResult importResult = pinpointClient.createImportJob(createImportJobRequest);

            String jobId = importResult.getImportJobResponse().getId();
            GetImportJobResult getImportJobResult = null;
            String jobStatus = null;

            // Checks the job status until the job completes or fails.
            do {
                getImportJobResult = pinpointClient.getImportJob(new GetImportJobRequest()
                        .withJobId(jobId)
                        .withApplicationId(applicationId));
                jobStatus = getImportJobResult.getImportJobResponse().getJobStatus();
                System.out.format("Import job %s . . .\n", jobStatus.toLowerCase());
                TimeUnit.SECONDS.sleep(3);
            } while (!jobStatus.equals("COMPLETED") && !jobStatus.equals("FAILED"));

            if (jobStatus.equals("COMPLETED")) {
                System.out.println("Finished importing endpoints.");
            } else {
                System.err.println("Failed to import endpoints.");
                System.exit(1);
            }

            // Checks for entries that failed to import.
            // getFailures provides up to 100 of the first failed entries for the job, if
            // any exist.
            List<String> failedEndpoints = getImportJobResult.getImportJobResponse().getFailures();
            if (failedEndpoints != null) {
                System.out.println("Failed to import the following entries:");
                for (String failedEndpoint : failedEndpoints) {
                    System.out.println(failedEndpoint);
                }
            }

        } catch (AmazonServiceException | InterruptedException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }

    }

}

HTTP

可以通过直接向 REST API 发出 HTTP 请求来使用 Amazon Pinpoint。

例 S3 PUT 对象请求

要将端点定义添加到存储桶，请使用 Amazon S3 PUT 对象操作，并提供端点定义作为正文：


PUT /prefix/key HTTP/1.1
Content-Type: text/plain
Accept: application/json
Host: bucket-name.s3.amazonaws.com
X-Amz-Content-Sha256: c430dc094b0cec2905bc88d96314914d058534b14e2bc6107faa9daa12fdff2d
X-Amz-Date: 20180605T184132Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/us-east-1/s3/aws4_request, SignedHeaders=accept;cache-control;content-length;content-type;host;postman-token;x-amz-content-sha256;x-amz-date, Signature=c25cbd6bf61bd3b3667c571ae764b9bf2d8af61b875cacced95d1e68d91b4170
Cache-Control: no-cache

{"ChannelType":"SMS","Address":"2065550182","Location":{"Country":"CAN"},"Demographic":{"Platform":"Android","Make":"LG"},"User":{"UserId":"example-user-id-1"}}
{"ChannelType":"APNS","Address":"1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}
{"ChannelType":"EMAIL","Address":"john.stiles@example.com","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}

其中：

/prefix/key 是上传后将包含端点定义的对象的前缀和键名。可以使用此前缀分层次组织对象。例如，pinpoint/imports/endpoints/ 就是一个有用的前缀。
bucket-name 是要将端点定义添加到的 Amazon S3 存储桶的名称。

例 POST 导入任务请求

要从 Amazon S3 存储桶导入端点定义，请向导入任务资源发出 POST 请求。在您的请求中，包含所需的标题并提供 ImportJobRequestJSON 作为正文：


POST /v1/apps/application_id/jobs/import HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180605T214912Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/us-east-1/mobiletargeting/aws4_request, SignedHeaders=accept;cache-control;content-length;content-type;host;postman-token;x-amz-date, Signature=c25cbd6bf61bd3b3667c571ae764b9bf2d8af61b875cacced95d1e68d91b4170
Cache-Control: no-cache

{
  "S3Url": "s3://bucket-name/prefix/key",
  "RoleArn": "iam-import-role-arn",
  "Format": "format",
  "RegisterEndpoints": true
}

其中：

application-id 是要为之导入端点的 Amazon Pinpoint 项目的 ID。
存储桶name/prefix/key是 Amazon S3 中包含一个或多个要导入的对象的位置。此位置可以用单个对象的键结尾，也可以用符合多个对象条件的前缀结尾。
iam-import-role-arn是 IAM 角色的亚马逊资源名称 (ARN)，该角色授予 Amazon Pinpoint 对存储桶的读取权限。
format 可以为 JSON 或 CSV，具体情况取决于定义端点时使用的格式。如果 Amazon S3 位置包含多个混合格式的文件，则 Amazon Pinpoint 将仅导入与指定格式匹配的文件。

如果您的请求成功，将收到与下类似的响应：


{
    "Id": "a995ce5d70fa44adb563b7d0e3f6c6f5",
    "JobStatus": "CREATED",
    "CreationDate": "2018-06-05T21:49:15.288Z",
    "Type": "IMPORT",
    "Definition": {
        "S3Url": "s3://bucket-name/prefix/key",
        "RoleArn": "iam-import-role-arn",
        "ExternalId": "external-id",
        "Format": "JSON",
        "RegisterEndpoints": true,
        "DefineSegment": false
    }
}

响应通过 Id 属性提供任务 ID。可以使用此 ID 检查导入任务的当前状态。

例 GET 导入任务请求

要检查导入任务的当前状态，请向导入任务资源发出 GET 请求：


GET /v1/apps/application_id/jobs/import/job_id HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180605T220744Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/us-east-1/mobiletargeting/aws4_request, SignedHeaders=accept;cache-control;content-type;host;postman-token;x-amz-date, Signature=c25cbd6bf61bd3b3667c571ae764b9bf2d8af61b875cacced95d1e68d91b4170
Cache-Control: no-cache

其中：

application_id 是已为之启动导入任务的 Amazon Pinpoint 项目的 ID。
job_id 是正检查的导入任务的 ID。

如果您的请求成功，将收到与下类似的响应：


{
    "ApplicationId": "application_id",
    "Id": "70a51b2cf442447492d2c8e50336a9e8",
    "JobStatus": "COMPLETED",
    "CompletedPieces": 1,
    "FailedPieces": 0,
    "TotalPieces": 1,
    "CreationDate": "2018-06-05T22:04:49.213Z",
    "CompletionDate": "2018-06-05T22:04:58.034Z",
    "Type": "IMPORT",
    "TotalFailures": 0,
    "TotalProcessed": 3,
    "Definition": {
        "S3Url": "s3://bucket-name/prefix/key.json",
        "RoleArn": "iam-import-role-arn",
        "ExternalId": "external-id",
        "Format": "JSON",
        "RegisterEndpoints": true,
        "DefineSegment": false
    }
}

响应通过 JobStatus 属性提供任务状态。

有关 Amazon Pinpoint API 中的导入任务资源的更多信息，包括支持的 HTTP 方法和请求参数，请参阅《Amazon Pinpoint API 参考》中的导入任务。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

批量添加端点

将端点从 Amazon Pinpoint 导出到 Amazon S3 存储桶