Endpunkt für Exportaufträge

Real-time Customer Profile ermöglicht Ihnen die Erstellung einer einzelnen Ansicht einzelner Kunden durch Zusammenführen von Daten aus mehreren Quellen, einschließlich Attributdaten und Verhaltensdaten. Profil-Daten können dann zur weiteren Verarbeitung in einen Datensatz exportiert werden. So können z. B. Audiencen aus Profile-Daten zur Aktivierung exportiert und Profil-Attribute zum Berichte exportiert werden.

Dieses Dokument enthält schrittweise Anleitungen zum Erstellen und Verwalten von Exportaufträgen mit der Profil-API.

HINWEIS

Dieses Handbuch behandelt die Verwendung von Exportaufträgen im Profile API. Informationen zum Verwalten von Exportaufträgen für den Adobe Experience Platform-Segmentierungsdienst finden Sie im Handbuch zu Exportaufträgen in der Segmentierungs-API.

Neben der Erstellung eines Exportauftrags können Sie auch mit dem Profile-Endpunkt /entities auf -Daten zugreifen. Dieser Endpunkt wird auch als "Profile Access"bezeichnet. Weitere Informationen finden Sie im Handbuch Entitätsendpunkt. Anweisungen zum Zugriff auf Profile-Daten mithilfe der Benutzeroberfläche finden Sie im Benutzerhandbuch.

Erste Schritte

Die in diesem Handbuch verwendeten API-Endpunkte sind Teil der API. Real-time Customer Profile Bevor Sie fortfahren, lesen Sie bitte im Handbuch Erste Schritte nach Links zu entsprechenden Dokumentationen, einem Leitfaden zum Lesen der Beispiel-API-Aufrufe in diesem Dokument und wichtigen Informationen zu erforderlichen Kopfzeilen, die für das erfolgreiche Aufrufen einer Experience Platform-API erforderlich sind.

Erstellen eines Exportauftrags

Für das Exportieren von Profile-Daten muss zunächst ein Datensatz erstellt werden, in den die Daten exportiert werden, und dann ein neuer Exportauftrag initiiert werden. Beide Schritte können mit Experience Platform-APIs durchgeführt werden, wobei erstere die Katalogdienst-API und letztere die Echtzeit-Customer-Profil-API verwenden. Detaillierte Anweisungen zum Abschluss der einzelnen Schritte finden Sie in den folgenden Abschnitten.

Zielgruppen-Dataset erstellen

Beim Exportieren von Profile-Daten muss zunächst ein Zielgruppe-Datensatz erstellt werden. Es ist wichtig, dass der Datensatz korrekt konfiguriert wird, um sicherzustellen, dass der Export erfolgreich ist.

Eine der wichtigsten Überlegungen ist das Schema, auf dem der Datensatz basiert (schemaRef.id in der unten stehenden API-Musteranforderung). Um Profil-Daten zu exportieren, muss der Datensatz auf dem XDM Individual Profile-Vereinigung-Schema (https://ns.adobe.com/xdm/context/profile__union) basieren. Ein Vereinigung-Schema ist ein systemgeneriertes, schreibgeschütztes Schema, das die Felder von Schemas, die dieselbe Klasse gemeinsam haben, Aggregat. In diesem Fall ist dies die XDM Individual Profile-Klasse. Weitere Informationen zu Schemas zur Ansicht der Vereinigung finden Sie im Abschnitt Vereinigung im Handbuch Grundlagen der Schema-Komposition.

In den folgenden Schritten wird beschrieben, wie Sie einen Datensatz erstellen, der auf das XDM Individual Profile-Vereinigung-Schema mit der Catalog-API verweist. Sie können auch die Platform-Benutzeroberfläche verwenden, um einen Datensatz zu erstellen, der auf das Schema "Vereinigung"verweist. Die Schritte zur Verwendung der Benutzeroberfläche sind in diesem UI-Lernprogramm zum Exportieren von Segmenten beschrieben, gelten aber auch hier. Nach Abschluss können Sie zu diesem Lernprogramm zurückkehren, um mit den Schritten für das Initiieren eines neuen Exportauftrags fortzufahren.

Wenn Sie bereits über einen kompatiblen Datensatz verfügen und dessen ID kennen, können Sie direkt mit dem Schritt für beginnen, um einen neuen Exportauftrag zu starten.

API-Format

POST /dataSets

Anfrage

Mit der folgenden Anforderung wird ein neuer Datensatz erstellt, der Konfigurationsparameter in der Nutzlast bereitstellt.

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Profile Data Export",
        "schemaRef": {
          "id": "https://ns.adobe.com/xdm/context/profile__union",
          "contentType": "application/vnd.adobe.xed+json;version=1"
        },
        "fileDescription": {
          "persisted": true,
          "containerFormat": "parquet",
          "format": "parquet"
        }
      }'
