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 importeras kan vara profildata från en platt fil (t.ex. en Parquet-fil) eller data som följer ett känt schema i Experience Data Model (XDM) register.
The API-referens 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 handboken är en del av API för gruppinmatning. Läs igenom komma igång-guide för länkar till relaterad dokumentation, en guide till hur du läser exempelanrop till API:er i det här dokumentet och viktig information om vilka huvuden som behövs för att kunna anropa ett Experience Platform-API.
Data Ingestion krav
- Data som ska överföras måste vara antingen i Parquet- eller JSON-format.
- En datauppsättning som skapats i Catalog services.
- Innehållet i Parquet-filen måste matcha en delmängd av schemat i datauppsättningen som överförs till.
- Ha din unika åtkomsttoken efter autentisering.
Bästa praxis för gruppkonsumtion
- Den rekommenderade batchstorleken är mellan 256 MB och 100 GB.
- Varje grupp bör innehålla högst 1 500 filer.
Begränsningar för batchförbrukning
Batchdatainmatning har vissa begränsningar:
- Maximalt antal filer per grupp: 1500
- Maximal batchstorlek: 100 GB
- Maximalt antal egenskaper eller fält per rad: 10000
- Maximalt antal batchar per minut, per användare: 138
Typer
När data hämtas är det viktigt att förstå 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 så inte är fallet misslyckas batchen med TypeCompatibilityException
.
Till exempel har varken JSON eller CSV en date
eller date-time
typ. Därför uttrycks dessa värden med Formaterade strängar enligt ISO 8061 ("2018-07-10T15:05:59.000-08:00") eller Unix-tid i millisekunder (1531263959000) och konverteras vid importen till mål-XDM-typen.
Tabellen nedan visar de konverteringar som stöds vid inmatning av data.
Använda API:et
The Data Ingestion Med API 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 tre grundläggande steg:
- Skapa en ny batch.
- Överför filer till en angiven datauppsättning som matchar datans XDM-schema.
- Signalera slutet av gruppen.
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}"
}'
datasetId
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}"
}
id
relatedObjects.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}
{BATCH_ID}
{DATASET_ID}
{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"
{FILE_PATH_AND_NAME}
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
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
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}
{BATCH_ID}
{DATASET_ID}
{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"
{FILE_PATH_AND_NAME}
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. Genom att göra det här Catalog DataSetFile-poster skapas för de slutförda filerna och kopplas till den grupp som genereras ovan. The Catalog batchen markeras sedan som lyckad, vilket aktiverar efterföljande flöden för att importera tillgängliga data.
Begäran
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
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}
{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"
}
}
}
{USER_ID}
The "status"
fält är det som visar aktuell status för den begärda batchen. Batcherna kan ha något av följande lägen: