Antes de começar Exemplos Informações relacionadas

Aviso de fim do suporte: em 30 de outubro de 2026, AWS encerrará o suporte para o Amazon Pinpoint. Depois de 30 de outubro de 2026, você não poderá mais acessar o console do Amazon Pinpoint ou os recursos do Amazon Pinpoint (endpoints, segmentos, campanhas, viagens e análises). Para obter mais informações, consulte Fim do suporte do Amazon Pinpoint. Observação: APIs relacionados a SMS, voz, push móvel, OTP e validação de número de telefone não são afetados por essa alteração e são compatíveis com o AWS End User Messaging.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Importar endpoints para o Amazon Pinpoint

Você pode adicionar ou atualizar um grande número de endpoints importando-os de um bucket do Amazon S3. A importação de endpoints é útil se você tiver registros sobre seu público-alvo fora do Amazon Pinpoint e desejar adicionar essas informações para um projeto do Amazon Pinpoint. Nesse caso, você deve:

Criar definições de endpoints com base nos dados de seu próprio público-alvo.
Salvar essas definições de endpoints em um ou mais arquivos e fazer upload dos arquivos em um bucket do Amazon S3.
Adicionar os endpoints a seu projeto do Amazon Pinpoint importando-os do bucket.

Cada tarefa de importação pode transferir até 1 GB de dados. Em uma tarefa típica, onde cada endpoint tem 4 KB ou menos, você pode importar cerca de 250.000 endpoints. Você pode executar até dois trabalhos de importação simultâneos por AWS conta. Se precisar de mais largura de banda para seus trabalhos de importação, você pode enviar uma solicitação de aumento de cota de serviço para. Suporte Para obter mais informações, consulte Solicitar um aumento de cota.

Antes de começar

Para poder importar endpoints, você precisa dos seguintes recursos em sua conta da AWS :

Um bucket do Amazon S3. Para criar um bucket, veja Criação de um bucket no Guia do usuário do Amazon Simple Storage Service.
Uma função AWS Identity and Access Management (IAM) que concede permissões de leitura ao Amazon Pinpoint para seu bucket do Amazon S3. Para criar o perfil, consulte Perfil do IAM para importação de endpoints ou segmentos.

Exemplos

Os exemplos a seguir demonstram como adicionar definições de endpoints a seu bucket do Amazon S3 e, depois, importar esses endpoints em um projeto do Amazon Pinpoint.

Arquivos com definições de endpoints

Os arquivos que você adiciona ao bucket do Amazon S3 podem conter definições de endpoint em formato CSV ou JSON delimitado por novas linhas. Para os atributos que você pode usar para definir seus endpoints, consulte o esquema EndpointRequestJSON na Referência da API do Amazon Pinpoint.

Solicitações de trabalhos de importação

Os exemplos a seguir mostram como adicionar definições de endpoint ao Amazon S3 fazendo upload de um arquivo local em um bucket. Em seguida, os exemplos importam as definições de endpoint em um projeto do Amazon Pinpoint.

AWS CLI

Você pode usar o Amazon Pinpoint executando comandos com a AWS CLI.

exemplo Comando CP do S3

Para fazer upload de um arquivo local em um bucket do Amazon S3, use o comando cp do Amazon S3:


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

Em que:

./endpoints-file é o caminho do arquivo para um arquivo local que contém as definições de endpoints.
bucket-name/prefix/ é o nome de seu bucket do Amazon S3 e, opcionalmente, um prefixo que ajuda a organizar os objetos em seu bucket hierarquicamente. Por exemplo, um prefixo útil pode ser pinpoint/imports/endpoints/.

exemplo Comando Create import job

Para importar definições de endpoint de um bucket do Amazon S3, use o 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

Em que:

application-id é o ID do projeto do Amazon Pinpoint para o qual você está importando endpoints.
bucket- name/prefix/key é o local no Amazon S3 que contém um ou mais objetos a serem importados. A localização pode terminar com a chave de um objeto individual ou terminar com um prefixo que qualifica vários objetos.
iam-import-role-arné o Amazon Resource Name (ARN) de uma função do IAM que concede ao Amazon Pinpoint acesso de leitura ao bucket.
O formato poder ser JSON ou CSV, dependendo do formato que você usou para definir os endpoints. Se o local do Amazon S3 incluir vários objetos de formatos mistos, o Amazon Pinpoint importará apenas os objetos que corresponderem ao formato especificado.

