Bevor Sie beginnen Beispiele Ähnliche Informationen

Importieren von Endpunkten in Amazon Pinpoint

Sie können sehr viele Endpunkte hinzufügen oder aktualisieren, indem Sie sie aus einem Amazon-S3-Bucket importieren. Das Importieren von Endpunkten ist nützlich, wenn Sie die Aufzeichnungen zu Ihrer Zielgruppe außerhalb von Amazon Pinpoint vorliegen haben und diese Informationen einem Amazon-Pinpoint-Projekt hinzufügen möchten. In diesem Fall müssen Sie wie folgt verfahren:

Erstellen Sie Endpunktdefinitionen, die auf Ihren eigenen Zielgruppendaten basieren.
Speichern Sie diese Endpunktdefinitionen in einer oder mehreren Dateien, und laden Sie die Dateien in einen Amazon-S3-Bucket.
Fügen Sie Ihrem Amazon-Pinpoint-Projekt die Endpunkte hinzu, indem Sie sie aus dem Bucket importieren.

Jede Importauftrag kann bis zu 1 GB Daten übertragen. In einem typischen Auftrag, wobei jeder Endpunkt 4 KB oder kleiner ist, können Sie ca. 250.000 Endpunkte importieren. Sie können bis zu zwei gleichzeitige Importaufträge pro AWS-Konto ausführen. Wenn Sie mehr Bandbreite für Ihre Importaufträge benötigen, können Sie eine Erhöhung des Servicekontingents bei AWS Support anfordern. Weitere Informationen finden Sie unter Beantragen einer Kontingenterhöhung.

Bevor Sie beginnen

Bevor Sie Endpunkte importieren können, benötigen Sie die folgenden Ressourcen in Ihrem AWS-Konto:

Ein Amazon-S3-Bucket Informationen zum Erstellen eines Buckets finden Sie unter Erstellen eines Buckets im Benutzerhandbuch für Amazon Simple Storage Service.
Eine AWS Identity and Access Management (IAM)-Rolle, die Amazon Pinpoint Leseberechtigungen für Ihren Amazon-S3-Bucket erteilt. Weitere Informationen zum Erstellen der Rolle finden Sie unter IAM-Rolle für das Importieren von Endpunkten oder Segmenten.

Beispiele

Die folgenden Beispiele zeigen, wie Sie Ihrem Amazon-S3-Bucket Endpunktdefinitionen hinzufügen, und diese Endpunkte dann in ein Amazon-Pinpoint-Projekt importieren.

Dateien mit Endpunktdefinitionen

Die Dateien, die Sie Ihrem Amazon-S3-Bucket hinzufügen, können Endpunktdefinitionen im CSV- oder JSON-Format mit Trennung durch neue Zeilen enthalten. Weitere Informationen zu den Attributen, die Sie verwenden können, um Ihre Endpunkte zu definieren, finden Sie im EndpointRequest-JSON-Schema in der Amazon-Pinpoint-API-Referenz.

CSV

Sie können Endpunkte importieren, die in einer CSV-Datei definiert sind, wie im folgenden Beispiel dargestellt:


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

Bei der ersten Zeile handelt es sich um die Kopfzeile, die die Endpunkt-Attribute enthält. Geben Sie verschachtelte Attribute unter Verwendung der Punktnotation an, wie in Location.Country gezeigt.

Die nachfolgenden Zeilen definieren die Endpunkte anhand von Werten für jedes Attribut in der Kopfzeile.

Wenn Sie ein Komma oder doppelte Anführungszeichen in einen Wert einschließen möchten, verwenden Sie doppelte Anführungszeichen für den Wert, z. B. "aaa,bbb".

Zeilenumbrüche werden innerhalb eines Werts in der CSV nicht unterstützt.

JSON

Sie können Endpunkte importieren, die in einer JSON-Datei mit Trennung durch neue Zeilen definiert sind, wie im folgenden Beispiel dargestellt:


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

In diesem Format ist jede Zeile ein vollständiges JSON-Objekt mit einer einzelnen Endpunktdefinition.

