從 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 使用者指南中的建立儲存貯體。

• 授予 Amazon Pinpoint 寫入許可的 AWS Identity and Access Management (IAM) 角色Amazon S3。若要建立角色，請參閱用於匯出端點或客群的 IAM 角色。

範例

以下範例說明如何從 Amazon Pinpoint 匯出端點，然後從 Amazon S3 儲存貯體下載這些端點。

AWS CLI

透過 AWS CLI執行命令，可以使用 Amazon Pinpoint。

範例 Create Export Job 命令

若要匯出 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 是 IAM 角色的 Amazon Resource Name (ARN)，可以為 Amazon Pinpoint 授予儲存貯體的寫入存取權限。

此命令的回應提供有關匯出任務的詳細資訊：

{
    "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 命令

若要檢查匯出任務的目前狀態，請使用 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 Export Job 請求

若要匯出 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 是 IAM 角色的 Amazon Resource Name (ARN)，可以為 Amazon Pinpoint 授予儲存貯體的寫入存取權限。

此請求的回應提供有關匯出任務的詳細資訊：

{
    "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 Export Jobs 請求

若要檢查匯出任務目前的狀態，請向匯出任務資源提出 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 參考中的匯出任務。