Eigenschaft Beschreibung
name Ein beschreibender Name für den Datensatz.
schemaRef.id Die ID der Vereinigung-Ansicht (Schema), der der Datensatz zugeordnet werden soll.
fileDescription.persisted Ein boolescher Wert, der bei Festlegung auf true den Datenbestand in der Ansicht "Vereinigung"beibehalten kann.

Antwort

Eine erfolgreiche Antwort gibt ein Array zurück, das die schreibgeschützte, systemgenerierte eindeutige ID des neu erstellten Datensatzes enthält. Für den erfolgreichen Export von Profil-Daten ist eine ordnungsgemäß konfigurierte Dataset-ID erforderlich.

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

Exportauftrag starten

Sobald Sie über einen Datensatz mit Vereinigung-Speicherung verfügen, können Sie einen Exportauftrag erstellen, um die Profil-Daten an den Datensatz zu erhalten, indem Sie eine POST an den /export/jobs-Endpunkt in der Echtzeit-Client-Profil-API anfordern und die Details der Daten angeben, die Sie im Hauptteil der Anforderung exportieren möchten.

API-Format

POST /export/jobs

Anfrage

Mit der folgenden Anforderung wird ein neuer Exportauftrag erstellt, der Konfigurationsparameter in der Nutzlast bereitstellt.

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    }
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }' 
Eigenschaft Beschreibung
fields (Optional) Beschränkt die Datenfelder, die in den Export einbezogen werden sollen, auf die in diesem Parameter bereitgestellten Felder. Wird dieser Wert nicht angegeben, werden alle Felder in die exportierten Daten einbezogen.
mergePolicy (Optional) Gibt die Richtlinie zum Zusammenführen an, die für die exportierten Daten gilt. Schließen Sie diesen Parameter ein, wenn mehrere Segmente exportiert werden.
mergePolicy.id Die ID der Zusammenführungsrichtlinie.
mergePolicy.version Die spezifische Version der zu verwendenden Mergerichtlinie. Wenn Sie diesen Wert auslassen, wird standardmäßig die neueste Version verwendet.
additionalFields.eventList (Optional) Steuert die Zeitreihen-Ereignis-Felder, die für untergeordnete oder verknüpfte Objekte exportiert werden, indem eine oder mehrere der folgenden Einstellungen bereitgestellt werden:
  • eventList.fields: Steuerung der zu exportierenden Felder.
  • eventList.filter: Gibt Kriterien an, die die Ergebnisse verknüpfter Objekte einschränken. Erwartet einen für den Export erforderlichen Mindestwert, normalerweise ein Datum.
  • eventList.filter.fromIngestTimestamp: Filter der Zeitreihen-Ereignis zu denen, die nach dem bereitgestellten Zeitstempel erfasst wurden. Dies ist nicht die Ereignis-Zeit selbst, sondern die Aufnahmezeit für die Ereignisse.
destination (Erforderlich) Zielinformationen für die exportierten Daten:
  • destination.datasetId: (Erforderlich) Die ID des Datensatzes, in den Daten exportiert werden sollen.
  • destination.segmentPerBatch: (Optional) Ein boolescher Wert, der standardmäßig falseverwendet wird, wenn er nicht angegeben wird. Der Wert false exportiert alle Segment-IDs in eine einzelne Stapel-ID. Der Wert true exportiert eine Segment-ID in eine Stapel-ID. Beachten Sie, dass sich das Festlegen des Werts auf true möglicherweise auf die Exportleistung des Stapels auswirkt.
schema.name (Erforderlich) Der Name des Schemas, das mit dem Datensatz verknüpft ist, in den Daten exportiert werden sollen.
HINWEIS

