终止支持通知： 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 的新的和现有的端点的最新数据。
将 Amazon Pinpoint 中的端点数据与您自己的客户关系管理 (CRM) 系统同步。
创建有关客户数据的报告或分析客户数据。

注意

发送到 Amazon S3 存储桶的内容可能包含客户内容。如果需要删除已导出到 Amazon S3 存储桶的端点数据，则必须在 Amazon S3 存储桶中执行此操作。有关删除敏感数据的更多信息，请参阅如何清空 S3 存储桶？或如何删除 S3 存储桶？

开始前的准备工作

要导出端点，您的 AWS 账户中需要有以下资源：

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

示例

以下示例演示如何从 Amazon Pinpoint 项目导出端点，然后从 Amazon S3 存储桶下载这些端点。

AWS CLI

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

例创建导出任务命令

要导出 Amazon Pinpoint 项目中的端点，请使用 create-export-job 命令：


$ aws pinpoint create-export-job \
> --application-id application-id \
> --export-job-request \
> S3UrlPrefix=s3://bucket-name/prefix/,\
> RoleArn=iam-export-role-arn

其中：

application-id 是包含端点的 Amazon Pinpoint 项目的 ID。
bucket-name/prefix/ 是 Amazon S3 存储桶的名称，并且可以是帮助您按层次组织存储桶中的对象的前缀。例如，pinpoint/exports/endpoints/ 就是一个有用的前缀。
iam-export-role-arn 是为 Amazon Pinpoint 授予对存储桶的写入权限的 IAM 角色的 Amazon 资源名称 (ARN)。

对此命令的响应提供了有关导出任务的详细信息：


{
    "ExportJobResponse": {
        "CreationDate": "2018-06-04T22:04:20.585Z",
        "Definition": {
            "RoleArn": "iam-export-role-arn",
            "S3UrlPrefix": "s3://s3-bucket-name/prefix/"
        },
        "Id": "7390e0de8e0b462380603c5a4df90bc4",
        "JobStatus": "CREATED",
        "Type": "EXPORT"
    }
}

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

例获取导出任务命令

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


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

其中：

application-id 是从中导出端点的 Amazon Pinpoint 项目的 ID。
job-id 是您要检查的任务的 ID。

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


{
    "ExportJobResponse": {
        "ApplicationId": "application-id",
        "CompletedPieces": 1,
        "CompletionDate": "2018-05-08T22:16:48.228Z",
        "CreationDate": "2018-05-08T22:16:44.812Z",
        "Definition": {},
        "FailedPieces": 0,
        "Id": "6c99c463f14f49caa87fa27a5798bef9",
        "JobStatus": "COMPLETED",
        "TotalFailures": 0,
        "TotalPieces": 1,
        "TotalProcessed": 215,
        "Type": "EXPORT"
    }
}

响应通过 JobStatus 属性提供任务状态。当任务状态值为 COMPLETED 时，您可以从 Amazon S3 存储桶获取导出的端点。

例 S3 CP 命令

要下载导出的端点，请使用 Amazon S3 cp 命令：


$ aws s3 cp s3://bucket-name/prefix/key.gz /local/directory/

其中：

bucket-name/prefix/key 是 Amazon Pinpoint 在您导出端点时添加到您的存储桶的 .gz 文件的位置。此文件包含导出的端点定义。例如，在 URL https://PINPOINT-EXAMPLE-BUCKET.s3.us-west-2.amazonaws.com/Exports/example.csv 中，PINPOINT-EXAMPLE-BUCKET 是存储桶的名称，Exports/example.csv 是密钥。有关密钥的更多信息，请参阅《Amazon S3 用户指南》中的密钥。
/local/directory/ 是您要将端点下载到的本地目录的文件路径。

适用于 Java 的 AWS SDK

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

例代码

要从 Amazon Pinpoint 项目中导出端点，请初始化 CreateExportJobRequest 对象。然后，将此对象传递到 AmazonPinpoint 客户端的 createExportJob 方法。

要从 Amazon Pinpoint 下载导出的端点，请使用 AmazonS3 客户端的 getObject 方法。


import software.amazon.awssdk.core.ResponseBytes;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.pinpoint.PinpointClient;
import software.amazon.awssdk.services.pinpoint.model.ExportJobRequest;
import software.amazon.awssdk.services.pinpoint.model.PinpointException;
import software.amazon.awssdk.services.pinpoint.model.CreateExportJobRequest;
import software.amazon.awssdk.services.pinpoint.model.CreateExportJobResponse;
import software.amazon.awssdk.services.pinpoint.model.GetExportJobResponse;
import software.amazon.awssdk.services.pinpoint.model.GetExportJobRequest;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
import software.amazon.awssdk.services.s3.model.S3Object;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;


