Prima di iniziare Esempi Informazioni correlate

Esportazione di endpoint da Amazon Pinpoint

Per ottenere tutte le informazioni di cui Amazon Pinpoint dispone sul pubblico, è possibile esportare le definizioni di endpoint appartenenti a un progetto. Quando esegui l'esportazione, Amazon Pinpoint inserisce le definizioni di endpoint in un bucket Amazon S3 specificato. L'esportazione degli endpoint è utile per:

Visualizzare i dati più recenti sugli endpoint nuovi ed esistenti che l'applicazione client ha registrato in Amazon Pinpoint.
Sincronizzare i dati degli endpoint in Amazon Pinpoint con il sistema CRM (Customer Relationship Management) in uso.
Creare report sui dati dei clienti o analizzarli.

Prima di iniziare

Prima di esportare endpoint, devi disporre delle seguenti risorse nel tuo account AWS :

Un bucket Amazon S3. Per creare un bucket, consulta Creazione di un bucket nella Guida per l'utente di Amazon Simple Storage Service.
Un ruolo AWS Identity and Access Management (IAM) che concede le autorizzazioni di scrittura di Amazon Pinpoint per il tuo bucket Amazon S3. Per creare il ruolo, consulta Ruolo IAM per l'esportazione di endpoint o segmenti.

Esempi

Gli esempi seguenti illustrano come esportare gli endpoint da un progetto Amazon Pinpoint e quindi scaricare questi endpoint dal bucket Amazon S3.

AWS CLI

Puoi utilizzare Amazon Pinpoint eseguendo i comandi con l' AWS CLI.

Esempio Comando per la creazione di un processo di esportazione

Per esportare gli endpoint nel tuo progetto Amazon Pinpoint, usa il comando 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

Dove:

application-id è l'ID del progetto Amazon Pinpoint contenente gli endpoint.
bucket-name/prefix/ è il nome del bucket Amazon S3 e, facoltativamente, un prefisso che consente di organizzare gli oggetti nel bucket in modo gerarchico. Ad esempio, un prefisso utile potrebbe essere pinpoint/exports/endpoints/.
iam-export-role-arn è il nome della risorsa Amazon (ARN) di un ruolo IAM che concede ad Amazon Pinpoint l'accesso in lettura al bucket.

La risposta a questo comando fornisce dettagli sul processo di esportazione:


{
    "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 risposta fornisce l'ID processo con l'attributo Id. Puoi usare questo ID per verificare lo stato corrente del processo di esportazione.

Esempio Comando per ottenere un processo di esportazione

Per verificare lo stato corrente di un processo di esportazione, usa il comando get-export-job:


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

Dove:

application-id è l'ID del progetto Amazon Pinpoint da cui sono stati esportati gli endpoint.
job-id è l'ID del processo da verificare.

La risposta a questo comando fornisce lo stato corrente del processo di esportazione:


{
    "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 risposta fornisce lo stato del processo con l'attributo JobStatus. Quando il valore di stato del processo è COMPLETED, puoi recuperare gli endpoint esportati dal bucket Amazon S3.

Esempio Comando S3 CP

Per scaricare gli endpoint esportati, usa il comando Amazon S3 cp:


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

Dove:

bucket-name/prefix/key è la posizione del file .gz aggiunto da Amazon Pinpoint al bucket durante l'esportazione degli endpoint. Questo file contiene le definizioni degli endpoint esportati. Ad esempio, nell'URL https://PINPOINT-EXAMPLE-BUCKET.s3.us-west-2.amazonaws.com/Exports/example.csv, PINPOINT-EXAMPLE-BUCKET è il nome del bucket e Exports/example.csv è la chiave. Per ulteriori informazioni sulle Chiavi, consulta Chiavi nella Guida per l'utente di Amazon S3.
/local/directory/ è il percorso della directory locale in cui scaricare gli endpoint.

AWS SDK for Java

Puoi utilizzare l'API Amazon Pinpoint nelle applicazioni Java utilizzando il client fornito da AWS SDK for Java.

Esempio Codice

Per esportare endpoint da un progetto Amazon Pinpoint, inizializza un oggetto CreateExportJobRequest. Passa quindi questo oggetto al metodo createExportJob del client AmazonPinpoint.

Per scaricare gli endpoint esportati da Amazon Pinpoint, usa il metodo getObject del 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);
        }
    }
}

Per l'esempio completo dell'SDK, consulta .java on. ExportEndpoints GitHub

HTTP

Puoi utilizzare Amazon Pinpoint effettuando richieste HTTP direttamente alla REST API.

Esempio Richiesta POST al processo di esportazione

Per esportare gli endpoint nel progetto Amazon Pinpoint, invia una richiesta POST alla risorsa Processi di esportazione:


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

Dove:

application-id è l'ID del progetto Amazon Pinpoint contenente gli endpoint.
bucket-name/prefix è il nome del bucket Amazon S3 e, facoltativamente, un prefisso che consente di organizzare gli oggetti nel bucket in modo gerarchico. Ad esempio, un prefisso utile potrebbe essere pinpoint/exports/endpoints/.
iam-export-role-arn è il nome della risorsa Amazon (ARN) di un ruolo IAM che concede ad Amazon Pinpoint l'accesso in lettura al bucket.

La risposta a questa richiesta fornisce dettagli sul processo di esportazione:


{
    "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 risposta fornisce l'ID processo con l'attributo Id. Puoi usare questo ID per verificare lo stato corrente del processo di esportazione.

Esempio Richiesta GET al processo di esportazione

Per controllare lo stato corrente di un processo di esportazione, invia una richiesta GET alla risorsa Export Job (Processo di esportazione):


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

Dove:

application-id è l'ID del progetto Amazon Pinpoint da cui sono stati esportati gli endpoint.
job-id è l'ID del processo da verificare.

La risposta a questa richiesta fornisce lo stato corrente del processo di esportazione:


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

La risposta fornisce lo stato del processo con l'attributo JobStatus. Quando il valore di stato del processo è COMPLETED, puoi recuperare gli endpoint esportati dal bucket Amazon S3.

Per ulteriori informazioni sulla risorsa Processi di esportazione nell'API Amazon Pinpoint, compresi i metodi HTTP supportati e i parametri della richiesta, consulta l'articolo relativo ai processi di esportazione nella documentazione di riferimento dell'API Amazon Pinpoint.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Ricerca di endpoint

Acquisizione dell'elenco degli ID endpoint