Antes de empezar Ejemplos Información relacionada

Aviso de fin de soporte: el 30 de octubre de 2026, AWS finalizará el soporte para Amazon Pinpoint. Después del 30 de octubre de 2026, ya no podrá acceder a la consola de Amazon Pinpoint ni a los recursos de Amazon Pinpoint (puntos de conexión, segmentos, campañas, recorridos y análisis). Para obtener más información, consulte Fin de soporte de Amazon Pinpoint. Nota: Este cambio no afecta a las API relacionadas con los SMS, los mensajes de voz, las notificaciones push móviles, la OTP y la validación de números de teléfono, por lo que son compatibles con Mensajería para usuarios finales de AWS.

Importar puntos de conexión a Amazon Pinpoint

Puede agregar o actualizar puntos de conexión a gran escala importándolos desde un bucket de Amazon S3. La importación de puntos de conexión resulta útil si tiene registros sobre el público fuera de Amazon Pinpoint y desea agregar esta información a un proyecto de Amazon Pinpoint. En este caso, debería hacer lo siguiente:

Crear definiciones de punto de enlace basadas en sus propios datos de público.
Guarde estas definiciones de punto de conexión en uno o más archivos y cargue los archivos en un bucket de Amazon S3.
Agregue los puntos de conexión al proyecto de Amazon Pinpoint importándolos desde el bucket.

Cada trabajo de importación puede transferir hasta 1 GB de datos. En un trabajo típico, en el que cada punto de enlace tiene 4 KB o menos, puede importar en torno a 250 000 puntos de enlace. Puede ejecutar hasta dos trabajos de importación simultáneos por cuenta de AWS. Si necesita más ancho de banda para sus trabajos de importación, puede enviar una solicitud de aumento de cuota de servicio a Soporte. Para obtener más información, consulte Solicitud de aumento de cuota.

Antes de empezar

Para poder importar los puntos de enlace, son precisos los siguientes recursos en su cuenta de AWS:

Un bucket de Amazon S3. Para crear un bucket, consulte Crear un bucket en la Guía del usuario de Amazon Simple Storage Service.
Un rol de AWS Identity and Access Management (IAM) que conceda a Amazon Pinpoint permisos de lectura para el bucket de Amazon S3. Para crear la función, consulte Rol de IAM para importar puntos de conexión o segmentos.

Ejemplos

Los siguientes ejemplos muestran cómo agregar definiciones de punto de conexión al bucket de Amazon S3 y, a continuación, importar dichos puntos de conexión en un proyecto de Amazon Pinpoint.

Archivos con definiciones de puntos de enlace

Los archivos que agrega al bucket de Amazon S3 pueden contener definiciones de punto de conexión en formato CSV o JSON delimitado por saltos de línea. Para los atributos que puede utilizar para definir los puntos de conexión, consulte el esquema EndpointRequest de JSON en la Referencia de la API de Amazon Pinpoint.

Solicitudes de trabajo de importación

Los siguientes ejemplos muestran cómo agregar definiciones de puntos de conexión a Amazon S3 cargando un archivo local en un bucket. A continuación, los ejemplos importan las definiciones de puntos de conexión en un proyecto de Amazon Pinpoint.

AWS CLI

Puede utilizar Amazon Pinpoint ejecutando comandos con la AWS CLI.

ejemplo Comando CP de S3

Para cargar un archivo local a un bucket de Amazon S3, utilice el comando cp de Amazon S3:


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

Donde:

./endpoints-file es la ruta de archivo a un archivo local que contiene definiciones de punto de enlace.
bucket-name/prefix es el nombre del bucket de Amazon S3 y, opcionalmente, un prefijo que le ayuda a organizar los objetos en el bucket de forma jerárquica. Por ejemplo, un prefijo útil puede ser pinpoint/imports/endpoints/.

ejemplo Comando Create Import Job

Para importar las definiciones de puntos de conexión desde un bucket de Amazon S3, utilice el 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

Donde:

application-id es el ID del proyecto de Amazon Pinpoint para el que está importando los puntos de conexión.
bucket-name/prefix/key es la ubicación en Amazon S3 que contiene uno o más objetos que importar. La ubicación puede finalizar con la clave para un objeto individual o puede terminar con un prefijo que califica varios objetos.
iam-import-role-arn es el nombre de recurso de Amazon (ARN) de un rol de IAM que concede a Amazon Pinpoint acceso de lectura al bucket.
format puede ser JSON o bien CSV, en función del formato que haya utilizado para definir los puntos de enlace. Si la ubicación de Amazon S3 incluye varios objetos de formatos mixtos, Amazon Pinpoint solo importa los objetos que coinciden con el formato especificado.