RegisterEndpoints pode ser true ou false. Quando definido como verdadeiro, o trabalho de importação registra os endpoints no Amazon Pinpoint, quando as definições do endpoint são importadas.

RegisterEndpoints e DefineSegments combinações
RegisterEndpoints	DefineSegments	Descrição
true	true	O Amazon Pinpoint importará os endpoints e criará um segmento que contém os endpoints.
verdadeiro	false	O Amazon Pinpoint importará os endpoints e não criará um segmento.
false	verdadeiro	O Amazon Pinpoint importará os endpoints e criará um segmento que contém os endpoints. Os endpoints não serão salvos e não substituirão os endpoints existentes.
false	false	O Amazon Pinpoint rejeitará essa solicitação.

A resposta inclui detalhes sobre o trabalho de importação:


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

A resposta fornece o ID do trabalho com o atributo Id. Você pode usar esse ID para verificar o status atual do trabalho de importação.

exemplo Comando Get import job

Para verificar o status atual do trabalho de importação, use o comando get-import-job:


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

Em que:

application-id é o ID do projeto do Amazon Pinpoint para o qual o trabalho de importação foi iniciado.
job-id é o ID do trabalho de importação que você está verificando.

A resposta a esse comando fornece o estado atual do trabalho de importação:


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

A resposta fornece o status do trabalho com o atributo JobStatus.

AWS SDK para Java

Você pode usar a API do Amazon Pinpoint em seus aplicativos Java usando o cliente fornecido pelo AWS SDK para Java.

exemplo Código

Para fazer upload de um arquivo com definições de endpoint para o Amazon S3, use o método putObject do cliente AmazonS3.

Para importar os endpoints em um projeto do Amazon Pinpoint, inicialize um objeto CreateImportJobRequest. Em seguida, passe esse objeto para o método createImportJob do cliente do 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

Você pode usar o Amazon Pinpoint fazendo solicitações HTTP diretamente para a API REST.

exemplo Solicitação de objeto PUT do S3

Para adicionar suas definições de endpoint a um bucket, use a operação PUT object do Amazon S3 e forneça as definições de endpoint como o 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"}}

Em que:

/prefix/key é o prefixo e o nome da chave do objeto que conterá as definições de endpoints após o upload. Você pode usar o prefixo para organizar seus objetos hierarquicamente. Por exemplo, um prefixo útil pode ser pinpoint/imports/endpoints/.
bucket-name é o nome do bucket do Amazon S3 ao qual você está adicionando as definições de endpoint.

exemplo Solicitação POST de trabalho de importação

Para importar definições de endpoint de um bucket do Amazon S3, envie uma solicitação POST para o recurso Tarefas de importação. Em sua solicitação, inclua os cabeçalhos necessários e forneça o ImportJobRequestJSON como 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
}

Em que:

application-id é o ID do projeto do Amazon Pinpoint para o qual você está importando endpoints.
bucket- name/prefix/key é o local no Amazon S3 que contém um ou mais objetos a serem importados. A localização pode terminar com a chave de um objeto individual ou terminar com um prefixo que qualifica vários objetos.
iam-import-role-arné o Amazon Resource Name (ARN) de uma função do IAM que concede ao Amazon Pinpoint acesso de leitura ao bucket.
O formato poder ser JSON ou CSV, dependendo do formato que você usou para definir os endpoints. Se o local do Amazon S3 incluir vários arquivos de formatos mistos, o Amazon Pinpoint importará apenas os arquivos que corresponderem ao formato especificado.

Se sua solicitação for bem-sucedida, você receberá uma resposta como a seguinte:


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

A resposta fornece o ID do trabalho com o atributo Id. Você pode usar esse ID para verificar o status atual do trabalho de importação.

exemplo Solicitação GET de trabalho de importação

Para verificar o status atual de uma tarefa de importação, envie uma solicitação GET para o recurso Tarefas de importação:


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

Em que:

application_id é o ID do projeto do Amazon Pinpoint para o qual o trabalho de importação foi iniciado.
job_id é o ID do trabalho de importação que você está verificando.

Se sua solicitação for bem-sucedida, você receberá uma resposta como a seguinte:


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

A resposta fornece o status do trabalho com o atributo JobStatus.

Para obter mais informações sobre o recurso de trabalhos de exportação na API do Amazon Pinpoint, incluindo os métodos HTTP e os parâmetros de solicitação compatíveis, consulte Trabalhos de importação na Referência da API do Amazon Pinpoint.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Adicionar um lote de endpoints

Exportar endpoints do Amazon Pinpoint para buckets do Amazon S3