Importauftrags-Anforderungen

Die folgenden Beispiele zeigen Ihnen, wie Sie Endpunktdefinitionen zu Amazon S3 hinzufügen, indem Sie eine lokale Datei in einen Bucket hochladen. Anschließend importieren die Beispiele die Endpunkt-Definitionen in ein Amazon-Pinpoint-Projekt.

AWS CLI

Sie können Amazon Pinpoint verwenden, indem Sie Befehle mit der AWS CLI ausführen.

Beispiel S3 CP-Befehl

Um eine lokale Datei in einen Amazon-S3-Bucket hochzuladen, verwenden Sie den Amazon-S3-Befehl cp:


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

Wobei gilt:

/endpoints-file ist der Dateipfad zu einer lokalen Datei, die die Endpunkt-Definitionen enthält.
bucket-name/prefix/ ist der Name Ihres Amazon-S3-Buckets und optional ein Präfix, das Ihnen hilft, die Objekte in Ihrem Bucket hierarchisch zu organisieren. Ein praktisches Präfix könnte beispielsweise pinpoint/imports/endpoints/ sein.

Beispiel Befehl zum Erstellen eines Importauftrags

Um Endpunktdefinitionen aus einem Amazon-S3-Bucket zu importieren, verwenden Sie den folgenden create-import-job-Befehl:


$ 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

Wobei gilt:

application-id ist die ID des Amazon-Pinpoint-Projekts, für das Sie Endpunkte importieren
bucket-name/prefix/key ist der Speicherort in Amazon S3, der ein oder mehrere Objekte zum Importieren enthält. Der Speicherort kann mit dem Schlüssel für ein einzelnes Objekt enden, oder mit einem Präfix, das mehrere Objekte qualifiziert.
iam-import-role-arn ist der Amazon-Ressourcenname (ARN) einer IAM-Rolle, die Amazon Pinpoint Lesezugriff auf den Bucket erteilt.
Format kann JSON oder CSV sein, abhängig davon, mit welchem Format Sie Ihre Endpunkte definiert haben. Wenn der Amazon-S3-Speicherort mehrere Objekte mit gemischten Formaten enthält, importiert Amazon Pinpoint nur die Objekte, die mit dem angegebenen Format übereinstimmen.

RegisterEndpoints kann entweder true oder false sein. Bei der Einstellung „true“ registriert der Importauftrag die Endpunkte mit Amazon Pinpoint, wenn die Endpunktdefinitionen importiert werden.

Kombinationen aus RegisterEndpoints und DefineSegments
RegisterEndpoints	DefineSegments	Beschreibung
true	true	Amazon Pinpoint importiert die Endpunkte und erstellt ein Segment, das die Endpunkte enthält.
true	false	Amazon Pinpoint importiert die Endpunkte und erstellt kein Segment.
false	true	Amazon Pinpoint importiert die Endpunkte und erstellt ein Segment, das die Endpunkte enthält. Die Endpunkte werden nicht gespeichert und überschreiben keine vorhandenen Endpunkte.
false	false	Amazon Pinpoint lehnt diese Anfrage ab.

Die Antwort enthält Details über den Importauftrag:


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

Die Ausgabe stellt die Auftrags-ID mit dem Id-Attribut bereit. Diese ID können Sie verwenden, um den aktuellen Status des Importauftrags zu überprüfen.

Beispiel Befehl zum Abrufen eines Importauftrags

Um den aktuellen Status eines Importauftrags zu überprüfen, verwenden Sie den Befehl get-import-job:


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

Wobei gilt:

application-id ist die ID des Amazon-Pinpoint-Projekts, für das der Importauftrag initiiert wurde.
job-id ist die ID des Importauftrags, den Sie überprüfen.

Die Ausgabe dieses Befehls stellt Informationen über den aktuellen Status des Importauftrags bereit:


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

Die Ausgabe stellt den Auftragsstatus mit dem JobStatus-Attribut bereit.

AWS SDK for Java

