Importing segments - Amazon Pinpoint

Importing segments

With Amazon Pinpoint, you can define a user segment by importing information about the endpoints that belong to the segment. An endpoint is a single messaging destination, such as a mobile push device token, a mobile phone number, or an email address.

Importing segments is useful if you've already created segments of your users outside of Amazon Pinpoint but you want to engage your users with Amazon Pinpoint campaigns.

When you import a segment, Amazon Pinpoint gets the segment's endpoints from Amazon Simple Storage Service (Amazon S3). Before you import, you add the endpoints to Amazon S3, and you create an IAM role that grants Amazon Pinpoint access to Amazon S3. Then, you give Amazon Pinpoint the Amazon S3 location where the endpoints are stored, and Amazon Pinpoint adds each endpoint to the segment.

To create the IAM role, see IAM role for importing endpoints or segments. For information about importing a segment by using the Amazon Pinpoint console, see Importing segments in the Amazon Pinpoint User Guide.

Importing a segment

The following example demonstrates how to import a segment by using the AWS SDK for Java.

import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.ImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.ImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.Format; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException;
import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.pinpoint.PinpointClient; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.ImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.ImportJobRequest; import software.amazon.awssdk.services.pinpoint.model.Format; import software.amazon.awssdk.services.pinpoint.model.CreateImportJobResponse; import software.amazon.awssdk.services.pinpoint.model.PinpointException; /** * Before running this Java V2 code example, set up your development * environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class ImportSegment { public static void main(String[] args) { final String usage = """ Usage: <appId> <bucket> <key> <roleArn>\s Where: appId - The application ID to create a segment for. bucket - The name of the Amazon S3 bucket that contains the segment definitons. key - The key of the S3 object. roleArn - ARN of the role that allows Amazon Pinpoint to access S3. You need to set trust management for this to work. See https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html """; if (args.length != 4) { System.out.println(usage); System.exit(1); } String appId = args[0]; String bucket = args[1]; String key = args[2]; String roleArn = args[3]; PinpointClient pinpoint = PinpointClient.builder() .region(Region.US_EAST_1) .build(); ImportJobResponse response = createImportSegment(pinpoint, appId, bucket, key, roleArn); System.out.println("Import job for " + bucket + " submitted."); System.out.println("See application " + response.applicationId() + " for import job status."); System.out.println("See application " + response.jobStatus() + " for import job status."); pinpoint.close(); } public static ImportJobResponse createImportSegment(PinpointClient client, String appId, String bucket, String key, String roleArn) { try { ImportJobRequest importRequest = ImportJobRequest.builder() .defineSegment(true) .registerEndpoints(true) .roleArn(roleArn) .format(Format.JSON) .s3Url("s3://" + bucket + "/" + key) .build(); CreateImportJobRequest jobRequest = CreateImportJobRequest.builder() .importJobRequest(importRequest) .applicationId(appId) .build(); CreateImportJobResponse jobResponse = client.createImportJob(jobRequest); return jobResponse.importJobResponse(); } catch (PinpointException e) { System.err.println(e.awsErrorDetails().errorMessage()); System.exit(1); } return null; } }

For the full SDK example, see ImportingSegments.java on GitHub.