Exportieren von Endpunkten aus Amazon Pinpoint - Amazon Pinpoint
Bevor Sie beginnenBeispieleÄhnliche Informationen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Exportieren von Endpunkten aus Amazon Pinpoint

Um alle Informationen zu erhalten, die Amazon Pinpoint über Ihre Zielgruppe besitzt, können Sie die zu einem Projekt gehörenden Endpunktdefinitionen exportieren. Beim Export legt Amazon Pinpoint die Endpunktdefinitionen in einen von Ihnen angegebenen Amazon-S3-Bucket ab. Das Exportieren von Endpunkten ist nützlich, wenn Sie Folgendes erledigen möchten:

  • Anzeige der neuesten Daten über neue und bestehende Endpunkte, die Ihre Client-Anwendung bei Amazon Pinpoint registriert hat.

  • Synchronisieren der Endpunktdaten in Amazon Pinpoint mit Ihrem eigenen CRM (Customer Relationship Management)-System.

  • Berichte über Ihre Kundendaten erstellen oder diese analysieren.

Bevor Sie beginnen

Bevor Sie Endpunkte exportieren können, benötigen Sie die folgenden Ressourcen in Ihrem AWS -Konto:

  • Ein Amazon-S3-Bucket Informationen zum Erstellen eines Buckets finden Sie unter Erstellen eines Buckets im Benutzerhandbuch für Amazon Simple Storage Service.

  • Eine AWS Identity and Access Management (IAM-) Rolle, die Amazon Pinpoint Schreibberechtigungen für Ihren Amazon S3 S3-Bucket gewährt. Weitere Informationen zum Erstellen der Rolle finden Sie unter IAMRolle für den Export von Endpunkten oder Segmenten.

Beispiele

Die folgenden Beispiele zeigen, wie Sie Endpunkte aus einem Amazon-Pinpoint-Projekt exportieren und diese Endpunkte anschließend aus Ihrem Amazon-S3-Bucket herunterladen.

AWS CLI

Sie können Amazon Pinpoint verwenden, indem Sie Befehle mit der AWS CLI ausführen.

Beispiel Befehl zum Erstellen eines Exportauftrags

Zum Exportieren der Endpunkte in Ihrem Amazon-Pinpoint-Projekt verwenden Sie den Befehl 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

Wobei gilt:

  • application-id ist die ID des Amazon-Pinpoint-Projekts, das die Endpunkte enthält.

  • bucket-name/prefix/ ist der Name Ihres Amazon-S3-Buckets und optional ein Präfix, das Ihnen hilft, die Objekte in Ihrem Bucket hierarchisch zu organisieren. Ein praktisches Präfix könnte beispielsweise pinpoint/exports/endpoints/ sein.

  • iam-export-role-arn ist der Amazon-Ressourcenname (ARN) einer IAM-Rolle, die Amazon Pinpoint Schreibzugriff auf den Bucket erteilt.

Die Ausgabe dieses Befehls enthält Details über den Exportauftrag:

{
    "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"
    }
}

Die Ausgabe stellt die Auftrags-ID mit dem Id-Attribut bereit. Diese ID können Sie verwenden, um den aktuellen Status des Exportauftrags zu überprüfen.

Beispiel Befehl zum Abrufen eines Exportauftrags

Um den aktuellen Status eines Exportauftrags zu überprüfen, verwenden Sie den Befehl get-export-job:

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

Wobei gilt:

  • application-id ist die ID des Amazon-Pinpoint-Projekts, aus dem Sie die Endpunkte exportiert haben.

  • job-id ist die ID des Auftrags, den Sie überprüfen.

Die Ausgabe dieses Befehls stellt Informationen über den aktuellen Status des Exportauftrags bereit:

{
    "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"
    }
}

Die Ausgabe stellt den Auftragsstatus mit dem JobStatus-Attribut bereit. Wenn der Wert des Auftragsstatus gleich COMPLETED ist, können Sie ihre exportierten Endpunkte aus Ihrem Amazon-S3-Bucket abrufen.

Beispiel S3 CP-Befehl

