Aktivieren eines Datensatzes für Profilaktualisierungen mithilfe von APIs

In diesem Tutorial wird die Aktivierung eines Datensatzes mit "upsert"-Funktionen beschrieben, um Aktualisierungen an den Echtzeit-Kundenprofildaten vorzunehmen. Dazu gehören die Schritte zum Erstellen eines neuen Datensatzes und zum Konfigurieren eines vorhandenen Datensatzes.

HINWEIS

Der Upsert-Workflow funktioniert nur für die Batch-Aufnahme. Die Streaming-Aufnahme wird nicht unterstützt.

Erste Schritte

Dieses Tutorial setzt Grundkenntnisse verschiedener Adobe Experience Platform-Services voraus, die mit der Verwaltung von profilaktivierten Datensätzen verbunden sind. Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte die Dokumentation für die folgenden Platform-Services:

  • Real-Time Customer Profile: Bietet ein einheitliches Echtzeit-Kundenprofil, das auf aggregierten Daten aus verschiedenen Quellen basiert.
  • Catalog Service: Eine RESTful-API, mit der Sie Datensätze erstellen und für Real-Time Customer Profile und Identity Service konfigurieren können.
  • Experience Data Model (XDM): Das standardisierte Framework, mit dem Kundenerlebnisdaten von Platform organisiert werden.
  • Batch-Aufnahme: Mit der Batch-Aufnahme-API können Sie Daten als Batch-Dateien in Experience Platform aufnehmen.

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um die Platform-APIs erfolgreich aufrufen zu können.

Lesen von Beispiel-API-Aufrufen

In diesem Tutorial wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Handbuch zur Fehlerbehebung für Experience Platform

Sammeln von Werten für erforderliche Kopfzeilen

Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Content-Type-Kopfzeile erforderlich. Der richtige Wert für diese Kopfzeile wird bei Bedarf in den Beispielanfragen angezeigt.

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Bei allen Anfragen an Platform-APIs ist eine x-sandbox-name-Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll. Weitere Informationen zu Sandboxes in Platform finden Sie in der Sandbox-Übersichtsdokumentation.

Erstellen eines Datensatzes, der für Profilaktualisierungen aktiviert ist

Beim Erstellen eines neuen Datensatzes können Sie diesen Datensatz für das Profil aktivieren und zum Zeitpunkt der Erstellung Aktualisierungsfunktionen aktivieren.

HINWEIS

Um einen neuen profilaktivierten Datensatz zu erstellen, müssen Sie die ID eines vorhandenen XDM-Schemas kennen, das für Profil aktiviert ist. Informationen zum Nachschlagen oder Erstellen eines profilaktivierten Schemas finden Sie im Tutorial zum Erstellen eines Schemas mithilfe der Schemaregistrierungs-API.

Um einen Datensatz zu erstellen, der für Profil und Aktualisierungen aktiviert ist, verwenden Sie eine POST-Anfrage an den /dataSets-Endpunkt.

API-Format

POST /dataSets

Anfrage

Indem Sie unifiedIdentity und unifiedProfile unter tags im Anfrageinhalt aufnehmen, wird der Datensatz bei der Erstellung für Profile aktiviert. Innerhalb des unifiedProfile-Arrays wird durch Hinzufügen von isUpsert:true zum Datensatz die Möglichkeit hinzugefügt, Aktualisierungen zu unterstützen.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "fields": [],
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'
Eigenschaft Beschreibung
schemaRef.id Die ID des Profile-aktivierten Schemas, auf dem der Datensatz basieren soll.
{TENANT_ID} Der Namespace innerhalb der Schema Registry, der Ressourcen enthält, die zu Ihrer Organisation gehören. Weitere Informationen finden Sie im Abschnitt TENANT_ID des Schema Registry-Entwicklerhandbuchs.

Antwort

Eine erfolgreiche Antwort zeigt ein Array mit der ID des neu erstellten Datensatzes in der Form "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Konfigurieren eines vorhandenen Datensatzes

Die folgenden Schritte beschreiben, wie Sie einen vorhandenen, für Profil aktivierten Datensatz für die Aktualisierung (upsert) konfigurieren.

HINWEIS

Um einen vorhandenen profilaktivierten Datensatz für upsert zu konfigurieren, müssen Sie zunächst den Datensatz für Profil deaktivieren und ihn dann zusammen mit dem Tag isUpsert wieder aktivieren. Wenn der vorhandene Datensatz nicht für Profil aktiviert ist, können Sie direkt mit den Schritten für das Aktivieren des Datensatzes für Profil und upsert fortfahren. Wenn Sie sich nicht sicher sind, zeigen Ihnen die folgenden Schritte, wie Sie überprüfen können, ob der Datensatz bereits aktiviert ist.

