Prima di iniziare Esempi Informazioni correlate

Avviso di fine del supporto: il 30 ottobre 2026, AWS terminerà il supporto per Amazon Pinpoint. Dopo il 30 ottobre 2026, non potrai più accedere alla console Amazon Pinpoint o alle risorse Amazon Pinpoint (endpoint, segmenti, campagne, percorsi e analisi). Per ulteriori informazioni, consulta la pagina relativa alla fine del supporto di Amazon Pinpoint. Nota: per quanto APIs riguarda gli SMS, i comandi vocali, i messaggi push su dispositivi mobili, l'OTP e la convalida del numero di telefono non sono interessati da questa modifica e sono supportati da AWS End User Messaging.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Importazione degli endpoint in Amazon Pinpoint

È possibile aggiungere o aggiornare numerosi endpoint importandoli da un bucket Amazon S3. L'importazione di endpoint è utile se disponi di record relativi al pubblico all'esterno di Amazon Pinpoint e vuoi aggiungere queste informazioni a un progetto Amazon Pinpoint. In questo caso, è necessario:

Creare definizioni di endpoint basate sui dati dei destinatari.
Salvare queste definizioni di endpoint in uno o più file e caricare i file in un bucket Amazon S3.
Aggiungere gli endpoint a un progetto Amazon Pinpoint importandoli da un bucket.

Ogni processo di importazione può trasferire fino a 1 GB di dati. In un processo tipico, in cui ogni endpoint è da 4 KB o meno, è possibile importare circa 250.000 endpoint. È possibile eseguire fino a due processi di importazione simultanei per account. AWS Se hai bisogno di più larghezza di banda per i tuoi lavori di importazione, puoi inviare una richiesta di aumento della quota di servizio a. Supporto Per ulteriori informazioni, consulta Richiesta di aumento delle quote.

Prima di iniziare

Prima di importare 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 lettura di Amazon Pinpoint per il tuo bucket Amazon S3. Per creare il ruolo, consulta Ruolo IAM per l'importazione di endpoint o segmenti.

Esempi

Gli esempi seguenti illustrano come aggiungere definizioni di endpoint a un bucket Amazon S3 e quindi importare tali endpoint in un progetto Amazon Pinpoint.

File con definizioni di endpoint

I file che aggiungi al tuo bucket Amazon S3 possono contenere definizioni di endpoint in formato CSV o in formato JSON delimitato da nuove righe. Per gli attributi che puoi utilizzare per definire i tuoi endpoint, consulta lo schema EndpointRequestJSON nell'Amazon Pinpoint API Reference.

Richieste al processo di importazione

I seguenti esempi illustrano come aggiungere definizioni di endpoint a Amazon S3 caricando un file locale in un bucket. Quindi, gli esempi importano le definizioni di endpoint in un progetto Amazon Pinpoint.

AWS CLI

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

Esempio Comando S3 CP

Per caricare un file locale in un bucket Amazon S3, utilizza il comando Amazon S3: cp


$ aws s3 cp ./endpoints-file s3://bucket-name/prefix/

Dove:

./endpoints-file è il percorso di un file locale che contiene le definizioni di 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/imports/endpoints/.

Esempio Comando per la creazione di un processo di importazione

Per importare le definizioni di endpoint da un bucket Amazon S3, usa il comando create-import-job:


$ aws pinpoint create-import-job \
> --application-id application-id \
> --import-job-request \
> S3Url=s3://bucket-name/prefix/key,\
> RoleArn=iam-import-role-arn,\
> Format=format,\
> RegisterEndpoints=true

Dove:

application-id è l'ID del progetto Amazon Pinpoint per cui stai importando gli endpoint.
bucket- name/prefix/key è la posizione in Amazon S3 che contiene uno o più oggetti da importare. La posizione può terminare con la chiave per un singolo oggetto oppure con un prefisso che qualifica più oggetti.
iam-import-role-arnè l'Amazon Resource Name (ARN) di un ruolo IAM che concede ad Amazon Pinpoint l'accesso in lettura al bucket.
format può essere JSON o CSV, a seconda del formato utilizzato per definire gli endpoint. Se la posizione Amazon S3 include più oggetti di formati misti, Amazon Pinpoint importa solo gli oggetti che corrispondono al formato specificato.

RegisterEndpoints può essere true o false. Se impostato su true, il processo di importazione registra gli endpoint con Amazon Pinpoint quando vengono importate le definizioni di endpoint.