Um nur Profil-Daten zu exportieren und keine zugehörigen Zeitreihendaten einzubeziehen, entfernen Sie das Objekt "additionalFields"aus der Anforderung.

Antwort

Eine erfolgreiche Antwort gibt einen Datensatz zurück, der mit den in der Anforderung angegebenen Profil-Daten gefüllt ist.

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "NEW",
    "requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
    "computeGatewayJobId": {},
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1559674261657
        }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}

Liste aller Exportaufträge

Sie können eine Liste aller Exportaufträge für eine bestimmte IMS-Organisation zurückgeben, indem Sie eine GET an den export/jobs-Endpunkt senden. Die Anforderung unterstützt auch die Abfragen limit und offset, wie unten dargestellt.

API-Format

GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
Parameter Beschreibung
start Versatz der Seite mit den zurückgegebenen Ergebnissen, unter Berücksichtigung der Erstellungszeit der Anfrage. Beispiel: start=4
limit Schränkt die Anzahl der zurückgegebenen Ergebnisse ein. Beispiel: limit=10
page Gibt eine bestimmte Seite mit Ergebnissen zurück, unter Berücksichtigung der Erstellungszeit der Anfrage. Beispiel: page=2
sort Sortiert Ergebnisse nach einem bestimmten Feld in aufsteigender (asc) oder absteigender (desc) Reihenfolge. Der Sortierparameter funktioniert nicht, wenn mehrere Ergebnisseiten zurückgegeben werden. Beispiel: sort=updateTime:asc

Anfrage

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/ \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -H 'x-sandbox-name: {SANDBOX_NAME}' 

Antwort

Die Antwort enthält ein records-Objekt, das die von Ihrer IMS-Organisation erstellten Exportaufträge enthält.

{
  "records": [
    {
      "profileInstanceId": "ups",
      "jobType": "BATCH",
      "id": 726,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "timestampOrdered-none-mp",
          "version": 1
      },
      "status": "SUCCEEDED",
      "requestId": "d995479c-8a08-4240-903b-af469c67be1f",
      "computeGatewayJobId": {
          "exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
          "pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538615973895,
              "endTimeInMs": 1538616233239,
              "totalTimeInMs": 259344
          },
          "profileExportTime": {
              "startTimeInMs": 1538616067445,
              "endTimeInMs": 1538616139576,
              "totalTimeInMs": 72131
          },
          "aCPDatasetWriteTime": {
              "startTimeInMs": 1538616195172,
              "endTimeInMs": 1538616195715,
              "totalTimeInMs": 543
          }
      },
      "destination": {
          "datasetId": "5b7c86968f7b6501e21ba9df",
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
      },
      "updateTime": 1538616233239,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538615973895
    },
    {
      "profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
      "errors": [
        {
          "code": "0090000009",
          "msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
          "callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger" 
        },
        {
          "code": "unknown",
          "msg": "Job aborted.",
          "callStack": "org.apache.spark.SparkException: Job aborted."
        }
      ],
      "jobType": "BATCH",
      "filter": {
        "segments": [
            {
                "segmentId": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
            }
        ]
      },
      "id": 722,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
          "version": 1
      },
      "status": "FAILED",
      "requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
      "computeGatewayJobId": {
          "exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538573416687,
              "endTimeInMs": 1538573922551,
              "totalTimeInMs": 505864
          },
          "profileExportTime": {
              "startTimeInMs": 1538573872211,
              "endTimeInMs": 1538573918809,
              "totalTimeInMs": 46598
          }
      },
      "destination": {
          "datasetId": "5bb4c46757920712f924a3eb",
          "batchId": ""
      },
      "updateTime": 1538573922551,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

Überwachung des Exportfortschritts

Um die Details eines bestimmten Exportauftrags Ansicht oder dessen Status während der Verarbeitung zu überwachen, können Sie eine GET an den Endpunkt /export/jobs anfordern und das id des Exportauftrags in den Pfad einschließen. Der Exportauftrag ist abgeschlossen, sobald das Feld status den Wert "SUCCEEDED"zurückgibt.

API-Format

GET /export/jobs/{EXPORT_JOB_ID}
Parameter Beschreibung
{EXPORT_JOB_ID} Der id des Exportauftrags, auf den Sie zugreifen möchten.