Überprüfen, ob der Datensatz für Profil aktiviert ist

Mithilfe der Catalog-API können Sie einen vorhandenen Datensatz untersuchen, um festzustellen, ob er für die Verwendung in Real-Time Customer Profile aktiviert ist. Der folgende Aufruf ruft die Details eines Datensatzes nach ID ab.

API-Format

GET /dataSets/{DATASET_ID}
Parameter Beschreibung
{DATASET_ID} Die ID des Datensatzes, den Sie untersuchen möchten.

Anfrage

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "lastBatchId": "{BATCH_ID}",
        "lastBatchStatus": "success",
        "dule": {},
        "statsCache": {
            "startDate": null,
            "endDate": null
        },
        "namespace": "ACP",
        "state": "DRAFT",
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "status": "enabled",
        "transforms": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/transforms",
        "files": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/files",
        "schema": "{SCHEMA}",
        "schemaMetadata": {
            "primaryKey": [],
            "delta": [],
            "dule": []
        },
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Unter der tags-Eigenschaft ist zu sehen, dass unifiedProfile mit dem Wert enabled:true vorliegt. Daher ist Real-Time Customer Profile für diesen Datensatz aktiviert.

Deaktivieren des Datensatzes für Profil

Um einen Profil-aktivierten Datensatz für Aktualisierungen zu konfigurieren, müssen Sie zunächst die Tags unifiedProfile und unifiedIdentity deaktivieren und sie dann zusammen mit dem Tag isUpsert erneut aktivieren. Dies erfolgt über zwei PATCH-Anfragen: die eine zur Deaktivierung und die andere zur erneuten Aktivierung.

WARNUNG

Daten, die in einen deaktivierten Datensatz aufgenommen werden, werden nicht in den Profilspeicher aufgenommen. Sie sollten die Aufnahme von Daten in den Datensatz vermeiden, bis er erneut für Profil aktiviert wurde.

API-Format

PATCH /dataSets/{DATASET_ID}
Parameter Beschreibung
{DATASET_ID} Die ID des Datensatzes, den Sie aktualisieren möchten.

Anfrage

Der erste PATCH-Anfragetext enthält einen path-Verweis zu unifiedProfile und einen path-Verweis zu unifiedIdentity. Wird value für beide Pfade auf enabled:false festgelegt, werden die Tags deaktiviert.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

Antwort

Bei einer erfolgreichen PATCH-Anfrage wird der HTTP-Status 200 (OK) sowie ein Array mit der ID des gelöschten Datensatzes zurückgegeben. Diese ID sollte mit der in der PATCH-Anfrage gesendeten ID übereinstimmen. Die Tags unifiedProfile und unifiedIdentity sind nun deaktiviert.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Aktivieren des Datensatzes für Profil und upsert

Ein vorhandener Datensatz kann mit einer einzigen PATCH-Anfrage für Profil- und Attributaktualisierungen aktiviert werden.

WICHTIG

Stellen Sie beim Aktivieren Ihres Datensatzes für Profil sicher, dass das Schema, mit dem der Datensatz verknüpft ist, ebenfalls Profil-aktiviert ist. Wenn das Schema nicht Profil-aktiviert ist, wird der Datensatz in der Platform-Benutzeroberfläche nicht als Profil-aktiviert angezeigt.

API-Format

PATCH /dataSets/{DATASET_ID}
Parameter Beschreibung
{DATASET_ID} Die ID eines Datensatzes, den Sie aktualisieren möchten.

Anfrage

Der Anfragetext enthält einen path-Verweis zu unifiedProfile. value umfasst dabei die Tags enabled und isUpsert, die beide auf true eingestellt sind. Der Anfragetext enthält auch einen path-Verweis zu unifiedIdentity, wobei value das Tag enabled mit der Einstellung true umfasst.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

Antwort

Bei einer erfolgreichen PATCH-Anfrage wird der HTTP-Status 200 (OK) sowie ein Array mit der ID des gelöschten Datensatzes zurückgegeben. Diese ID sollte mit der in der PATCH-Anfrage gesendeten ID übereinstimmen. Die Tags unifiedProfile und unifiedIdentity sind nun für Attributaktualisierungen aktiviert und konfiguriert.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Nächste Schritte

Ihr Profil- und upsert-aktivierter Datensatz kann nun von Batch-Aufnahme-Workflows verwendet werden, um Aktualisierungen an Profildaten vorzunehmen. Um mehr über die Aufnahme von Daten in Adobe Experience Platform zu erfahren, lesen Sie bitte zunächst die Übersicht zur Datenaufnahme.

Auf dieser Seite