Avant de commencer Exemples Informations connexes

Exporter des points de terminaison d'Amazon Pinpoint

Pour obtenir toutes les informations dont dispose Amazon Pinpoint sur votre audience, vous pouvez exporter les définitions de points de terminaison appartenant à un projet. Lorsque vous effectuez l'exportation, Amazon Pinpoint place les définitions de points de terminaison dans un compartiment Amazon S3 que vous spécifiez. L’exportation de points de terminaison est utile si vous souhaitez :

Afficher les données les plus récentes sur les points de terminaison nouveaux et existants que votre application client a enregistré auprès d'Amazon Pinpoint.
Synchroniser les données de point de terminaison dans Amazon Pinpoint avec votre propre système de gestion des relations client (CRM).
Créer des rapports ou analyser vos données client.

Avant de commencer

Avant de pouvoir exporter des points de terminaison, vous devez disposer des ressources suivantes dans votre compte AWS :

Un compartiment Amazon S3. Pour créer un compartiment, consultez la section Créer un compartiment dans le Guide de l'utilisateur Amazon Simple Storage Service.
Rôle AWS Identity and Access Management (IAM) qui accorde à Amazon Pinpoint des autorisations d'écriture pour votre compartiment Amazon S3. Pour créer ce rôle, consultez Rôle IAM pour l'exportation de points de terminaison ou de segments.

Exemples

Les exemples suivants expliquent comment exporter des points de terminaison à partir d'un projet Amazon Pinpoint, puis les télécharger à partir de votre compartiment Amazon S3.

AWS CLI

Vous pouvez utiliser Amazon Pinpoint en exécutant des commandes avec l' AWS CLI.

Exemple Commande de création d’une tâche d’exportation

Pour exporter les points de terminaison dans votre projet Amazon Pinpoint, utilisez la commande 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

Où :

application-id correspond à l'ID du projet Amazon Pinpoint contenant les points de terminaison.
bucket-name/prefix/ correspond au nom de votre compartiment Amazon S3 et, éventuellement, à un préfixe vous permettant d'organiser les objets de votre compartiment de manière hiérarchique. Par exemple, un préfixe utile peut être pinpoint/exports/endpoints/.
iam-export-role-arn correspond à l'Amazon Resource Name (ARN) d'un rôle IAM qui accorde à Amazon Pinpoint un accès en écriture au compartiment.

La réponse à cette commande fournit des détails sur la tâche d’exportation :


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

La réponse fournit l’ID de tâche avec l’attribut Id. Vous pouvez utiliser cet ID pour vérifier le statut actuel de la tâche d’exportation.

Exemple Commande de génération d’une tâche d’exportation

Pour vérifier le statut actuel d'une tâche d'exportation, utilisez la commande get-export-job :


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

Où :

application-id correspond à l'ID du projet Amazon Pinpoint à partir duquel les points de terminaison ont été exportés.
job-id correspond à l’ID de la tâche que vous vérifiez.

La réponse à cette commande fournit l’état actuel de la tâche d’exportation :


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

La réponse fournit le statut de la tâche avec l’attribut JobStatus. Lorsque la valeur du statut de la tâche est COMPLETED, vous pouvez obtenir vos points de terminaison exportés dans votre compartiment Amazon S3.

Exemple Commande CP S3

Pour télécharger vos points de terminaison exportés, utilisez la commande cp Amazon S3 :


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

Où :

bucket-name/prefix/key correspond à l'emplacement du fichier .gz que Amazon Pinpoint a ajouté à votre compartiment lorsque vous avez exporté vos points de terminaison. Ce fichier contient les définitions de points de terminaison exportées. Par exemple, dans l’URL https://PINPOINT-EXAMPLE-BUCKET.s3.us-west-2.amazonaws.com/Exports/example.csv, « PINPOINT-EXAMPLE-BUCKET » est le nom du compartiment et « Exports/example.csv » est la clé. Pour plus d’informations sur les Clés, consultez Clés dans le Guide de l’utilisateur Amazon S3.
/local/directory/ correspond au chemin d’accès au répertoire local dans lequel vous souhaitez télécharger les points de terminaison.

AWS SDK for Java

Vous pouvez utiliser l'API Amazon Pinpoint dans vos applications Java en utilisant le client fourni par AWS SDK for Java.

Exemple Code

Pour exporter les points de terminaison à partir d'un projet Amazon Pinpoint, initialisez un objet CreateExportJobRequest. Transmettez ensuite cet objet à la méthode createExportJob du client AmazonPinpoint.

Pour télécharger les points de terminaison exportés à partir d'Amazon Pinpoint, utilisez la méthode getObject du client AmazonS3.


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

Pour l'exemple complet du SDK, consultez ExportEndpoints.java on. GitHub

HTTP

Vous pouvez utiliser Amazon Pinpoint en effectuant des demandes HTTP directement à l'API REST.

Exemple Demande de tâche d’exportation POST

Pour exporter les points de terminaison dans votre projet Amazon Pinpoint, envoyez une demande POST à la ressource Tâches d'exportation :


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

Où :

application-id correspond à l'ID du projet Amazon Pinpoint contenant les points de terminaison.
bucket-name/prefix correspond au nom de votre compartiment Amazon S3 et, éventuellement, à un préfixe vous permettant d'organiser les objets de votre compartiment de manière hiérarchique. Par exemple, un préfixe utile peut être pinpoint/exports/endpoints/.
iam-export-role-arn correspond à l'Amazon Resource Name (ARN) d'un rôle IAM qui accorde à Amazon Pinpoint un accès en écriture au compartiment.

La réponse à cette demande fournit des détails sur la tâche d’exportation :


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

La réponse fournit l’ID de tâche avec l’attribut Id. Vous pouvez utiliser cet ID pour vérifier le statut actuel de la tâche d’exportation.

Exemple Demande de tâche d’exportation GET

Pour vérifier le statut actuel d'une tâche d'exportation, envoyez une demande GET à la ressource Tâche d'exportation :


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

Où :

application-id correspond à l'ID du projet Amazon Pinpoint à partir duquel les points de terminaison ont été exportés.
job-id correspond à l’ID de la tâche que vous vérifiez.

La réponse à cette demande fournit l’état actuel de la tâche d’exportation :


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

Pour plus d'informations concernant la ressource Tâches d'exportation dans l'API Amazon Pinpoint, notamment les méthodes HTTP prises en charge et les paramètres de demande, consultez Tâches d'exportation dans la Référence de l'API Amazon Pinpoint.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Recherche de points de terminaison

Répertorier les ID de points de terminaison