Um die exportierten Endpunkte herunterzuladen, verwenden Sie den Amazon-S3-Befehl cp:

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

Wobei gilt:

  • bucket-name/prefix/key ist der Speicherort der .gz-Datei, die Amazon Pinpoint Ihrem Bucket hinzugefügt hat, als Sie Ihre Endpunkte exportiert haben. Diese Datei enthält die exportierten Endpunktdefinitionen. So ist in der URL https://PINPOINT-EXAMPLE-BUCKET.s3.us-west-2.amazonaws.com/Exports/example.csv PINPOINT-EXAMPLE-BUCKET der Name des Buckets und Exports/example.csv der Schlüssel. Weitere Informationen zu Schlüsseln finden Sie unter Schlüssel im Amazon-S3-Benutzerhandbuch.

  • /local/directory/ ist der Dateipfad zu dem lokalen Verzeichnis, in das Sie die Endpunkte herunterladen möchten.

AWS SDK for Java

Sie können die Amazon-Pinpoint-API in Ihren Java-Anwendungen verwenden, indem Sie den vom AWS SDK for Java bereitgestellten Client verwenden.

Beispiel Code

Um Endpunkte aus einem Amazon-Pinpoint-Projekt zu exportieren, initialisieren Sie ein CreateExportJobRequest-Objekt. Anschließend übergeben Sie dieses Objekt der Methode createExportJob des AmazonPinpoint-Clients.

Um die exportierten Endpunkte von Amazon Pinpoint herunterzuladen, verwenden Sie die Methode getObject des AmazonS3-Clients.

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);
        }
    }
}

Das vollständige SDK-Beispiel finden Sie unter ExportEndpoints.java on. GitHub

HTTP

Sie können Amazon Pinpoint verwenden, indem Sie HTTP-Anforderungen direkt an die REST-API stellen.

Beispiel POST-Anforderung für einen Exportauftrag

Um die Endpunkte in Ihrem Amazon-Pinpoint-Projekt zu exportieren, führen Sie eine POST-Anforderung für die Ressource Exportaufträge aus:

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"
}

Wobei gilt:

  • application-id ist die ID des Amazon-Pinpoint-Projekts, das die Endpunkte enthält.

  • bucket-name/prefix ist der Name Ihres Amazon-S3-Buckets und optional ein Präfix, das Ihnen hilft, die Objekte in Ihrem Bucket hierarchisch zu organisieren. Ein praktisches Präfix könnte beispielsweise pinpoint/exports/endpoints/ sein.

  • iam-export-role-arn ist der Amazon-Ressourcenname (ARN) einer IAM-Rolle, die Amazon Pinpoint Schreibzugriff auf den Bucket erteilt.

Die Ausgabe dieser Anforderung enthält Details über den Exportauftrag:

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

Die Ausgabe stellt die Auftrags-ID mit dem Id-Attribut bereit. Diese ID können Sie verwenden, um den aktuellen Status des Exportauftrags zu überprüfen.

Beispiel GET-Anforderung für einen Exportauftrag

Um den aktuellen Status eines Exportauftrags zu überprüfen, führen Sie eine GET-Anforderung für die Ressource Export job durch:

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

Wobei gilt:

  • application-id ist die ID des Amazon-Pinpoint-Projekts, aus dem Sie die Endpunkte exportiert haben.

  • job-id ist die ID des Auftrags, den Sie überprüfen.

Die Ausgabe dieser Anforderung stellt Informationen über den aktuellen Status des Exportauftrags bereit:

{
    "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": {}
}

Die Ausgabe stellt den Auftragsstatus mit dem JobStatus-Attribut bereit. Wenn der Wert des Auftragsstatus gleich COMPLETED ist, können Sie ihre exportierten Endpunkte aus Ihrem Amazon-S3-Bucket abrufen.

Weitere Informationen über die „Exportaufträge“-Ressource in der Amazon-Pinpoint-API, einschließlich der unterstützten HTTP-Methoden und Anforderungsparameter, finden Sie unter Exportaufträge in der Amazon-Pinpoint-API-Referenz.