**终止支持通知：** AWS 将于 2026 年 10 月 30 日终止对亚马逊 Pinpoint 的支持。2026 年 10 月 30 日之后，您将不再能够访问 Amazon Pinpoint 控制台或 Amazon Pinpoint 资源（端点、分段、活动、旅程和分析）。有关更多信息，请参阅 [Amazon Pinpoint 终止支持](https://docs.aws.amazon.com/console/pinpoint/migration-guide)。**注意：** APIs 与短信相关、语音、移动推送、OTP 和电话号码验证不受此更改的影响，并受 AWS 最终用户消息的支持。本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 将端点导入 Amazon Pinpoint 可以通过从 Amazon S3 存储桶导入大量端点的方式来添加或更新端点。如果您在 Amazon Pinpoint 之外拥有受众的记录，并且想要将这些信息添加到 Amazon Pinpoint 项目中，则导入端点的方法很有用。在此情况下，请： 1. 创建基于您自己的受众数据的端点定义。 1. 将这些端点定义保存到一个或多个文件中，然后将这些文件上传到 Amazon S3 存储桶。 1. 通过从存储桶导入端点来将端点添加到 Amazon Pinpoint 项目中。每个导入任务可传输多达 1 GB 数据。在典型任务（其中每个端点为 4 KB 或更小）中，可以导入约 250,000 个端点。每个 AWS 账户最多可以运行两个并发导入任务。如果您需要更多带宽来完成导入任务，可以向提交增加服务配额的请求支持。有关更多信息，请参阅 [请求提高限额](quotas.md#quotas-increase)。 ## 开始前的准备工作要导入端点，您的 AWS 账户中需要具备以下资源： + Amazon S3 存储桶。要创建存储桶，请参阅《Amazon Simple Storage Service 用户指南》**中的[创建存储桶](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)。 + 一个 AWS Identity and Access Management (IAM) 角色，用于向 Amazon Pinpoint 授予您的 Amazon S3 存储桶的读取权限。要创建该角色，请参阅[用于导入端点或分段的 IAM 角色](permissions-import-segment.md)。 ## 示例以下示例演示如何将端点定义添加到您的 Amazon S3 存储桶，然后再将这些端点导入 Amazon Pinpoint 项目。 ### 包含端点定义的文件添加到您的 Amazon S3 存储桶的文件可以包含 CSV 或以换行符分隔的 JSON 格式的端点定义。有关可用于定义终端节点的属性，请参阅《*亚马逊 Pinpoint API* 参考》中的 [EndpointRequest](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-endpoints-endpoint-id.html#apps-application-id-endpoints-endpoint-id-schemas)JSON 架构。 ------ #### [ CSV ] 您可以导入在 CSV 文件中定义的端点，如以下示例中所示： ``` ChannelType,Address,Location.Country,Demographic.Platform,Demographic.Make,User.UserId SMS,12065550182,CN,Android,LG,example-user-id-1 APNS,1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f,US,iOS,Apple,example-user-id-2 EMAIL,john.stiles@example.com,US,iOS,Apple,example-user-id-2 ``` 第一行是标头，其中包含端点属性。使用点标记（如 `Location.Country` 中所示）指定嵌套属性。后续行通过为标头中的每个属性提供值来定义端点。要在值中包含逗号或双引号，请将值括在双引号内，如 `"aaa,bbb"`。 CSV 中的值中不支持换行符。 ------ #### [ JSON ] 可以导入在以换行符分隔的 JSON 文件中定义的端点，如以下示例中所示： ``` {"ChannelType":"SMS","Address":"12065550182","Location":{"Country":"CN"},"Demographic":{"Platform":"Android","Make":"LG"},"User":{"UserId":"example-user-id-1"}} {"ChannelType":"APNS","Address":"1a2b3c4d5e6f7g8h9i0j1a2b3c4d5e6f","Location":{"Country":"US"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}} {"ChannelType":"EMAIL","Address":"john.stiles@example.com","Location":{"Country":"US"},"Demographic":{"Platform":"iOS","Make":"Apple"},"User":{"UserId":"example-user-id-2"}} ``` 在此格式中，每一行都是一个完整的 JSON 对象，其中包含单独的端点定义。 ------ ### 导入任务请求以下示例演示如何通过将本地文件上传到存储桶，来将端点定义添加到 Amazon S3。然后，示例将端点定义导入 Amazon Pinpoint 项目。 ------ #### [ AWS CLI ] 可以通过在 AWS CLI中运行命令来使用 Amazon Pinpoint。 **Example S3 CP 命令** 要将本地文件上传到 Amazon S3 存储桶，请使用 Amazon S3 [https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) 命令： ``` $ aws s3 cp ./endpoints-file s3://bucket-name/prefix/ ``` 其中： + *./endpoints-file* 是包含端点定义的本地文件的文件路径。 + *bucket-name/prefix/* 是 Amazon S3 存储桶的名称，并且还可以选择使用前缀，以帮助您按层次组织存储桶中的对象。例如，`pinpoint/imports/endpoints/` 就是一个有用的前缀。 **Example 创建导入任务命令** 要从 Amazon S3 存储桶导入端点定义，请使用 [https://docs.aws.amazon.com/cli/latest/reference/pinpoint/create-import-job.html](https://docs.aws.amazon.com/cli/latest/reference/pinpoint/create-import-job.html) 命令： ``` $ 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 ``` 其中： + *application-id* 是要为之导入端点的 Amazon Pinpoint 项目的 ID。 + *存储桶name/prefix/key*是 Amazon S3 中包含一个或多个要导入的对象的位置。此位置可以用单个对象的键结尾，也可以用符合多个对象条件的前缀结尾。 + *iam-import-role-arn*是 IAM 角色的亚马逊资源名称 (ARN)，该角色授予 Amazon Pinpoint 对存储桶的读取权限。 + *format* 可以为 `JSON` 或 `CSV`，具体情况取决于定义端点时使用的格式。如果 Amazon S3 位置包含多个混合格式的对象，则 Amazon Pinpoint 将仅导入与指定格式匹配的对象。 + *RegisterEndpoints* 可以是 `true` 或 `false`。当设置为 true 时，导入任务会在导入端点定义时向 Amazon Pinpoint 注册端点。 **RegisterEndpoints 和 DefineSegments 组合** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/pinpoint/latest/developerguide/audience-define-import.html) 响应包含有关导入任务的详细信息： ``` { "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" } } ``` 响应通过 `Id` 属性提供任务 ID。可以使用此 ID 检查导入任务的当前状态。 **Example 获取导入任务命令** 要检查导入任务的当前状态，请使用 `get-import-job` 命令： ``` $ aws pinpoint get-import-job \ > --application-id application-id \ > --job-id job-id ``` 其中： + *application-id* 是要为之启动导入任务的 Amazon Pinpoint 项目的 ID。 + *job-id* 是正检查的导入任务的 ID。此命令的响应提供导入任务的当前状态： ``` { "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" } } ``` 响应通过 `JobStatus` 属性提供任务状态。 ------ #### [ 适用于 Java 的 AWS SDK ] 您可以通过使用适用于 Java 的 AWS SDK提供的客户端在您的 Java 应用程序中使用 Amazon Pinpoint API。 **Example 代码** 要将包含端点定义的文件上传到 Amazon S3，请使用 `AmazonS3` 客户端的 `putObject` 方法。要将端点导入 Amazon Pinpoint 项目，请初始化 `CreateImportJobRequest` 对象。然后，将此对象传递到 `AmazonPinpoint` 客户端的 `createImportJob` 方法。 ``` 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 " + "\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 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 ] 可以通过直接向 REST API 发出 HTTP 请求来使用 Amazon Pinpoint。 **Example S3 PUT 对象请求** 要将端点定义添加到存储桶，请使用 Amazon S3 [PUT 对象](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)操作，并提供端点定义作为正文： ``` 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"}} ``` 其中： + */prefix/key* 是上传后将包含端点定义的对象的前缀和键名。可以使用此前缀分层次组织对象。例如，`pinpoint/imports/endpoints/` 就是一个有用的前缀。 + *bucket-name* 是要将端点定义添加到的 Amazon S3 存储桶的名称。 **Example POST 导入任务请求** 要从 Amazon S3 存储桶导入端点定义，请向[导入任务](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-jobs-import.html)资源发出 POST 请求。在您的请求中，包含所需的标题并提供 [ImportJobRequest](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-jobs-import.html#apps-application-id-jobs-import-schemas)JSON 作为正文： ``` 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 } ``` 其中： + *application-id* 是要为之导入端点的 Amazon Pinpoint 项目的 ID。 + *存储桶name/prefix/key*是 Amazon S3 中包含一个或多个要导入的对象的位置。此位置可以用单个对象的键结尾，也可以用符合多个对象条件的前缀结尾。 + *iam-import-role-arn*是 IAM 角色的亚马逊资源名称 (ARN)，该角色授予 Amazon Pinpoint 对存储桶的读取权限。 + *format* 可以为 `JSON` 或 `CSV`，具体情况取决于定义端点时使用的格式。如果 Amazon S3 位置包含多个混合格式的文件，则 Amazon Pinpoint 将仅导入与指定格式匹配的文件。如果您的请求成功，将收到与下类似的响应： ``` { "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 } } ``` 响应通过 `Id` 属性提供任务 ID。可以使用此 ID 检查导入任务的当前状态。 **Example GET 导入任务请求** 要检查导入任务的当前状态，请向[导入任务](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-jobs-import-job-id.html)资源发出 `GET` 请求： ``` 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 ``` 其中： + *application\$1id* 是已为之启动导入任务的 Amazon Pinpoint 项目的 ID。 + *job\$1id* 是正检查的导入任务的 ID。如果您的请求成功，将收到与下类似的响应： ``` { "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 } } ``` 响应通过 `JobStatus` 属性提供任务状态。 ------ ## 相关信息有关 Amazon Pinpoint API 中的导入任务资源的更多信息，包括支持的 HTTP 方法和请求参数，请参阅《Amazon Pinpoint API 参考》中的[导入任务](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-jobs-import.html)**。