Slutpunkt för profilexportjobb

Real-Time Customer Profile Med kan ni skapa en enda vy över enskilda kunder genom att sammanföra data från flera källor, både attributdata och beteendedata. Profildata kan sedan exporteras till en datauppsättning för vidare bearbetning. Till exempel: Profile data kan exporteras för aktivering genom att målgrupper skapas, och profilattribut kan exporteras för rapportering.

Det här dokumentet innehåller stegvisa instruktioner för att skapa och hantera exportjobb med Profil-API.

Förutom att skapa ett exportjobb kan du även använda Profile data med /entities slutpunkt, kallas ocksåProfile Access". Se slutpunktsguide för enheter för mer information. Anvisningar om hur du får åtkomst Profile data med användargränssnittet, se användarhandbok.

Komma igång

API-slutpunkterna som används i den här handboken är en del av Real-Time Customer Profile API. Innan du fortsätter bör du granska komma igång-guide för länkar till relaterad dokumentation, en guide till hur du läser exempel-API-anrop i det här dokumentet och viktig information om vilka huvuden som behövs för att kunna ringa anrop till Experience Platform API.

Skapa ett exportjobb

Exporterar Profile data måste först skapa en datauppsättning som data exporteras till och sedan starta ett nytt exportjobb. Båda dessa steg kan uppnås med Experience Platform API:er, där den första använder Catalog Service API och den senare med hjälp av Real-Time Customer Profile API. Detaljerade instruktioner för hur du slutför varje steg finns i följande avsnitt.

Skapa en måldatauppsättning

Vid export Profile måste en måldatauppsättning skapas först. Det är viktigt att datauppsättningen är korrekt konfigurerad för att exporten ska lyckas.

Ett av de viktigaste övervägandena är schemat som datauppsättningen baseras på (schemaRef.id i API-exempelbegäran nedan). För att kunna exportera profildata måste datauppsättningen baseras på XDM Individual Profile Unionens schema (https://ns.adobe.com/xdm/context/profile__union). Ett unionsschema är ett systemgenererat, skrivskyddat schema som samlar in fält i scheman som delar samma klass. I det här fallet är det XDM Individual Profile klassen. Mer information om unionens vyscheman finns i facksektion i grunderna för schemakompositionsguiden.

Stegen som följer i den här självstudiekursen visar hur du skapar en datauppsättning som refererar till XDM Individual Profile Unionsschema som använder Catalog API. Du kan också använda Platform användargränssnitt för att skapa en datauppsättning som refererar till unionsschemat. Steg för att använda användargränssnittet beskrivs i den här självstudiekursen för användargränssnitt för att exportera målgrupper men gäller även här. När du är klar kan du gå tillbaka till den här självstudiekursen och fortsätta med stegen för starta ett nytt exportjobb.

Om du redan har en kompatibel datauppsättning och känner till dess ID kan du fortsätta direkt till steget för starta ett nytt exportjobb.

API-format

POST /dataSets

Begäran

Följande begäran skapar en ny datauppsättning med konfigurationsparametrar i nyttolasten.

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": "Profile Data Export",
        "schemaRef": {
          "id": "https://ns.adobe.com/xdm/context/profile__union",
          "contentType": "application/vnd.adobe.xed+json;version=1"
        }
      }'

Svar

Ett lyckat svar returnerar en array som innehåller det skrivskyddade, systemgenererade, unika ID:t för den nya datauppsättningen. Det krävs ett korrekt konfigurerat datauppsättnings-ID för att profildata ska kunna exporteras.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Initiera exportjobb

När du har en datauppsättning som består av en union kan du skapa ett exportjobb som behåller profildata i datauppsättningen genom att göra en POST till /export/jobs slutpunkten i Real-Time Customer Profile API och ger information om de data som du vill exportera i själva förfrågningen.

API-format

POST /export/jobs

Begäran

Följande begäran skapar ett nytt exportjobb med konfigurationsparametrar i nyttolasten.

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: {ORG_ID}' \
  -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"
    }
  }'

Svar

Ett lyckat svar returnerar en datauppsättning ifylld med profildata som anges i begäran.

{
    "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": "{ORG_ID}",
    "creationTime": 1559674261657
}

Visa alla exportjobb

Du kan returnera en lista över alla exportjobb för en viss organisation genom att utföra en GET-begäran till export/jobs slutpunkt. Begäran stöder även frågeparametrar limit och offset, vilket visas nedan.

API-format

GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}

Begäran

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: {ORG_ID}'
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Svar

Svaret innehåller en records -objekt som innehåller de exportjobb som har skapats av organisationen.

{
  "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": "{ORG_ID}",
      "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": "{ORG_ID}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

Övervaka exportförlopp

Om du vill visa information om ett specifikt exportjobb, eller övervaka statusen när det bearbetas, kan du göra en GET-förfrågan till /export/jobs slutpunkt och inkludera id av exportjobbet i sökvägen. Exportjobbet är klart när status returnerar värdet "SUCCEEDED".

API-format

GET /export/jobs/{EXPORT_JOB_ID}

Begäran

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Svar

{
    "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": "{ORG_ID}",
    "creationTime": 1559674261657
}

Avbryt ett exportjobb

Med Experience Platform kan du avbryta ett befintligt exportjobb, vilket kan vara användbart av flera skäl, bland annat om exportjobbet inte slutfördes eller fastnade i bearbetningsfasen. Om du vill avbryta ett exportjobb kan du göra en DELETE-förfrågan till /export/jobs slutpunkt och inkludera id av det exportjobb som du vill avbryta till sökvägen för begäran.

API-format

DELETE /export/jobs/{EXPORT_JOB_ID}

Begäran

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Svar

En borttagningsbegäran returnerar HTTP-status 204 (inget innehåll) och en tom svarstext, vilket anger att åtgärden avbröts.

Nästa steg

När exporten är klar är dina data tillgängliga i Data Lake i Experience Platform. Du kan sedan använda API för dataåtkomst för att få åtkomst till data med batchId som är associerad med exporten. Beroende på exportens storlek kan data vara i segment och gruppen kan bestå av flera filer.

Följ de stegvisa instruktionerna om hur du använder API:t för dataåtkomst för att komma åt och hämta gruppfiler Dataåtkomst, genomgång.

Du kan också komma åt exporterade kundprofildata i realtid med Adobe Experience Platform Query Service. Med API:t UI eller RESTful kan du med Query Service skriva, validera och köra frågor på data i Data Lake.

Mer information om hur man hämtar in data från olika målgrupper finns i Dokumentation för frågetjänsten.

Bilaga

Följande avsnitt innehåller ytterligare information om exportjobb i profilens API.

Fler exempel på exportnyttolaster

Exempel-API-anropet som visas i avsnittet om starta ett exportjobb skapar ett jobb som innehåller både profildata (post) och händelsedata (tidsserie). I det här avsnittet finns ytterligare exempel på nyttolasten för begäran som begränsar exporten till att innehålla en datatyp eller en annan.

Följande nyttolast skapar ett exportjobb som bara innehåller profildata (inga händelser):

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

Om du vill skapa ett exportjobb som bara innehåller händelsedata (inga profilattribut) kan nyttolasten se ut ungefär så här:

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

Exportera målgrupper

Du kan också använda slutpunkten för exportjobb för att exportera målgrupper i stället för Profile data. Se guiden på exportjobb i segmenterings-API för mer information.