**支援終止通知：**2026 年 10 月 30 日， AWS 將結束對 Amazon Pinpoint 的支援。2026 年 10 月 30 日之後，您將無法再存取 Amazon Pinpoint 主控台或 Amazon Pinpoint 資源 (端點、區段、行銷活動、旅程和分析)。如需詳細資訊，請參閱 [Amazon Pinpoint 終止支援](https://docs.aws.amazon.com/console/pinpoint/migration-guide)。**注意：**與 SMS、語音、行動推播、OTP 和電話號碼驗證相關的 APIs 不受此變更影響，並受 AWS 最終使用者傳訊支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將端點匯入 Amazon Pinpoint
<a name="audience-define-import"></a>

將端點從 Amazon S3 儲存貯體匯入，可以新增或更新大量端點。若在 Amazon Pinpoint 以外的地方有受眾記錄，而且想將此資訊加入 Amazon Pinpoint 專案，匯入端點是有用的方法。在此情況下，您可以：

1. 建立根據您自己的對象資料的端點定義。

1. 請將這些端點定義儲存在一個或多個檔案中，並將檔案上傳至 Amazon S3 儲存貯體。

1. 將端點從儲存貯體匯入，可以將端點加入 Amazon Pinpoint 專案。

每個匯入任務可傳輸最多 1 GB 的資料。在一般任務中，其中的每個端點為 4 KB 或更少，您可以匯入大約 250,000 個端點。每個 AWS 帳戶最多可以執行兩個並行匯入任務。如果您的匯入任務需要更多頻寬，您可以向 提交服務配額增加請求 支援。如需詳細資訊，請參閱[請求提高配額](quotas.md#quotas-increase)。

## 開始之前
<a name="audience-define-import-before"></a>

在您可以匯入端點之前，您需要您的 AWS 帳戶中的下列資源：
+ Amazon S3 儲存貯體。若要建立儲存貯體，請參閱 *Amazon Simple Storage Service 使用者指南*中的[建立儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html)。
+ 為 Amazon S3 儲存貯體授予 Amazon Pinpoint 讀取許可的 AWS Identity and Access Management (IAM) 角色。 Amazon S3 若要建立角色，請參閱[用於匯入端點或客群的 IAM 角色](permissions-import-segment.md)。

## 範例
<a name="audience-define-import-examples"></a>

以下範例說明如何將端點定義加入 Amazon S3 儲存貯體，然後將這些端點匯入 Amazon Pinpoint 專案。

### 含有端點定義的檔案
<a name="audience-define-import-examples-files"></a>

您加入 Amazon S3 儲存貯體的檔案，可以包含 CSV 格式或換行分隔 JSON 格式的端點定義。如需可用於定義端點的屬性，請參閱 *Amazon 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 物件，其中包含個別端點定義。

------

### 匯入任務請求
<a name="audience-define-import-examples-jobs"></a>

以下範例說明如何透過將本機檔案上傳到儲存貯體，將端點定義加入 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 Create Import Job 命令**  
若要從 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。
+ *bucket-name/prefix/key* 是 Amazon S3 中的一個位置，包含一個或多個要匯入的物件。位置的結尾可以是個別物件的金鑰，或者結尾可以是符合多個物件的字首。
+ *iam-import-role-arn* 是 IAM 角色的 Amazon Resource Name (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_tw/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 命令**  
若要檢查匯入任務的目前狀態，請使用 `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 Code**  
若要將有端點定義的檔案上傳到 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 <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 ]

對 REST API 直接提出 HTTP 請求，可以使用 Amazon Pinpoint。

**Example S3 PUT Object 請求**  
若要將端點定義加入儲存貯體，請使用 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 Import Job 請求**  
若要從 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。
+ *bucket-name/prefix/key* 是 Amazon S3 中的一個位置，包含一個或多個要匯入的物件。位置的結尾可以是個別物件的金鑰，或者結尾可以是符合多個物件的字首。
+ *iam-import-role-arn* 是 IAM 角色的 Amazon Resource Name (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 Import Job 請求**  
若要檢查匯入任務目前的狀態，請向[匯入任務](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` 屬性提供任務狀態。

------

## 相關資訊
<a name="audience-define-import-related"></a>

如需 Amazon Pinpoint API 中匯入任務資源的詳細資訊 (包括支援的 HTTP 方法和請求參數)，請參閱 *Amazon Pinpoint API 參考*中的[匯入任務](https://docs.aws.amazon.com/pinpoint/latest/apireference/apps-application-id-jobs-import.html)。