import software.amazon.awssdk.core.ResponseBytes;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.pinpoint.PinpointClient;
import software.amazon.awssdk.services.pinpoint.model.ExportJobRequest;
import software.amazon.awssdk.services.pinpoint.model.PinpointException;
import software.amazon.awssdk.services.pinpoint.model.CreateExportJobRequest;
import software.amazon.awssdk.services.pinpoint.model.CreateExportJobResponse;
import software.amazon.awssdk.services.pinpoint.model.GetExportJobResponse;
import software.amazon.awssdk.services.pinpoint.model.GetExportJobRequest;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Request;
import software.amazon.awssdk.services.s3.model.ListObjectsV2Response;
import software.amazon.awssdk.services.s3.model.S3Object;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;

/**
 * To run this code example, you need to create an AWS Identity and Access
 * Management (IAM) role with the correct policy as described in this
 * documentation:
 * https://docs.aws.amazon.com/pinpoint/latest/developerguide/audience-data-export.html
 *
 * Also, set up your development environment, including your credentials.
 *
 * For information, see this documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 */

public class ExportEndpoints {
    public static void main(String[] args) {
        final String usage = """

                This program performs the following steps:

                1. Exports the endpoints to an Amazon S3 bucket.
                2. Downloads the exported endpoints files from Amazon S3.
                3. Parses the endpoints files to obtain the endpoint IDs and prints them.
                Usage: ExportEndpoints <applicationId> <s3BucketName> <iamExportRoleArn> <path>

                Where:
                  applicationId - The ID of the Amazon Pinpoint application that has the endpoint.
                  s3BucketName - The name of the Amazon S3 bucket to export the JSON file to.\s
                  iamExportRoleArn - The ARN of an IAM role that grants Amazon Pinpoint write permissions to the S3 bucket.  path - The path where the files downloaded from the Amazon S3 bucket are written (for example, C:/AWS/).
                """;

        if (args.length != 4) {
            System.out.println(usage);
            System.exit(1);
        }

        String applicationId = args[0];
        String s3BucketName = args[1];
        String iamExportRoleArn = args[2];
        String path = args[3];
        System.out.println("Deleting an application with ID: " + applicationId);

        Region region = Region.US_EAST_1;
        PinpointClient pinpoint = PinpointClient.builder()
                .region(region)
                .build();

        S3Client s3Client = S3Client.builder()
                .region(region)
                .build();

        exportAllEndpoints(pinpoint, s3Client, applicationId, s3BucketName, path, iamExportRoleArn);
        pinpoint.close();
        s3Client.close();
    }