RegisterEndpoints DefineSegments e combinazioni
RegisterEndpoints	DefineSegments	Descrizione
true	true	Amazon Pinpoint importerà gli endpoint e creerà un segmento che li contiene.
true	false	Amazon Pinpoint importerà gli endpoint e non creerà un segmento.
false	true	Amazon Pinpoint importerà gli endpoint e creerà un segmento che li contiene. Gli endpoint non verranno salvati e non sovrascriveranno gli endpoint esistenti.
false	false	Amazon Pinpoint rifiuterà questa richiesta.

La risposta include i dettagli sul processo di importazione:


{
    "ImportJobResponse": {
        "CreationDate": "2018-05-24T21:26:33.995Z",
        "Definition": {
            "DefineSegment": false,
            "ExternalId": "463709046829",
            "Format": "JSON",
            "RegisterEndpoints": true,
            "RoleArn": "iam-import-role-arn",
            "S3Url": "s3://bucket-name/prefix/key"
        },
        "Id": "d5ecad8e417d498389e1d5b9454d4e0c",
        "JobStatus": "CREATED",
        "Type": "IMPORT"
    }
}

La risposta fornisce l'ID processo con l'attributo Id. Puoi usare questo ID per verificare lo stato corrente del processo di importazione.

Esempio Comando Get per processo di importazione

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


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

Dove:

application-id è l'ID del progetto Amazon Pinpoint per cui è stato avviato il processo di importazione.
job-id è l'ID del processo di importazione da verificare.

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


{
    "ImportJobResponse": {
        "ApplicationId": "application-id",
        "CompletedPieces": 1,
        "CompletionDate": "2018-05-24T21:26:45.308Z",
        "CreationDate": "2018-05-24T21:26:33.995Z",
        "Definition": {
            "DefineSegment": false,
            "ExternalId": "463709046829",
            "Format": "JSON",
            "RegisterEndpoints": true,
            "RoleArn": "iam-import-role-arn",
            "S3Url": "s3://s3-bucket-name/prefix/endpoint-definitions.json"
        },
        "FailedPieces": 0,
        "Id": "job-id",
        "JobStatus": "COMPLETED",
        "TotalFailures": 0,
        "TotalPieces": 1,
        "TotalProcessed": 3,
        "Type": "IMPORT"
    }
}

La risposta fornisce lo stato del processo con l'attributo JobStatus.

AWS SDK per Java

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

Esempio Codice

Per caricare un file con le definizioni di endpoint in Amazon S3, usa il metodo putObject del client AmazonS3.

Per importare endpoint in un progetto Amazon Pinpoint, inizializza un oggetto CreateImportJobRequest. Passa quindi questo oggetto al metodo createImportJob del client AmazonPinpoint.



package com.amazonaws.examples.pinpoint;

import com.amazonaws.AmazonServiceException;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.pinpoint.AmazonPinpoint;
import com.amazonaws.services.pinpoint.AmazonPinpointClientBuilder;
import com.amazonaws.services.pinpoint.model.CreateImportJobRequest;
import com.amazonaws.services.pinpoint.model.CreateImportJobResult;
import com.amazonaws.services.pinpoint.model.Format;
import com.amazonaws.services.pinpoint.model.GetImportJobRequest;
import com.amazonaws.services.pinpoint.model.GetImportJobResult;
import com.amazonaws.services.pinpoint.model.ImportJobRequest;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.services.s3.model.AmazonS3Exception;
import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import java.util.concurrent.TimeUnit;

public class ImportEndpoints {

    public static void main(String[] args) {

        final String USAGE = "\n" +
                "ImportEndpoints - Adds endpoints to an Amazon Pinpoint application by: \n" +
                "1.) Uploading the endpoint definitions to an Amazon S3 bucket. \n" +
                "2.) Importing the endpoint definitions from the bucket to an Amazon Pinpoint " +
                "application.\n\n" +
                "Usage: ImportEndpoints <endpointsFileLocation> <s3BucketName> <iamImportRoleArn> " +
                "<applicationId>\n\n" +
                "Where:\n" +
                "  endpointsFileLocation - The relative location of the JSON file that contains the " +
                "endpoint definitions.\n" +
                "  s3BucketName - The name of the Amazon S3 bucket to upload the JSON file to. If the " +
                "bucket doesn't exist, a new bucket is created.\n" +
                "  iamImportRoleArn - The ARN of an IAM role that grants Amazon Pinpoint read " +
                "permissions to the S3 bucket.\n" +
                "  applicationId - The ID of the Amazon Pinpoint application to add the endpoints to.";

        if (args.length < 1) {
            System.out.println(USAGE);
            System.exit(1);
        }

        String endpointsFileLocation = args[0];
        String s3BucketName = args[1];
        String iamImportRoleArn = args[2];
        String applicationId = args[3];

        Path endpointsFilePath = Paths.get(endpointsFileLocation);
        File endpointsFile = new File(endpointsFilePath.toAbsolutePath().toString());
        uploadToS3(endpointsFile, s3BucketName);

        importToPinpoint(endpointsFile.getName(), s3BucketName, iamImportRoleArn, applicationId);

    }