Anfrage

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/24115 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "SUCCEEDED",
    "requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
    "computeGatewayJobId": {
      "exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
      "pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
    },
    "metrics": {
      "totalTime": {
        "startTimeInMs": 1547053539564,
        "endTimeInMs": 1547054743929,
        "totalTimeInMs": 1204365
      },
      "profileExportTime": {
        "startTimeInMs": 1547053667591,
        "endTimeInMs": 1547053778195,
        "totalTimeInMs": 110604
      },
      "aCPDatasetWriteTime": {
        "startTimeInMs": 1547054660416,
        "endTimeInMs": 1547054698918,
        "totalTimeInMs": 38502
      }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}
Eigenschaft Beschreibung
batchId Die Kennung der Stapel, die aus einem erfolgreichen Export erstellt wurden und für Nachschlagezwecke beim Lesen von Profil-Daten verwendet werden.

Abbrechen eines Exportauftrags

Mit der Experience Platform können Sie einen vorhandenen Exportauftrag stornieren. Dies kann aus verschiedenen Gründen nützlich sein, z. B. wenn der Exportauftrag nicht abgeschlossen wurde oder in der Verarbeitungsstufe hängen geblieben ist. Um einen Exportauftrag abzubrechen, können Sie eine DELETE-Anforderung an den /export/jobs-Endpunkt ausführen und die id des Exportauftrags einschließen, den Sie zum Abbrechen an den Anforderungspfad abbrechen möchten.

API-Format

DELETE /export/jobs/{EXPORT_JOB_ID}
Parameter Beschreibung
{EXPORT_JOB_ID} Der id des Exportauftrags, auf den Sie zugreifen möchten.

Anfrage

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs/726 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

Bei einer erfolgreichen Löschanforderung werden HTTP-Status 204 (Kein Inhalt) und ein leerer Antworttext zurückgegeben, der angibt, dass der Vorgang "Abbrechen"erfolgreich war.

Nächste Schritte

Nach erfolgreichem Abschluss des Exports sind Ihre Daten im Data Lake in der Experience Platform verfügbar. Mit der Datenzugriff-API können Sie dann mit dem batchId, das dem Export zugeordnet ist, auf die Daten zugreifen. Je nach Größe des Exports können die Daten in Blöcken vorliegen und der Stapel kann aus mehreren Dateien bestehen.

Eine schrittweise Anleitung zum Verwenden der Datenzugriffs-API zum Zugriff auf und Herunterladen von Stapeldateien finden Sie im Lernprogramm Datenzugriff.

Sie können auch über den Adobe Experience Platform Abfrage Service auf erfolgreich exportierte Echtzeit-Kundendaten zugreifen. Mithilfe der Benutzeroberfläche oder RESTful-API können Sie mit dem Abfrage Service Abfragen für Daten im Data Lake schreiben, überprüfen und ausführen.

Weitere Informationen zur Abfrage von Audiencen finden Sie in der Abfrage Service-Dokumentation.

Anhang

Im folgenden Abschnitt finden Sie weitere Informationen zu Exportaufträgen in der Profil-API.

Zusätzliche Beispiele für die Exportnutzlast

Der API-Beispielaufruf, der im Abschnitt Initiieren eines Exportauftrags angezeigt wird, erstellt einen Auftrag, der sowohl Profil- (Datensatz-) als auch Ereignis- (Zeitreihendaten) enthält. Dieser Abschnitt enthält zusätzliche Anforderungs-Nutzlastbeispiele, um den Export auf den einen Datentyp oder den anderen zu beschränken.

Die folgende Nutzlast erstellt einen Exportauftrag, der nur Profil-Daten (keine Ereignis) enthält:

{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Um einen Exportauftrag zu erstellen, der nur Ereignis-Daten enthält (keine Profil-Attribute), sieht die Nutzlast möglicherweise wie folgt aus:

{
    "fields": "identityMap",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Exportieren von Segmenten

Sie können den Endpunkt "Exportaufträge"auch verwenden, um Audiencen-Segmente anstelle von Profile-Daten zu exportieren. Weitere Informationen finden Sie im Handbuch zu Exportaufträgen in der Segmentierungs-API.

Auf dieser Seite

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now