Amazon Pinpoint からエンドポイントをエクスポートする

Amazon Pinpoint が対象者について所有している情報をすべて取得するには、プロジェクトに属するエンドポイント定義をエクスポートします。エクスポートすると、Amazon Pinpoint は指定した Amazon S3 バケットにエンドポイント定義を配置します。エンドポイントのエクスポートは、次のような場合に役立ちます。

• クライアントアプリケーションで Amazon Pinpoint を使用して登録された新規および既存のエンドポイントに関する最新のデータの表示。

• Amazon Pinpoint のエンドポイントデータと独自の顧客関係管理 (CRM) システムの同期。

• 顧客データに関するレポートの作成、または顧客データの分析。

開始する前に

エンドポイントをエクスポートする前に、AWS アカウントの次のリソースが必要です。

• Amazon S3 バケット バケットの作成方法については、『Amazon Simple Storage Service ユーザーガイド』の「バケットの作成」を参照してください。

• Amazon S3 バケットに対する Amazon Pinpoint の書き込みのアクセス許可を付与する AWS Identity and Access Management (IAM)のロール。ロールを作成するには、「エンドポイントまたはセグメントをエクスポートするための IAM ロール」を参照してください。

例

次の例では、Amazon Pinpoint プロジェクトからエンドポイントをエクスポートし、Amazon S3 バケットからそれらのエンドポイントをダウンロードする方法を示します。

AWS CLI

Amazon Pinpoint を使用するには、AWS CLI でコマンドを実行します。

例 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 は、バケットの書き込み権限を 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 コマンド

エクスポートジョブの現在のステータスを確認するには、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 ファイルの場所を表します。このファイルには、エクスポートされたエンドポイント定義が含まれます。例えば、https://PINPOINT-EXAMPLE-BUCKET.s3.us-west-2.amazonaws.com/Exports/example.csv という URL で、「PINPOINT-EXAMPLE-BUCKET」がバケットの名前で、「Exports/example.csv」がキーです。キーの詳細については、「Amazon S3 ユーザーガイド」の「キー」を参照してください。

• /local/directory/ は、エンドポイントをダウンロードするローカルディレクトリのファイルパスを表します。

AWS SDK for Java

AWS SDK for Java が提供するクライアントにより、Java アプリケーションで Amazon Pinpoint API を使用できます。

例 Code

Amazon Pinpoint プロジェクトからエンドポイントをエクスポートするには、CreateExportJobRequest オブジェクトを初期化します。次に、このオブジェクトを AmazonPinpoint クライアントの createExportJob メソッドに渡します。

Amazon Pinpoint からエクスポートされたエンドポイントをダウンロードするには、 クライアントの getObjectAmazonS3 メソッドを使用します。

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

HTTP リクエストを直接 REST API に送信して Amazon Pinpoint を使用することができます。

例 POST Export Job リクエスト

Amazon Pinpoint プロジェクトのエンドポイントをエクスポートするには、Export Jobs リソースに対して 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 Export Job リクエスト

エクスポートジョブの現在のステータスを確認するには、Export Job リソースに対して 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 バケットからエクスポートされたエンドポイントを取得できます。

関連情報

API のエクスポートジョブリソースに関する詳細 (例: サポートされている HTTP メソッドやリクエストパラメータ) については、Amazon Pinpoint API リファレンスの「Export Jobs」を参照してください。