Aktivieren eines Datensatzes für Profile und Identity Service mithilfe von APIs
In diesem Tutorial wird der Prozess zum Aktivieren eines Datensatzes für die Verwendung in Real-Time Customer Profile und Identity Service beschrieben, der in die folgenden Schritte unterteilt ist:
-
Aktivieren eines Datensatzes für die Verwendung in Real-Time Customer Profile mit einer von zwei Optionen:
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.
- Identity Service: Aktiviert das Real-Time Customer Profile durch Überbrückung von Identitäten aus unterschiedlichen Datenquellen, die in Platform aufgenommen werden.
- Catalog Service: Eine RESTful-API, mit der Sie Datensätze für das Real-Time Customer Profile und Identity Service erstellen und konfigurieren können.
- Experience Data Model (XDM): Das standardisierte Framework, mit dem Kundenerlebnisdaten von Platform organisiert werden.
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.
Konfigurieren eines für Profil und Identität aktivierten Datensatzes create-a-dataset-enabled-for-profile-and-identity
Sie können einen Datensatz für Echtzeit-Kundenprofil und Identity Service sofort nach der Erstellung oder zu einem beliebigen Zeitpunkt nach der Erstellung des Datensatzes aktivieren. Wenn Sie einen bereits erstellten Datensatz aktivieren möchten, folgen Sie den weiter unten in diesem Dokument beschriebenen Schritten zum Konfigurieren eines vorhandenen Datensatzes.
Um einen Datensatz zu erstellen, der für Profil aktiviert ist, können Sie eine POST-Anfrage an den /dataSets-Endpunkt verwenden.
API-Format
POST /dataSets
Anfrage
Durch Einbeziehung von unifiedProfile und unifiedIdentity unter tags im Anfragetext wird der Datensatz sofort für Profile bzw. Identity Service aktiviert. Die Werte dieser Tags müssen ein Array sein, das die Zeichenfolge "enabled:true" enthält.
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 '{
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
},
"tags": {
"unifiedProfile": ["enabled:true"],
"unifiedIdentity": ["enabled:true"]
}
}'
schemaRef.id{TENANT_ID}Antwort
Eine erfolgreiche Antwort zeigt ein Array mit der ID des neu erstellten Datensatzes in der Form "@/dataSets/{DATASET_ID}". Nachdem Sie einen Datensatz erfolgreich erstellt und aktiviert haben, fahren Sie mit den Schritten zum Hochladen von Daten fort.
[
"@/dataSets/5b020a27e7040801dedbf46e"
]
Konfigurieren eines vorhandenen Datensatzes configure-an-existing-dataset
In den folgenden Schritten wird beschrieben, wie Sie einen zuvor erstellten Datensatz für Real-Time Customer Profile und Identity Service aktivieren. Wenn Sie bereits einen profilaktivierten Datensatz erstellt haben, fahren Sie mit den Schritten für die Datenaufnahme fort.
Überprüfen auf eine Aktivierung des Datensatzes check-if-the-dataset-is-enabled
Mithilfe der Catalog-API können Sie einen vorhandenen Datensatz untersuchen, um festzustellen, ob er für die Verwendung in Real-Time Customer Profile und Identity Service aktiviert ist. Der folgende Aufruf ruft die Details eines Datensatzes nach ID ab.
API-Format
GET /dataSets/{DATASET_ID}
{DATASET_ID}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": "Commission Program Events DataSet",
"imsOrg": "{ORG_ID}",
"tags": {
"adobe/pqs/table": [
"unifiedprofileingestiontesteventsdataset"
],
"unifiedProfile": [
"enabled:true"
],
"unifiedIdentity": [
"enabled:true"
]
},
"version": "1.0.1",
"created": 1536536917382,
"updated": 1539793978215,
"createdClient": "{CLIENT_CREATED}",
"createdUser": "{CREATED_BY}",
"updatedUser": "{CREATED_BY}",
"viewId": "5b020a27e7040801dedbf46f",
"files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
"schema": "@/xdms/context/experienceevent",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/experienceevent",
"contentType": "application/vnd.adobe.xed+json"
}
}
}
Unter der tags-Eigenschaft ist zu sehen, dass sowohl unifiedProfile als auch unifiedIdentity mit dem Wert enabled:true vorliegen. Daher sind Real-Time Customer Profile bzw. Identity Service für diesen Datensatz aktiviert.
Aktivieren des Datensatzes enable-the-dataset
Wenn der vorhandene Datensatz nicht für Profile oder Identity Service aktiviert ist, können Sie ihn aktivieren, indem Sie eine PATCH-Anfrage mit der Datensatz-ID stellen.
API-Format
PATCH /dataSets/{DATASET_ID}
{DATASET_ID}Anfrage
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"] },
{ "op": "add", "path": "/tags/unifiedIdentity", "value": ["enabled:true"] }
]'
Der Anfragetext enthält einen path zu zwei Arten von Tags, unifiedProfile und unifiedIdentity. Als value sind jeweils Arrays mit der Zeichenfolge enabled:true angegeben.
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 wurden hinzugefügt und der Datensatz ist für Profil und Identity Service aktiviert.
[
"@/dataSets/5b020a27e7040801dedbf46e"
]
Aufnehmen von Daten in den Datensatz ingest-data-into-the-dataset
Sowohl Real-Time Customer Profile als auch Identity Service verwenden XDM-Daten, wenn sie in einen Datensatz aufgenommen werden. Anweisungen zum Hochladen von Daten in einen Datensatz finden Sie im Tutorial zum Erstellen eines Datensatzes mithilfe von APIs. Bei der Planung, welche Daten an Ihren Profile-aktivierten Datensatz gesendet werden, sollten die folgenden Best Practices berücksichtigt werden:
- Schließen Sie alle Daten ein, die Sie als Segmentierungskriterien verwenden möchten.
- Schließen Sie so viele IDs ein, wie Sie über Ihre Profildaten ermitteln können, um Ihr Identitätsdiagramm zu maximieren. So kann Identity Service Identitäten effektiver über Datensätze hinweg zusammenfügen.
Bestätigen der Datenaufnahme durch das Real-Time Customer Profile confirm-data-ingest-by-real-time-customer-profile
Beim erstmaligen Hochladen von Daten in einen neuen Datensatz oder im Rahmen eines Prozesses mit einer neuen ETL oder Datenquelle wird empfohlen, die Daten sorgfältig zu überprüfen, um sicherzustellen, dass sie wie erwartet hochgeladen wurden. Mit der Zugriffs-API des Real-Time Customer Profile können Sie Batch-Daten abrufen, sobald sie in einen Datensatz geladen werden. Wenn Sie keine der erwarteten Entitäten abrufen können, ist Ihr Datensatz möglicherweise nicht für Real-Time Customer Profile aktiviert. Nachdem Sie bestätigt haben, dass Ihr Datensatz aktiviert wurde, stellen Sie sicher, dass Ihr Quelldatenformat und Ihre Identifikatoren Ihren Erwartungen entsprechen. Ausführliche Anweisungen zur Verwendung der Real-Time Customer Profile-API für den Zugriff auf Profile-Daten finden Sie im Handbuch für Entitäten-Endpunkte, auch bekannt als „Profile Access“-API.
Bestätigen der Datenaufnahme durch Identity Service confirm-data-ingest-by-identity-service
Jedes erfasste Datenfragment, das mehr als eine Identität enthält, erstellt einen Link in Ihrem privaten Identitätsdiagramm. Um weitere Informationen zu Identitätsdiagrammen und zum Zugriff auf Identitätsdaten zu erhalten, lesen Sie zunächst die Seite Identity Service – Übersicht.