    private static void uploadToS3(File endpointsFile, String s3BucketName) {

        // Initializes Amazon S3 client.
        final AmazonS3 s3 = AmazonS3ClientBuilder.defaultClient();

        // Checks whether the specified bucket exists. If not, attempts to create one.
        if (!s3.doesBucketExistV2(s3BucketName)) {
            try {
                s3.createBucket(s3BucketName);
                System.out.format("Created S3 bucket %s.\n", s3BucketName);
            } catch (AmazonS3Exception e) {
                System.err.println(e.getErrorMessage());
                System.exit(1);
            }
        }

        // Uploads the endpoints file to the bucket.
        String endpointsFileName = endpointsFile.getName();
        System.out.format("Uploading %s to S3 bucket %s . . .\n", endpointsFileName, s3BucketName);
        try {
            s3.putObject(s3BucketName, "imports/" + endpointsFileName, endpointsFile);
            System.out.println("Finished uploading to S3.");
        } catch (AmazonServiceException e) {
            System.err.println(e.getErrorMessage());
            System.exit(1);
        }
    }

    private static void importToPinpoint(String endpointsFileName, String s3BucketName,
            String iamImportRoleArn, String applicationId) {

        // The S3 URL that Amazon Pinpoint requires to find the endpoints file.
        String s3Url = "s3://" + s3BucketName + "/imports/" + endpointsFileName;

        // Defines the import job that Amazon Pinpoint runs.
        ImportJobRequest importJobRequest = new ImportJobRequest()
                .withS3Url(s3Url)
                .withRegisterEndpoints(true)
                .withRoleArn(iamImportRoleArn)
                .withFormat(Format.JSON);
        CreateImportJobRequest createImportJobRequest = new CreateImportJobRequest()
                .withApplicationId(applicationId)
                .withImportJobRequest(importJobRequest);

        // Initializes the Amazon Pinpoint client.
        AmazonPinpoint pinpointClient = AmazonPinpointClientBuilder.standard()
                .withRegion(Regions.US_EAST_1).build();

        System.out.format("Importing endpoints in %s to Amazon Pinpoint application %s . . .\n",
                endpointsFileName, applicationId);

        try {

            // Runs the import job with Amazon Pinpoint.
            CreateImportJobResult importResult = pinpointClient.createImportJob(createImportJobRequest);

            String jobId = importResult.getImportJobResponse().getId();
            GetImportJobResult getImportJobResult = null;
            String jobStatus = null;

            // Checks the job status until the job completes or fails.
            do {
                getImportJobResult = pinpointClient.getImportJob(new GetImportJobRequest()
                        .withJobId(jobId)
                        .withApplicationId(applicationId));
                jobStatus = getImportJobResult.getImportJobResponse().getJobStatus();
                System.out.format("Import job %s . . .\n", jobStatus.toLowerCase());
                TimeUnit.SECONDS.sleep(3);
            } while (!jobStatus.equals("COMPLETED") && !jobStatus.equals("FAILED"));

            if (jobStatus.equals("COMPLETED")) {
                System.out.println("Finished importing endpoints.");
            } else {
                System.err.println("Failed to import endpoints.");
                System.exit(1);
            }

            // Checks for entries that failed to import.
            // getFailures provides up to 100 of the first failed entries for the job, if
            // any exist.
            List<String> failedEndpoints = getImportJobResult.getImportJobResponse().getFailures();
            if (failedEndpoints != null) {
                System.out.println("Failed to import the following entries:");
                for (String failedEndpoint : failedEndpoints) {
                    System.out.println(failedEndpoint);
                }
            }

        } catch (AmazonServiceException | InterruptedException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }

    }

}

HTTP

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

Esempio Richiesta PUT Object di S3

Per aggiungere le definizioni di endpoint a un bucket, utilizza l'operazione oggetto PUT di Amazon S3 e fornisci le definizioni di endpoint come corpo:


PUT /prefix/key HTTP/1.1
Content-Type: text/plain
Accept: application/json
Host: bucket-name.s3.amazonaws.com
X-Amz-Content-Sha256: c430dc094b0cec2905bc88d96314914d058534b14e2bc6107faa9daa12fdff2d
X-Amz-Date: 20180605T184132Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/us-east-1/s3/aws4_request, SignedHeaders=accept;cache-control;content-length;content-type;host;postman-token;x-amz-content-sha256;x-amz-date, Signature=c25cbd6bf61bd3b3667c571ae764b9bf2d8af61b875cacced95d1e68d91b4170
Cache-Control: no-cache