Sie können die Amazon-Pinpoint-API in Ihren Java-Anwendungen verwenden, indem Sie den vom AWS SDK for Java bereitgestellten Client verwenden.

Beispiel Code

Um eine Datei mit Endpunktdefinitionen in Amazon S3 hochzuladen, verwenden Sie die Methode putObject des AmazonS3-Clients.

Um Endpunkte in ein Amazon-Pinpoint-Projekt zu importieren, initialisieren Sie ein CreateImportJobRequest-Objekt. Anschließend übergeben Sie dieses Objekt der Methode createImportJob des AmazonPinpoint-Clients.



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

Sie können Amazon Pinpoint verwenden, indem Sie HTTP-Anforderungen direkt an die REST-API stellen.

Beispiel PUT-Anforderung für ein Objekt in S3

Um Ihre Endpunktdefinitionen einem Bucket hinzuzufügen, verwenden Sie die Amazon-S3-Operation PUT-Objekt und geben die Endpunktdefinitionen als Text an:


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

Wobei gilt:

/prefix/key ist das Präfix und den Schlüsselname für das Objekt, das die Endpunktdefinitionen nach dem Hochladen enthält. Sie können das Präfix verwenden, um Ihre Objekte hierarchisch zu organisieren. Ein praktisches Präfix könnte beispielsweise pinpoint/imports/endpoints/ sein.
bucket-name ist der Name des Amazon-S3-Buckets, dem Sie die Endpunktdefinitionen hinzufügen.

Beispiel POST-Anforderung für den Importauftrag

Um Endpunktdefinitionen aus einem Amazon-S3-Bucket zu importieren, senden Sie eine POST-Anforderung an die Importaufträge-Ressource. Fügen Sie Ihrer Anforderung die erforderlichen Header hinzu und geben Sie die ImportJobRequest-JSON als Text an:


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
}

Wobei gilt:

application-id ist die ID des Amazon-Pinpoint-Projekts, für das Sie Endpunkte importieren
bucket-name/prefix/key ist der Speicherort in Amazon S3, der ein oder mehrere Objekte zum Importieren enthält. Der Speicherort kann mit dem Schlüssel für ein einzelnes Objekt enden, oder mit einem Präfix, das mehrere Objekte qualifiziert.
iam-import-role-arn ist der Amazon-Ressourcenname (ARN) einer IAM-Rolle, die Amazon Pinpoint Lesezugriff auf den Bucket erteilt.
Format kann JSON oder CSV sein, abhängig davon, mit welchem Format Sie Ihre Endpunkte definiert haben. Wenn der Amazon-S3-Speicherort mehrere Dateien mit gemischten Formaten enthält, importiert Amazon Pinpoint nur die Dateien, die mit dem angegebenen Format übereinstimmen.

Wenn Ihre Anforderung erfolgreich ist, erhalten Sie eine Antwort wie die folgende:


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

Die Ausgabe stellt die Auftrags-ID mit dem Id-Attribut bereit. Diese ID können Sie verwenden, um den aktuellen Status des Importauftrags zu überprüfen.

Beispiel GET-Anforderung für den Importauftrag

Um den aktuellen Status eines Importauftrags zu überprüfen, führen Sie eine GET-Anforderung für die Import Job-Ressource durch:


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

Wobei gilt:

application_id ist die ID des Amazon-Pinpoint-Projekts, für das der Importauftrag initiiert wurde.
job_id ist die ID des Importauftrags, den Sie überprüfen.

Wenn Ihre Anforderung erfolgreich ist, erhalten Sie eine Antwort wie die folgende:


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

Die Ausgabe stellt den Auftragsstatus mit dem JobStatus-Attribut bereit.

Weitere Informationen über die „Importaufträge“-Ressource in der Amazon-Pinpoint-API, einschließlich der unterstützten HTTP-Methoden und Anforderungsparameter, finden Sie unter Importaufträge in der Amazon-Pinpoint-API-Referenz.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Hinzufügen eines Stapels Endpunkte

Löschen von Endpunkten