    public static void exportAllEndpoints(PinpointClient pinpoint,
            S3Client s3Client,
            String applicationId,
            String s3BucketName,
            String path,
            String iamExportRoleArn) {

        try {
            List<String> objectKeys = exportEndpointsToS3(pinpoint, s3Client, s3BucketName, iamExportRoleArn,
                    applicationId);
            List<String> endpointFileKeys = objectKeys.stream().filter(o -> o.endsWith(".gz"))
                    .collect(Collectors.toList());
            downloadFromS3(s3Client, path, s3BucketName, endpointFileKeys);

        } catch (PinpointException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
    }

    public static List<String> exportEndpointsToS3(PinpointClient pinpoint, S3Client s3Client, String s3BucketName,
            String iamExportRoleArn, String applicationId) {

        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd-HH_mm:ss.SSS_z");
        String endpointsKeyPrefix = "exports/" + applicationId + "_" + dateFormat.format(new Date());
        String s3UrlPrefix = "s3://" + s3BucketName + "/" + endpointsKeyPrefix + "/";
        List<String> objectKeys = new ArrayList<>();
        String key;

        try {
            // Defines the export job that Amazon Pinpoint runs.
            ExportJobRequest jobRequest = ExportJobRequest.builder()
                    .roleArn(iamExportRoleArn)
                    .s3UrlPrefix(s3UrlPrefix)
                    .build();

            CreateExportJobRequest exportJobRequest = CreateExportJobRequest.builder()
                    .applicationId(applicationId)
                    .exportJobRequest(jobRequest)
                    .build();

            System.out.format("Exporting endpoints from Amazon Pinpoint application %s to Amazon S3 " +
                    "bucket %s . . .\n", applicationId, s3BucketName);

            CreateExportJobResponse exportResult = pinpoint.createExportJob(exportJobRequest);
            String jobId = exportResult.exportJobResponse().id();
            System.out.println(jobId);
            printExportJobStatus(pinpoint, applicationId, jobId);

            ListObjectsV2Request v2Request = ListObjectsV2Request.builder()
                    .bucket(s3BucketName)
                    .prefix(endpointsKeyPrefix)
                    .build();

            // Create a list of object keys.
            ListObjectsV2Response v2Response = s3Client.listObjectsV2(v2Request);
            List<S3Object> objects = v2Response.contents();
            for (S3Object object : objects) {
                key = object.key();
                objectKeys.add(key);
            }

            return objectKeys;

        } catch (PinpointException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return null;
    }

    private static void printExportJobStatus(PinpointClient pinpointClient,
            String applicationId,
            String jobId) {

        GetExportJobResponse getExportJobResult;
        String status;

        try {
            // Checks the job status until the job completes or fails.
            GetExportJobRequest exportJobRequest = GetExportJobRequest.builder()
                    .jobId(jobId)
                    .applicationId(applicationId)
                    .build();

            do {
                getExportJobResult = pinpointClient.getExportJob(exportJobRequest);
                status = getExportJobResult.exportJobResponse().jobStatus().toString().toUpperCase();
                System.out.format("Export job %s . . .\n", status);
                TimeUnit.SECONDS.sleep(3);

            } while (!status.equals("COMPLETED") && !status.equals("FAILED"));

            if (status.equals("COMPLETED")) {
                System.out.println("Finished exporting endpoints.");
            } else {
                System.err.println("Failed to export endpoints.");
                System.exit(1);
            }

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

    // Download files from an Amazon S3 bucket and write them to the path location.
    public static void downloadFromS3(S3Client s3Client, String path, String s3BucketName, List<String> objectKeys) {

        String newPath;
        try {
            for (String key : objectKeys) {
                GetObjectRequest objectRequest = GetObjectRequest.builder()
                        .bucket(s3BucketName)
                        .key(key)
                        .build();

                ResponseBytes<GetObjectResponse> objectBytes = s3Client.getObjectAsBytes(objectRequest);
                byte[] data = objectBytes.asByteArray();

                // Write the data to a local file.
                String fileSuffix = new SimpleDateFormat("yyyyMMddHHmmss").format(new Date());
                newPath = path + fileSuffix + ".gz";
                File myFile = new File(newPath);
                OutputStream os = new FileOutputStream(myFile);
                os.write(data);
            }
            System.out.println("Download finished.");

        } catch (S3Exception | NullPointerException | IOException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }
}

有关完整的 SDK 示例，请参阅上GitHub的 ExportEndpoints.java。

HTTP

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

例 POST 导出任务请求

要导出 Amazon Pinpoint 项目中的端点，请将 POST 请求发给导出任务资源：


POST /v1/apps/application_id/jobs/export HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180606T001238Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180606/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

{
  "S3UrlPrefix": "s3://bucket-name/prefix",
  "RoleArn": "iam-export-role-arn"
}

其中：

application-id 是包含端点的 Amazon Pinpoint 项目的 ID。
bucket-name/prefix 是 Amazon S3 存储桶的名称，并且可以是帮助您按层次组织存储桶中的对象的前缀。例如，pinpoint/exports/endpoints/ 就是一个有用的前缀。
iam-export-role-arn 是为 Amazon Pinpoint 授予对存储桶的写入权限的 IAM 角色的 Amazon 资源名称 (ARN)。

对此请求的响应提供了有关导出任务的详细信息：


{
    "Id": "611bdc54c75244bfa51fe7001ddb2e36",
    "JobStatus": "CREATED",
    "CreationDate": "2018-06-06T00:12:43.271Z",
    "Type": "EXPORT",
    "Definition": {
        "S3UrlPrefix": "s3://bucket-name/prefix",
        "RoleArn": "iam-export-role-arn"
    }
}

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

例 GET 导出任务请求

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


GET /v1/apps/application_id/jobs/export/job_id HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180606T002443Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180606/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": "job_id",
    "JobStatus": "COMPLETED",
    "CompletedPieces": 1,
    "FailedPieces": 0,
    "TotalPieces": 1,
    "CreationDate": "2018-06-06T00:12:43.271Z",
    "CompletionDate": "2018-06-06T00:13:01.141Z",
    "Type": "EXPORT",
    "TotalFailures": 0,
    "TotalProcessed": 217,
    "Definition": {}
}

响应通过 JobStatus 属性提供任务状态。当任务状态值为 COMPLETED 时，您可以从 Amazon S3 存储桶获取导出的端点。

要查找特定端点的端点 ID，必须确定端点所属的客户细分，然后从 Amazon Pinpoint 中导出该客户细分。导出的数据包括每个端点的端点 ID。您可以使用 Amazon Pinpoint 控制台将分段导出到文件。有关导出客户细分的更多信息，请参阅《Amazon Pinpoint 用户指南》中的导出客户细分。

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

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

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

文档惯例

导入端点

查找 Amazon Pinpoint 项目中的端点

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

注意

开始前的准备工作

示例

例 创建导出任务命令

例 获取导出任务命令

例 S3 CP 命令

例 代码

例 POST 导出任务请求

例 GET 导出任务请求

相关信息

例创建导出任务命令

例获取导出任务命令

例代码