RegisterEndpoints puede ser true o false. Si se establece en verdadero, el trabajo de importación registra los puntos de conexión con Amazon Pinpoint, cuando se importan las definiciones de los puntos de conexión.

Combinaciones RegisterEndpoints y DefineSegments
RegisterEndpoints	DefineSegments	Descripción
true	true	Amazon Pinpoint importará los puntos de conexión y creará un segmento que los contenga.
true	false	Amazon Pinpoint importará los puntos de conexión y no creará un segmento.
false	true	Amazon Pinpoint importará los puntos de conexión y creará un segmento que los contenga. Los puntos de conexión no se guardarán ni sobrescribirán los puntos de conexión existentes.
false	false	Amazon Pinpoint rechazará esta solicitud.

La respuesta incluye detalles acerca del trabajo de importación:


{
    "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 respuesta proporciona el ID de trabajo con el atributo Id. Puede utilizar este ID para comprobar el estado actual del trabajo de importación.

ejemplo Comando Get Import Job

Para comprobar el estado actual de un trabajo de importación, utilice el comando get-import-job:


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

Donde:

application-id es el ID del proyecto de Amazon Pinpoint para el que se inició el trabajo de importación.
job-id es el ID del trabajo de importación que está comprobando.

La respuesta a este comando ofrece el estado actual del trabajo de importación:


{
    "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 respuesta proporciona el estado de trabajo con el atributo JobStatus.

AWS SDK para Java

Puede usar la API de Amazon Pinpoint en las aplicaciones Java mediante el cliente que proporciona AWS SDK para Java.

ejemplo Código

Para cargar un archivo con definiciones de puntos de conexión en Amazon S3, utilice el método putObject del cliente de AmazonS3.

Para importar los puntos de conexión en un proyecto de Amazon Pinpoint, inicialice un objeto CreateImportJobRequest. A continuación, transfiera este objeto al método createImportJob del cliente de 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

Puede utilizar Amazon Pinpoint realizando solicitudes HTTP directamente a la API de REST.

ejemplo Solicitud PUT Object de S3

Para agregar las definiciones de puntos de conexión a un bucket, utilice la operación PUT object de Amazon S3 y proporcione las definiciones del punto de conexión como cuerpo:


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

Donde:

/prefix/key es el prefijo y nombre de clave para el objeto que contendrá las definiciones de puntos de enlace después de la carga. Puede utilizar el prefijo para organizar sus objetos jerárquicamente. Por ejemplo, un prefijo útil puede ser pinpoint/imports/endpoints/.
bucket-name es el nombre del bucket de Amazon S3 al que está agregando las definiciones de puntos de conexión.

ejemplo Solicitud POST de trabajo de importación

Para importar definiciones de puntos de conexión desde un bucket de Amazon S3, emita una solicitud POST al recurso Trabajos de importación. En su solicitud, incluya los encabezados necesarios y proporcione el JSON ImportJobRequest como cuerpo:


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
}

Donde:

application-id es el ID del proyecto de Amazon Pinpoint para el que está importando los puntos de conexión.
bucket-name/prefix/key es la ubicación en Amazon S3 que contiene uno o más objetos que importar. La ubicación puede finalizar con la clave para un objeto individual o puede terminar con un prefijo que califica varios objetos.
iam-import-role-arn es el nombre de recurso de Amazon (ARN) de un rol de IAM que concede a Amazon Pinpoint acceso de lectura al bucket.
format puede ser JSON o bien CSV, en función del formato que haya utilizado para definir los puntos de enlace. Si la ubicación de Amazon S3 incluye varios archivos de formatos mixtos, Amazon Pinpoint solo importa los archivos que coincidan con el formato especificado.

Si la solicitud se realiza correctamente, recibirá una respuesta similar a la siguiente:


{
    "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 respuesta proporciona el ID de trabajo con el atributo Id. Puede utilizar este ID para comprobar el estado actual del trabajo de importación.

ejemplo Solicitud GET de trabajo de importación

Para comprobar el estado actual de un trabajo de importación, emita una solicitud GET al recurso Trabajo de importación:


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

Donde:

application_id es el ID del proyecto de Amazon Pinpoint para el que se inició el trabajo de importación.
job_id es el ID del trabajo de importación que está comprobando.

Si la solicitud se realiza correctamente, recibirá una respuesta similar a la siguiente:


{
    "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 respuesta proporciona el estado de trabajo con el atributo JobStatus.

Para obtener más información acerca del recurso Trabajos de importación en la API de Amazon Pinpoint, incluidos los métodos HTTP compatibles y los parámetros de solicitud, consulte Trabajos de importación en la Referencia de la API de Amazon Pinpoint.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Agregar un lote de puntos de conexión

Exportar puntos de conexión de Amazon Pinpoint a buckets de Amazon S3