Endpunkt der Segmentexportaufträge
Exportaufträge sind asynchrone Prozesse, mit denen Zielgruppensegmentmitglieder in Datensätzen beibehalten werden. Sie können den Endpunkt /export/jobs
in der Adobe Experience Platform Segmentation API verwenden, mit dem Sie Exportaufträge programmgesteuert abrufen, erstellen und abbrechen können.
Erste Schritte
Die in diesem Handbuch verwendeten Endpunkte sind Teil der Adobe Experience Platform Segmentation Service -API. Bevor Sie fortfahren, lesen Sie zunächst das Erste-Schritte-Handbuch , um wichtige Informationen zu erhalten, die Sie benötigen, um die API erfolgreich aufrufen zu können, einschließlich erforderlicher Kopfzeilen und Anweisungen zum Lesen von Beispiel-API-Aufrufen.
Liste mit Exportaufträgen abrufen retrieve-list
Sie können eine Liste aller Exportaufträge für Ihr Unternehmen abrufen, indem Sie eine GET-Anfrage an den Endpunkt /export/jobs
senden.
API-Format
Der /export/jobs
-Endpunkt unterstützt verschiedene Abfrageparameter, mit denen Sie Ihre Ergebnisse filtern können. Diese Parameter sind zwar optional, doch wird ihre Verwendung dringend empfohlen, um den teuren Verwaltungsaufwand zu reduzieren. Wenn Sie diesen Endpunkt ohne Parameter aufrufen, werden alle für Ihre Organisation verfügbaren Exportaufträge abgerufen. Es können mehrere Parameter eingeschlossen werden, die durch kaufmännische Und-Zeichen (&
) voneinander getrennt werden.
GET /export/jobs
GET /export/jobs?limit={LIMIT}
GET /export/jobs?offset={OFFSET}
GET /export/jobs?status={STATUS}
{LIMIT}
{OFFSET}
{STATUS}
Anfrage
Mit der folgenden Anfrage werden die letzten beiden Exportaufträge innerhalb Ihres Unternehmens abgerufen.
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs?limit=2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Die folgende Antwort gibt den HTTP-Status 200 mit einer Liste erfolgreich abgeschlossener Exportaufträge zurück, basierend auf dem Abfrageparameter, der im Anfragepfad angegeben ist.
{
"records": [
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52",
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"errors": [
{
"code": "0100000003",
"msg": "Error in Export Job",
"callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger"
}
],
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
},
{
"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": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "AAM",
"status": ["realized"]
}
]
},
"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",
"segmentPerBatch": false,
"batchId": "IWEQ6920712f9475762D"
},
"updateTime": 1538573922551,
"imsOrgId": "1BD6382559DF0C130A49422D@AdobeOrg",
"creationTime": 1538573416687
}
],
"page":{
"sortField": "createdTime",
"sort": "desc",
"pageOffset": "1540974701302_96",
"pageSize": 2
},
"link":{
"next": "/export/jobs/?limit=2&offset=1538573416687_722"
}
}
destination
Zielinformationen für die exportierten Daten:
datasetId
: Die ID des Datensatzes, in den Daten exportiert wurden.segmentPerBatch
: Ein boolescher Wert, der anzeigt, ob Segment-IDs konsolidiert sind oder nicht. Der Wert "false"bedeutet, dass alle Segment-IDs in eine Batch-Kennung exportiert werden. Der Wert "true"bedeutet, dass eine Segment-ID in eine Batch-Kennung exportiert wird. Hinweis: Die Festlegung des Werts auf "true"kann sich auf die Batch-Exportleistung auswirken.
fields
schema.name
filter.segments
Die exportierten Segmente. Die folgenden Felder sind enthalten:
segmentId
: Die Segment-ID, in die Profile exportiert werden.segmentNs
: Segment-Namespace für den angegebenensegmentID
.status
: Ein Array von Zeichenfolgen, die einen Statusfilter für diesegmentID
bereitstellen. Standardmäßig hatstatus
den Wert["realized"]
, der alle Profile darstellt, die zum aktuellen Zeitpunkt in das Segment fallen. Mögliche Werte sind:realized
undexited
. Der Wertrealized
bedeutet, dass das Profil für das Segment qualifiziert ist. Der Wertexiting
bedeutet, dass das Profil das Segment verlässt.
mergePolicy
metrics.totalTime
metrics.profileExportTime
page
link.next
Neuen Exportauftrag erstellen create
Sie können einen neuen Exportauftrag erstellen, indem Sie eine POST-Anfrage an den /export/jobs
-Endpunkt senden.
API-Format
POST /export/jobs
Anfrage
Die folgende Anfrage erstellt einen neuen Exportauftrag, der durch die in der Payload bereitgestellten Parameter konfiguriert wird.
curl -X POST https://platform.adobe.io/data/core/ups/export/jobs \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"fields": "identities.id,personalEmail.address",
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "string",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"toIngestTimestamp": "2020-01-01T00:00:00Z"
}
}
},
"destination":{
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false
},
"schema":{
"name": "_xdm.context.profile"
},
"evaluationInfo": {
"segmentation": true
}
}'
fields
mergePolicy
filter
filter.segments
Gibt die zu exportierenden Segmente an. Wird dieser Wert nicht angegeben, werden alle Daten aus allen Profilen exportiert. Akzeptiert ein Array von Segmentobjekten, die jeweils die folgenden Felder enthalten:
segmentId
: (Erforderlich bei Verwendung vonsegments
) Segment-ID für zu exportierende Profile.segmentNs
(Optional) Segment-Namespace für den angegebenensegmentID
.status
(Optional) Ein Array von Zeichenfolgen, die einen Statusfilter für diesegmentID
angeben. Standardmäßig hatstatus
den Wert["realized"]
, der alle Profile darstellt, die zum aktuellen Zeitpunkt in das Segment fallen. Mögliche Werte sind:realized
undexited
. Der Wertrealized
bedeutet, dass das Profil für das Segment qualifiziert ist. Der Wertexiting
bedeutet, dass das Profil das Segment verlässt.
filter.segmentQualificationTime
filter.segmentQualificationTime.startTime
filter.segmentQualificationTime.endTime
filter.fromIngestTimestamp
Beschränkt exportierte Profile so, dass nur die Profile einbezogen werden, die nach diesem Zeitstempel aktualisiert wurden. Der Zeitstempel muss im Format RFC 339 angegeben werden.
fromIngestTimestamp
für profile, sofern angegeben: Umfasst alle zusammengeführten Profile, bei denen der zusammengeführte aktualisierte Zeitstempel größer als der angegebene Zeitstempel ist. Unterstützt den Operandgreater_than
.fromIngestTimestamp
für events: Alle Ereignisse, die nach diesem Zeitstempel erfasst werden, werden entsprechend dem resultierenden Profilergebnis exportiert. Dies ist nicht die Ereigniszeit selbst, sondern die Erfassungszeit für die Ereignisse.
filter.emptyProfiles
emptyProfiles
auf true
. Wenn emptyProfiles
auf false
gesetzt ist, werden nur Profile mit Profildatensätzen im Speicher exportiert. Wenn das Attribut emptyProfiles
nicht enthalten ist, werden standardmäßig nur Profile exportiert, die Profildatensätze enthalten.additionalFields.eventList
Steuert die Zeitreihen-Ereignisfelder, die für untergeordnete oder verknüpfte Objekte exportiert werden, indem eine oder mehrere der folgenden Einstellungen bereitgestellt werden:
fields
: Kontrollieren Sie die zu exportierenden Felder.filter
: Gibt Kriterien an, die die Ergebnisse aus den verknüpften Objekten einschränken. Erwartet einen für den Export erforderlichen Mindestwert, normalerweise ein Datum.filter.fromIngestTimestamp
: Filtert Zeitreihenereignisse nach jenen, die nach dem angegebenen Zeitstempel erfasst wurden. Dies ist nicht die Ereigniszeit selbst, sondern die Erfassungszeit für die Ereignisse.filter.toIngestTimestamp
: Filtert den Zeitstempel auf die Zeitstempel, die vor dem angegebenen Zeitstempel erfasst wurden. Dies ist nicht die Ereigniszeit selbst, sondern die Erfassungszeit für die Ereignisse.
destination
(Erforderlich) Informationen zu den exportierten Daten:
datasetId
: (Erforderlich) Die Kennung des Datensatzes, in den Daten exportiert werden sollen.segmentPerBatch
: (Optional) Ein boolescher Wert, der, falls nicht angegeben, standardmäßig "false"lautet. Der Wert "false"exportiert alle Segment-IDs in eine Batch-Kennung. Der Wert "true"exportiert eine Segment-ID in eine Batch-Kennung. Beachten Sie, dass sich die Festlegung des Werts auf "true"auf die Batch-Exportleistung auswirken kann.
schema.name
evaluationInfo.segmentation
false
gesetzt ist. Der Wert true
zeigt an, dass die Segmentierung für den Exportauftrag durchgeführt werden muss.Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 200 mit Details zu Ihrem neu erstellten Exportauftrag zurück.
{
"id": 100,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{ORG_ID}",
"status": "NEW",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status": [
"realized"
]
}
],
"segmentQualificationTime": {
"startTime": "2018-01-01T00:00:00Z",
"endTime": "2018-02-01T00:00:00Z"
},
"fromIngestTimestamp": "2018-01-01T00:00:00Z",
"emptyProfiles": true
},
"additionalFields": {
"eventList": {
"fields": "_id, _experience",
"filter": {
"fromIngestTimestamp": "2018-01-01T00:00:00Z"
}
}
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
}
},
"computeGatewayJobId": {
"exportJob": ""
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
id
Wenn destination.segmentPerBatch
auf true
gesetzt worden wäre, hätte das obige destination
-Objekt ein batches
-Array, wie unten dargestellt:
"destination": {
"dataSetId": "{DATASET_ID}",
"segmentPerBatch": true,
"batches": [
{
"segmentId": "segment1",
"segmentNs": "ups",
"status": ["realized"],
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
{
"segmentId": "segment2",
"segmentNs": "AdCloud",
"status": "exited",
"batchId": "df4gssdfb93a09f7e37fa53ad52"
}
]
}
Bestimmten Exportauftrag abrufen get
Sie können detaillierte Informationen zu einem bestimmten Exportauftrag abrufen, indem Sie eine GET-Anfrage an den /export/jobs
-Endpunkt senden und im Anfragepfad die Kennung des Exportauftrags angeben, den Sie abrufen möchten.
API-Format
GET /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
des Exportauftrags, auf den Sie zugreifen möchten.Anfrage
curl -X GET https://platform.adobe.io/data/core/ups/export/jobs/11037 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 200 mit genauen Informationen zum angegebenen Exportauftrag zurück.
{
"id": 11037,
"jobType": "BATCH",
"destination": {
"datasetId": "5b7c86968f7b6501e21ba9df",
"segmentPerBatch": false,
"batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
},
"fields": "identities.id,personalEmail.address",
"schema": {
"name": "_xdm.context.profile"
},
"imsOrgId": "{ORG_ID}",
"status": "SUCCEEDED",
"filter": {
"segments": [
{
"segmentId": "52c26d0d-45f2-47a2-ab30-ed06abc981ff",
"segmentNs": "ups",
"status":[
"realized"
]
}
]
},
"mergePolicy": {
"id": "timestampOrdered-none-mp",
"version": 1
},
"profileInstanceId": "ups",
"metrics": {
"totalTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"profileExportTime": {
"startTimeInMs": 123456789000,
"endTimeInMs": 123456799000,
"totalTimeInMs": 10000
},
"totalExportedProfileCounter": 20,
"exportedProfileByNamespaceCounter": {
"namespace1": 10,
"namespace2": 5
}
},
"computeGatewayJobId": {
"exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94"
},
"creationTime": 1538615973895,
"updateTime": 1538616233239,
"requestId": "d995479c-8a08-4240-903b-af469c67be1f"
}
destination
Zielinformationen für die exportierten Daten:
datasetId
: Die ID des Datensatzes, in den die Daten exportiert wurden.segmentPerBatch
: Ein boolescher Wert, der anzeigt, ob Segment-IDs konsolidiert sind oder nicht. Der Wertfalse
bedeutet, dass alle Segment-IDs in einer Batch-Kennung enthalten waren. Der Werttrue
bedeutet, dass eine Segment-ID in eine Batch-Kennung exportiert wird.
fields
schema.name
filter.segments
Die exportierten Segmente. Die folgenden Felder sind enthalten:
segmentId
: Segment-ID für zu exportierende Profile.segmentNs
: Segment-Namespace für den angegebenensegmentID
.status
: Ein Array von Zeichenfolgen, die einen Statusfilter für diesegmentID
bereitstellen. Standardmäßig hatstatus
den Wert["realized"]
, der alle Profile darstellt, die zum aktuellen Zeitpunkt in das Segment fallen. Mögliche Werte sind:realized
undexited
. Der Wertrealized
bedeutet, dass das Profil für das Segment qualifiziert ist. Der Wertexiting
bedeutet, dass das Profil das Segment verlässt.
mergePolicy
metrics.totalTime
metrics.profileExportTime
totalExportedProfileCounter
Bestimmten Exportauftrag abbrechen oder löschen delete
Sie können das Löschen des angegebenen Exportauftrags anfordern, indem Sie eine DELETE-Anfrage an den Endpunkt /export/jobs
senden und im Anfragepfad die Kennung des Exportauftrags angeben, den Sie löschen möchten.
API-Format
DELETE /export/jobs/{EXPORT_JOB_ID}
{EXPORT_JOB_ID}
id
des Exportauftrags, den Sie löschen möchten.Anfrage
curl -X DELETE https://platform.adobe.io/data/core/ups/export/jobs/{EXPORT_JOB_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status 204 mit der folgenden Meldung zurück:
{
"status": true,
"message": "Export job has been marked for cancelling"
}
Nächste Schritte
Nach dem Lesen dieses Handbuchs haben Sie jetzt ein besseres Verständnis davon, wie Exportaufträge funktionieren.