{"ChannelType":"SMS","Address":"2065550182","Location":{"Country":"CAN"},"Demographic":{"Platform":"Android","Make":"LG"},"User":{"UserId":"example-user-id-1"}}
{"ChannelType":"APNS","Address":"1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}
{"ChannelType":"EMAIL","Address":"john.stiles@example.com","Location":{"Country":"USA"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}}

Dove:

/prefix/key è il prefisso e il nome della chiave per l'oggetto che conterrà le definizioni di endpoint dopo il caricamento. È possibile utilizzare il prefisso per organizzare gerarchicamente gli oggetti. Ad esempio, un prefisso utile potrebbe essere pinpoint/imports/endpoints/.
bucket-name è il nome del bucket Amazon S3 a cui aggiungi le definizioni di endpoint.

Esempio Richiesta POST per processo di importazione

Per importare le definizioni di endpoint da un bucket Amazon S3, invia una richiesta POST alla risorsa Processi di importazione. Nella richiesta, includi le intestazioni richieste e fornisci il codice ImportJobRequestJSON come corpo:


POST /v1/apps/application_id/jobs/import HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180605T214912Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/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

{
  "S3Url": "s3://bucket-name/prefix/key",
  "RoleArn": "iam-import-role-arn",
  "Format": "format",
  "RegisterEndpoints": true
}

Dove:

application-id è l'ID del progetto Amazon Pinpoint per cui stai importando gli endpoint.
bucket- name/prefix/key è la posizione in Amazon S3 che contiene uno o più oggetti da importare. La posizione può terminare con la chiave per un singolo oggetto oppure con un prefisso che qualifica più oggetti.
iam-import-role-arnè l'Amazon Resource Name (ARN) di un ruolo IAM che concede ad Amazon Pinpoint l'accesso in lettura al bucket.
format può essere JSON o CSV, a seconda del formato utilizzato per definire gli endpoint. Se la posizione Amazon S3 include più file di formati misti, Amazon Pinpoint importa solo i file corrispondenti al formato specificato.

Se la richiesta va a buon fine, riceverai una risposta analoga alla seguente:


{
    "Id": "a995ce5d70fa44adb563b7d0e3f6c6f5",
    "JobStatus": "CREATED",
    "CreationDate": "2018-06-05T21:49:15.288Z",
    "Type": "IMPORT",
    "Definition": {
        "S3Url": "s3://bucket-name/prefix/key",
        "RoleArn": "iam-import-role-arn",
        "ExternalId": "external-id",
        "Format": "JSON",
        "RegisterEndpoints": true,
        "DefineSegment": false
    }
}

La risposta fornisce l'ID processo con l'attributo Id. Puoi usare questo ID per verificare lo stato corrente del processo di importazione.

Esempio Richiesta GET per processo di importazione

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


GET /v1/apps/application_id/jobs/import/job_id HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: pinpoint.us-east-1.amazonaws.com
X-Amz-Date: 20180605T220744Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20180605/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 per cui è stato avviato il processo di importazione.
job_id è l'ID del processo di importazione da verificare.

Se la richiesta va a buon fine, riceverai una risposta analoga alla seguente:


{
    "ApplicationId": "application_id",
    "Id": "70a51b2cf442447492d2c8e50336a9e8",
    "JobStatus": "COMPLETED",
    "CompletedPieces": 1,
    "FailedPieces": 0,
    "TotalPieces": 1,
    "CreationDate": "2018-06-05T22:04:49.213Z",
    "CompletionDate": "2018-06-05T22:04:58.034Z",
    "Type": "IMPORT",
    "TotalFailures": 0,
    "TotalProcessed": 3,
    "Definition": {
        "S3Url": "s3://bucket-name/prefix/key.json",
        "RoleArn": "iam-import-role-arn",
        "ExternalId": "external-id",
        "Format": "JSON",
        "RegisterEndpoints": true,
        "DefineSegment": false
    }
}

La risposta fornisce lo stato del processo con l'attributo JobStatus.

Per ulteriori informazioni sulla risorsa Processi di importazione nell'API Amazon Pinpoint, compresi i metodi HTTP supportati e i parametri della richiesta, consulta l'articolo relativo ai processi di importazione 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

Aggiungi un batch di endpoint

Esportazione degli endpoint da Amazon Pinpoint a bucket Amazon S3