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 S3 버킷에 대한 Amazon Pinpoint 쓰기 권한을 부여하는 AWS Identity and Access Management (IAM) 역할입니다. 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 명령

내보내기 작업의 현재 상태를 확인하려면 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를 사용할 수 있습니다.

예 코드

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 사용 설명서의 세그먼트 내보내기를 참조하세요.

지원되는 HTTP 메서드 및 요청 파라미터를 비롯하여, Amazon Pinpoint API의 내보내기 작업 리소스에 대한 자세한 내용은 Amazon Pinpoint API 참조의 내보내기 작업 섹션을 참조하세요.