API-översikt för gruppinmatning

Med API:t för Adobe Experience Platform Batch Ingclosure kan du importera data till Platform som gruppfiler. Data som ska importeras kan vara profildata från en platt fil (till exempel en Parquet-fil) eller data som följer ett känt schema i Experience Data Model (XDM)-registret.

API-referensen för gruppinmatning innehåller ytterligare information om dessa API-anrop.

I följande diagram visas batchintagsprocessen:

Komma igång

API-slutpunkterna som används i den här guiden ingår i API:t för gruppinmatning. Innan du fortsätter bör du läsa kom igång-guiden för att få länkar till relaterad dokumentation, en guide till hur du läser exempelanropen för API i det här dokumentet och viktig information om vilka huvuden som krävs för att kunna anropa ett Experience Platform-API.

Krav för Data Ingestion

Bästa praxis för gruppkonsumtion

Begränsningar för batchförbrukning

Batchdatainmatning har vissa begränsningar:

Typer

När du importerar data är det viktigt att du förstår hur Experience Data Model (XDM)-scheman fungerar. Mer information om hur XDM-fälttyper mappas till olika format finns i Utvecklarhandbok för schemaregister.

Det finns viss flexibilitet vid inmatning av data - om en typ inte matchar vad som finns i målschemat konverteras data till den angivna måltypen. Om den inte kan det misslyckas gruppen med en TypeCompatibilityException.

Till exempel har varken JSON eller CSV typen date eller date-time. Därför uttrycks dessa värden med ISO 8601-formaterade strängar ("2018-07-10T15:05:59.000-08:00") eller Unix Time i millisekunder (153126395) 9000) och konverteras vid intag till mål-XDM-typen.

Tabellen nedan visar de konverteringar som stöds vid inmatning av data.

Använda API:et

Med API:t Data Ingestion kan du importera data som grupper (en dataenhet som består av en eller flera filer som ska importeras som en enda enhet) till Experience Platform i tre grundläggande steg:

Skapa en batch

Innan data kan läggas till i en datauppsättning måste de länkas till en batch, som senare överförs till en angiven datauppsättning.

POST /batches

Begäran

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "Content-Type: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}"
      }'

Svar

{
    "id": "{BATCH_ID}",
    "imsOrg": "{ORG_ID}",
    "updated": 0,
    "status": "loading",
    "created": 0,
    "relatedObjects": [
        {
            "type": "dataSet",
            "id": "{DATASET_ID}"
        }
    ],
    "version": "1.0.0",
    "tags": {},
    "createdUser": "{USER_ID}",
    "updatedUser": "{USER_ID}"
}

Filöverföring

När du har skapat en ny batch för överföring kan filer sedan överföras till en viss datauppsättning.

Du kan överföra filer med hjälp av API:t för liten filöverföring. Om filerna är för stora och gatewaygränsen överskrids (t.ex. utökade tidsgränser, begäranden om kroppsstorlek har överskridits och andra begränsningar) kan du växla till API:t för stor filöverföring. Denna API överför filen i segment och sammanfogar data med API-anropet Large File Upload Complete.

Liten filöverföring

När en batch har skapats kan data överföras till en befintlig datauppsättning. Filen som överförs måste matcha det refererade XDM-schemat.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Begäran

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Svar

#Status 200 OK, with empty response body

Stor filöverföring - skapa fil

Om du vill överföra en stor fil måste filen delas upp i mindre segment och överföras en åt gången.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize

Begäran

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Svar

#Status 201 CREATED, with empty response body

Stor filöverföring - överför efterföljande delar

När filen har skapats kan alla efterföljande segment överföras genom upprepade PATCH-begäranden, en för varje del av filen.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Begäran

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Svar

#Status 200 OK, with empty response

Slutförande av signalbatch

När alla filer har överförts till gruppen kan gruppen signaleras för slutförande. På så sätt skapas Catalog DataSetFile-posterna för de slutförda filerna och kopplas till den grupp som genereras ovan. Batchen Catalog markeras sedan som lyckad, vilket utlöser flödesomformningar för att importera tillgängliga data.

Begäran

POST /batches/{BATCH_ID}?action=COMPLETE

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Svar

#Status 200 OK, with empty response

Kontrollera batchstatus

I väntan på att filerna ska överföras till gruppen kan batchens status kontrolleras för att se dess förlopp.

API-format

GET /batch/{BATCH_ID}

Begäran

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

Svar

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}

Fältet "status" visar den aktuella statusen för den begärda batchen. Batcherna kan ha något av följande lägen:

Status för batchförtäring