Ontwikkeling van ETL-integratie voor Adobe Experience Platform

In de ETL-integratiehandleiding worden algemene stappen beschreven voor het maken van krachtige, veilige connectors voor Experience Platform en het opnemen van gegevens in Platform .

Deze handleiding bevat ook voorbeeld-API-aanroepen die moeten worden gebruikt bij het ontwerpen van een ETL-connector, met koppelingen naar documentatie die elke Experience Platform -service beschrijft en meer in detail het gebruik van de bijbehorende API.

Een steekproefintegratie is beschikbaar op GitHub via de Code van de Verwijzing van de Integratie van het Ecosysteem ETLonder Apache Versie van de Vergunning 2.0.

Workflow

Het volgende workflowdiagram biedt een overzicht op hoog niveau voor de integratie van Adobe Experience Platform-componenten met een ETL-toepassing en -aansluiting.

Adobe Experience Platform-componenten

Er zijn veelvoudige Experience Platform componenten betrokken bij ETL schakelaarintegratie. In de volgende lijst worden verschillende belangrijke componenten en functies beschreven:

Aan de slag met Experience Platform API's

De volgende secties bevatten aanvullende informatie die u nodig hebt of die u zelf nodig hebt om aanroepen van Experience Platform API's te kunnen uitvoeren.

API-voorbeeldaanroepen lezen

Deze gids verstrekt voorbeeld API vraag om aan te tonen hoe te om uw verzoeken te formatteren. Dit zijn paden, vereiste kopteksten en correct opgemaakte ladingen voor aanvragen. Voorbeeld-JSON die wordt geretourneerd in API-reacties, wordt ook verschaft. Voor informatie over de overeenkomsten die in documentatie voor steekproef API vraag worden gebruikt, zie de sectie op hoe te om voorbeeld API vraagin de Experience Platform het oplossen van problemengids te lezen.

Waarden verzamelen voor vereiste koppen

Om vraag aan Platform APIs te maken, moet u het authentificatieleerprogrammaeerst voltooien. Als u de zelfstudie over verificatie voltooit, krijgt u de waarden voor elk van de vereiste headers in alle API-aanroepen van Experience Platform , zoals hieronder wordt getoond:

Alle bronnen in Experience Platform zijn geïsoleerd naar specifieke virtuele sandboxen. Alle aanvragen naar Platform API's vereisen een header die de naam van de sandbox opgeeft waarin de bewerking plaatsvindt:

Alle verzoeken die een nuttige lading (POST, PUT, PATCH) bevatten vereisen een extra kopbal:

Algemene gebruikersstroom

Om te beginnen, registreert een gebruiker ETL in het Experience Platform gebruikersinterface (UI) en leidt datasets voor opname gebruikend een standaardschakelaar of een duw-dienst schakelaar.

In UI, leidt de gebruiker tot de outputdataset door een datasetschema te selecteren. De keuze van het schema hangt af van het type gegevens (record- of tijdreeks) dat in Platform wordt opgenomen. Door op het lusje van Schema binnen UI te klikken, zal de gebruiker alle beschikbare schema's, met inbegrip van het gedragstype kunnen bekijken dat het schema steunt.

In ETL zal de gebruiker beginnen hun toewijzingstransformaties te ontwerpen nadat de aangewezen verbinding (gebruikend hun geloofsbrieven) wordt gevormd. Er wordt aangenomen dat voor het ETL-hulpprogramma al Experience Platform -connectors zijn geïnstalleerd (proces niet gedefinieerd in deze integratiegids).

Mockups voor een hulpmiddel en een werkschema van steekproefETL zijn verstrekt in het werkschema ETL. Hoewel de ETL-gereedschappen verschillende indelingen kunnen hebben, zijn de meeste toepassingen beschikbaar voor vergelijkbare functies.

Lijst met gegevenssets weergeven

Gebruikend de bron van gegevens voor afbeelding, kan een lijst van alle beschikbare datasets worden gehaald gebruikend Catalog API.

U kunt één enkele API verzoek uitgeven om alle beschikbare datasets (b.v. GET /dataSets) te bekijken, met beste praktijken die zijn om vraagparameters te omvatten die de grootte van de reactie beperken.

In gevallen waarin volledige gegevenssetinformatie wordt gevraagd, kan de antwoordlading voorbij 3 GB in grootte bereiken, die algemene prestaties kan vertragen. Daarom zal het gebruiken van vraagparameters om slechts de benodigde informatie te filtreren Catalog vragen efficiënter maken.

Filteren op List

Wanneer het filtreren van reacties, kunt u veelvoudige filters in één enkele vraag gebruiken door parameters met een ampersand (&) te scheiden. Sommige queryparameters accepteren door komma's gescheiden lijsten met waarden, zoals het filter "Eigenschappen" in de voorbeeldaanvraag hieronder.

Catalog de reacties worden automatisch gemeten volgens gevormde grenzen, nochtans kan de "grens"vraagparameter worden gebruikt om de beperkingen aan te passen en het aantal teruggekeerde voorwerpen te beperken. De vooraf geconfigureerde limiet voor de respons van Catalog is:

De parameters van de vraag worden behandeld in meer detail in het overzicht van de Dienst van de Catalogus.

API formaat

GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -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}"

Gelieve te verwijzen naar het overzicht van de Dienst van de Catalogusvoor gedetailleerde voorbeelden van hoe te om vraag aan Catalog API te maken.

Reactie

De reactie omvat drie (limit=3) datasets die de "naam", "beschrijving", en "schemaRef"zoals die door de properties vraagparameter wordt vermeld tonen.

{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Gegevenssetschema weergeven

Het "schemaRef"bezit van een dataset bevat URI die het XDM schema van verwijzingen voorzien waarop de dataset gebaseerd is. Het XDM-schema ("schemaRef") vertegenwoordigt alle potentiële velden die door de dataset kunnen worden gebruikt, niet noodzakelijkerwijs de velden die worden gebruikt (zie "observableSchema" hieronder).

Het XDM-schema is het schema dat u gebruikt wanneer u de gebruiker een lijst moet geven met alle beschikbare velden waarnaar kan worden geschreven.

De eerste "schemaRef.id"waarde in het vorige reactievoorwerp (https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18) is URI die aan een specifiek schema XDM in Schema Registry richt. Het schema kan worden opgehaald door een opzoekaanvraag (GET) in te dienen bij de Schema Registry API.

API formaat

GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

Verzoek

De aanvraag gebruikt de URL-gecodeerde id URI van het schema (de waarde van het kenmerk "schemaRef.id") en vereist een Accept-header.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \

De responsindeling is afhankelijk van het type Accept-header dat in de aanvraag wordt verzonden. Voor opzoekverzoeken moet ook een version worden opgenomen in de koptekst Accepteren. In de volgende tabel worden de beschikbare kopteksten voor zoekopdrachten geaccepteerd:

Reactie

Het JSON-schema dat wordt geretourneerd, beschrijft de structuur en veldniveaugegevens ("type", "format", "minimum", "maximum", enz.) van de gegevens, geserialiseerd als JSON. Als het gebruiken van een rangschikkingsformaat buiten JSON voor opname (zoals Parquet of Scala), bevat de Gids van de Registratie van het Schemaeen lijst die het gewenste type JSON ("meta:xdmType") en zijn overeenkomstige vertegenwoordiging in andere formaten tonen.

Samen met deze tabel bevat de Schema Registry Developer Guide diepgaande voorbeelden van alle mogelijke aanroepen die met de Schema Registry API kunnen worden uitgevoerd.

De eigenschap "schema" van de gegevensset (VEROUDERD - EOL 2019-05-30)

Datasets kunnen een eigenschap "schema" bevatten die nu is vervangen en tijdelijk beschikbaar blijft voor achterwaartse compatibiliteit. Bijvoorbeeld, zou een lijst (GET) verzoek gelijkend op eerder gemaakt, waar "schema"werd vervangen "schemaRef"in de properties vraagparameter, het volgende kunnen terugkeren:

{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

Als het "schema"bezit van een dataset wordt bevolkt, wijst dit erop dat het schema een afgekeurd /xdms schema is en, waar gesteund, zou de schakelaar ETL de waarde in het "schema"bezit met het /xdms eindpunt (een afgekeurd eindpunt in Catalog API) moeten gebruiken om het erfenisschema terug te winnen.

API formaat

GET /catalog/{"schema" property without the "@"}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -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}"

Reactie

Gelijkaardig aan de stappen voor het bekijken datasetschema, bevat de reactie een schema JSON dat de structuur en gebied-vlakke informatie van de gegevens beschrijft, als JSON in series vervaardigd.

De eigenschap "observableSchema"

De eigenschap "observableSchema" van een dataset heeft een JSON-structuur die overeenkomt met die van het XDM-schema JSON. Het "observableSchema" bevat de velden die aanwezig waren in de binnenkomende invoerbestanden. Wanneer u gegevens naar Experience Platform schrijft, hoeft een gebruiker niet elk veld in het doelschema te gebruiken. In plaats daarvan moeten ze alleen die velden leveren die worden gebruikt.

Het waarneembare schema is het schema dat u zou gebruiken als u de gegevens leest of een lijst presenteert met velden die beschikbaar zijn om van te lezen/in kaart te brengen.

{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

Gegevens voorvertonen

De toepassing ETL kan een vermogen aan voorproefgegevens ( "Figuur 8"in het ETL- Werkschema verstrekken). De API voor gegevenstoegang biedt verschillende opties voor het voorvertonen van gegevens.

De extra informatie, met inbegrip van geleidelijke begeleiding voor het voorvertonen van gegevens die API gebruiken van de gegevenstoegang, kan in het leerprogramma van de gegevenstoegangworden gevonden.

Krijg datasetdetails gebruikend de "eigenschappen"vraagparameter

Zoals aangetoond in de stappen hierboven aan mening een lijst van datasets, kunt u "dossiers"verzoeken gebruikend de "eigenschappen"vraagparameter.

U kunt naar het overzicht van de Dienst van de Catalogusvoor gedetailleerde informatie over het vragen van datasets en beschikbare reactiefilters verwijzen.

API formaat

GET /catalog/dataSets?limit={value}&properties={value}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -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}"

Reactie

De reactie zal één dataset (limit=1) omvatten die het "dossiers"bezit tonen.

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSetFiles?dataSetId=5bf479a6a8c862000050e3c7"
  }
}

Gegevenssetbestanden weergeven met het kenmerk "files"

U kunt ook een verzoek van de GET gebruiken om dossierdetails te halen gebruikend het "dossiers"attribuut.

API formaat

GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: 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}"

Reactie

De reactie omvat identiteitskaart van het Dossier van de Dataset als top-level bezit, met dossierdetails bevat binnen het voorwerp van identiteitskaart van het Dossier van de Dataset.

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Bestandsgegevens ophalen

De id's van het gegevenssetbestand die in de vorige reactie zijn geretourneerd, kunnen worden gebruikt in een GET-aanvraag om meer bestandsgegevens op te halen via de Data Access API.

Het overzicht van de gegevenstoegangbevat details op hoe te om Data Access API te gebruiken.

API formaat

GET /export/files/{DATASET_FILE_ID}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -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}"

Reactie

[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

Bestandsgegevens voorvertonen

De eigenschap "href" kan worden gebruikt om voorvertoningsgegevens op te halen via de Data Access API .

API formaat

GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -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}"

Het antwoord op het bovenstaande verzoek bevat een voorvertoning van de inhoud van het bestand.

Meer informatie over Data Access API, met inbegrip van gedetailleerde verzoeken en reacties, is beschikbaar in het overzicht van de gegevenstoegang.

"fileDescription" ophalen uit gegevensset

De bestemmingscomponent als output van getransformeerde gegevens, zal de Ingenieur van Gegevens een Dataset van de Output ( "Figuur 12"in het ETL- Werkschema) kiezen. Het XDM-schema is gekoppeld aan de uitvoergegevensset. De te schrijven gegevens worden geïdentificeerd door het kenmerk "fileDescription" van de gegevenssetentiteit van de API's voor gegevensdetectie. Deze informatie kan worden opgehaald gebruikend een dataset identiteitskaart ({DATASET_ID}). De eigenschap "fileDescription" in het JSON-antwoord geeft de gevraagde informatie.

API formaat

GET /catalog/dataSets/{DATASET_ID}

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: 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}"

Reactie

{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

De gegevens zullen aan Experience Platform worden geschreven gebruikend de Ingestie API van de Partij. Gegevens schrijven is een asynchroon proces. Wanneer gegevens naar Adobe Experience Platform worden geschreven, wordt alleen een batch gemaakt en gemarkeerd als een succes nadat de gegevens volledig zijn geschreven.

Gegevens in Experience Platform moeten worden geschreven in de vorm van Parquet-bestanden.

Uitvoeringsfase

Terwijl de uitvoering start, zal de connector (zoals gedefinieerd in de broncomponent) de gegevens lezen vanuit Experience Platform met behulp van Data Access API. Het transformatieproces leest de gegevens voor een bepaald tijdbereik. Intern, zal het partijen brondatasets vragen. Tijdens het vragen, zal het een geparameterized (het rollen voor tijdreeksgegevens, of stijgende gegevens) begindatum en lijstdatasetdossiers voor die partijen gebruiken, en begint verzoeken om gegevens voor die datasetdossiers te doen.

Voorbeeldtransformaties

Het de transformaties van steekproefETLdocument bevat een aantal voorbeeldtransformaties, met inbegrip van identiteit behandeling en gegevens-type afbeeldingen. Gebruik deze transformaties ter referentie.

Gegevens lezen uit Experience Platform

Gebruikend Catalog API, kunt u alle partijen tussen een gespecificeerde begintijd en eindtijd ophalen, en hen sorteren op de orde zij werden gecreeerd.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: 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}"

De details op het filtreren van partijen kunnen in het leerprogramma van de Toegang van Gegevensworden gevonden.

Bestanden ophalen uit een batch

Zodra u identiteitskaart voor de partij hebt u zoekt ({BATCH_ID}), is het mogelijk om een lijst van dossiers terug te winnen die tot een specifieke partij via Data Access API behoren. De details voor het doen dit zijn beschikbaar in het Data Access leerprogramma.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -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}"

Bestanden openen met bestands-id

Gebruikend unieke identiteitskaart van een dossier ({FILE_ID), Data Access APIkan worden gebruikt om tot de specifieke details van het dossier, met inbegrip van zijn naam, grootte in bytes, en een verbinding toegang te hebben om het te downloaden.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_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}"

De reactie kan naar één bestand of naar een map verwijzen. De details op elk kunnen in het Data Access leerprogrammaworden gevonden.

Bestandsinhoud openen

Data Access APIkan worden gebruikt om tot de inhoud van een specifiek dossier toegang te hebben. Om de inhoud op te halen, wordt een GET-aanvraag gedaan met de waarde die wordt geretourneerd voor _links.self.href wanneer een bestand wordt geopend met de bestands-id.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -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}"

Het antwoord op deze aanvraag bevat de inhoud van het bestand. Voor meer informatie, met inbegrip van details op antwoordpaginering, zie hoe te Gegevens van de Vraag via de toegang API van de gegevenstoegangleerprogramma.

Records voor schemaconformiteit valideren

Wanneer gegevens worden geschreven, kunnen gebruikers ervoor kiezen om gegevens te valideren volgens de validatieregels die in het XDM-schema zijn gedefinieerd. Meer informatie over schemabevestiging kan in de ETL Code van de Verwijzing van de Integratie van het Ecosysteem op GitHub worden gevonden.

Als u de verwijzingsimplementatie gebruikt die op GitHub wordt gevonden, kunt u schemabevestiging in deze implementatie aanzetten gebruikend het systeembezit -DenableSchemaValidation=true.

Validatie kan worden uitgevoerd voor logische XDM-typen, met kenmerken zoals minLength en maxlength voor tekenreeksen, minimum en maximum voor gehele getallen en meer. De de ontwikkelaarsgids van de Registratie van het Schema APIbevat een lijst die types XDM en de eigenschappen schetst die voor bevestiging kunnen worden gebruikt.

Een batch maken

Zodra het gegeven wordt verwerkt, zal het hulpmiddel ETL de gegevens terug naar Experience Platform schrijven gebruikend de Ingestie API van de Partij. Voordat gegevens kunnen worden toegevoegd aan een gegevensset, moet deze worden gekoppeld aan een batch die later wordt geüpload naar een specifieke gegevensset.

Verzoek

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: 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}"
      }'

De details voor het creëren van een partij, met inbegrip van steekproefverzoeken en reacties kunnen in het overzicht van de Opname van de Partij van de Partijworden gevonden.

Schrijven naar gegevensset

Nadat een nieuwe partij met succes tot stand is gebracht, kunnen de dossiers dan aan een specifieke dataset worden geupload. U kunt meerdere bestanden in een batch plaatsen totdat deze worden gepromoot. Bestanden kunnen worden geüpload met de API voor het uploaden van kleine bestanden. Als uw bestanden echter te groot zijn en de gatewaylimiet wordt overschreden, kunt u de API voor het uploaden van grote bestanden gebruiken. De details voor het gebruiken van zowel Groot als Klein Dossier uploaden kunnen in het overzicht van de Opname van de Partij van de Partijworden gevonden.

Verzoek

Gegevens in Experience Platform moeten worden geschreven in de vorm van Parquet-bestanden.

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

Batchupload voltooien

Nadat alle bestanden naar de batch zijn geüpload, kan de batch worden gemarkeerd als voltooid. Op deze manier worden de Catalog "DataSetFile"-items gemaakt voor de voltooide bestanden en gekoppeld aan de generatiebatch. De batch Catalog wordt vervolgens gemarkeerd als succesvol, waardoor stroomafwaartse stromen worden geactiveerd om de beschikbare gegevens in te voeren.

De gegevens worden eerst op de halteplaats op Adobe Experience Platform geland en vervolgens na catalogisering en validatie naar de uiteindelijke locatie verplaatst. De partijen zullen als succesvol worden gemerkt zodra alle gegevens naar een permanente plaats worden verplaatst.

Verzoek

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

Als dit lukt, retourneert de reactie HTTP Status 200 OK en is de hoofdtekst van de reactie leeg.

Het ETL-hulpmiddel zorgt ervoor dat de tijdstempel van de brongegevensset(s) wordt genoteerd wanneer de gegevens worden gelezen.

Bij de volgende transformatie-uitvoering, waarschijnlijk door planning of aanroeping van de gebeurtenis, zal ETL beginnen om de gegevens van eerder-bewaarde timestamp en alle gegevens te vragen die door:gaan.

Laatste batchstatus ophalen

Voordat u nieuwe taken uitvoert met het gereedschap ETL, moet u controleren of de laatste batch is voltooid. Catalog Service APIverstrekt een batch-specifieke optie die de details van de relevante partijen verstrekt.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: 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}"

Reactie

Nieuwe taken kunnen worden gepland als de vorige batch-"status"-waarde "success" is, zoals hieronder wordt getoond:

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Laatste batchstatus ophalen op id

Een individuele partijstatus kan door Catalog Service API worden teruggewonnendoor een GET verzoek uit te geven gebruikend {BATCH_ID}. De gebruikte {BATCH_ID} zou dezelfde zijn als de id die werd geretourneerd toen de batch werd gemaakt.

Verzoek

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: 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}"

Reactie - Succes

De volgende reactie laat een "succes" zien:

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Reactie - Mislukking

In geval van een storing kunnen de "fouten" worden opgehaald uit het antwoord en op het ETL-gereedschap worden weergegeven als foutberichten.

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

Incrementele versus momentopnamegegevens en gebeurtenissen vs. profielen

Gegevens kunnen als volgt in een twee bij twee matrix worden vertegenwoordigd:

Gebeurtenisgegevens zijn doorgaans wanneer elke rij geïndexeerde tijdstempelkolommen bevat.

Profielgegevens worden doorgaans gebruikt wanneer er geen tijdstempel in de gegevens staat en elke rij kan worden geïdentificeerd met een primaire/samengestelde sleutel.

Met incrementele gegevens worden alleen nieuwe/bijgewerkte gegevens in het systeem opgenomen en toegevoegd aan de huidige gegevens in de gegevenssets.

De gegevens van de momentopname zijn wanneer alle gegevens in het systeem komen en sommige of alle vorige gegevens in een dataset vervangen.

In het geval van incrementele gebeurtenissen moet het ETL-gereedschap de beschikbare datums gebruiken/de aanmaakdatum van de batchentiteit. In het geval van de pushservice zijn er geen beschikbare datums. Voor het markeren van toenamen wordt dus gebruikgemaakt van een batch gemaakt/bijgewerkte datum. Elke batch incrementele gebeurtenissen moet worden verwerkt.

Voor incrementele profielen gebruikt ETL-tool gemaakte/bijgewerkte datums van batchentiteiten. Doorgaans moet elke batch incrementele profielgegevens worden verwerkt.

Gebeurtenissen voor momentopnamen zijn zeer minder waarschijnlijk als gevolg van de grootte van de gegevens. Maar als dit vereist zou zijn, moet het ETL hulpmiddel slechts de laatste partij voor verwerking kiezen.

Wanneer momentopnameprofielen worden gebruikt, zal het hulpmiddel ETL de laatste partij van de gegevens moeten kiezen die in het systeem aankwamen. Maar als de vereiste is om de versies van veranderingen te volgen, dan zullen alle partijen moeten worden verwerkt. De verwerking van deduplicatie binnen het ETL-proces zal helpen de opslagkosten te beheersen.

Batch opnieuw afspelen en gegevens opnieuw verwerken

Het opnieuw afspelen van batches en het opwerken van gegevens kunnen vereist zijn in gevallen waarin een klant ontdekt dat de laatste 'n' dagen, de gegevens die worden verwerkt niet zoals verwacht hebben plaatsgevonden of de brongegevens zelf wellicht niet correct zijn geweest.

Hiertoe gebruiken de gegevensbeheerders van de client de gebruikersinterface van Platform om de batches met beschadigde gegevens te verwijderen. Vervolgens zal de ETL waarschijnlijk opnieuw moeten worden uitgevoerd, zodat de ETL met correcte gegevens kan worden gerepareerd. Als de bron zelf corrupte gegevens had, zal de gegevensingenieur/beheerder de bronpartijen moeten verbeteren en de gegevens (of in Adobe Experience Platform of via schakelaars ETL) opnieuw opnemen.

Gebaseerd op het type van gegevens die worden geproduceerd, zal het de keus van de gegevensingenieur zijn om één enkele partij of alle partijen uit bepaalde datasets te verwijderen. Gegevens worden verwijderd/gearchiveerd volgens de Experience Platform richtlijnen.

Het is waarschijnlijk een scenario dat de functionaliteit ETL om gegevens te zuiveren belangrijk zal zijn.

Zodra het leegmaken is voltooid, moeten de clientbeheerders Adobe Experience Platform opnieuw configureren om de verwerking voor kernservices opnieuw te starten vanaf het moment dat de batches worden verwijderd.

Gelijktijdige batchverwerking

Naar eigen goeddunken van de klant kunnen gegevensbeheerders/engineers besluiten gegevens op sequentiële wijze of op gelijktijdige wijze te extraheren, te transformeren en te laden, afhankelijk van de kenmerken van een bepaalde gegevensset. Dit wordt ook gebaseerd op het geval waarin de client de getransformeerde gegevens gebruikt.

Bijvoorbeeld, als de cliënt aan een updatable persistentieopslag voortduurt en de opeenvolging of de orde van gebeurtenissen belangrijk is, kan de cliënt banen met opeenvolgende transformaties strikt moeten verwerken ETL.

In andere gevallen kunnen gegevens in de vorm van een out-of-order worden verwerkt door downstreamtoepassingen/processen die intern worden gesorteerd met een opgegeven tijdstempel. In die gevallen kunnen parallelle ETL-transformaties levensvatbaar zijn om de verwerkingstijd te verbeteren.

Voor bronbatches is dit weer afhankelijk van de voorkeur van de klant en de beperking van de consument. Als de brongegevens parallel kunnen worden opgepikt zonder dat rekening wordt gehouden met de urgentie/volgorde van een rij, kan het transformatieproces procesbatches maken met een hogere mate van parallellisme (optimalisatie gebaseerd op verwerking buiten bestelling). Maar als de transformatie tijdstempels moet respecteren of belangrijkheidsvolgorde moet wijzigen, moeten de API voor gegevenstoegang of ETL-toolplanner/aanroeping ervoor zorgen dat batches waar mogelijk niet buiten de bestelling worden verwerkt.

Uitstel

Uitstel is een proces waarbij de inputgegevens nog niet volledig genoeg zijn om naar downstreamprocessen te worden verzonden, maar in de toekomst bruikbaar kunnen zijn. Clients zullen hun individuele tolerantie voor gegevensramen voor toekomstige matching tegenover de kosten van verwerking bepalen om hun beslissing om gegevens te reserveren en opnieuw te verwerken in de volgende transformatieuitvoering te informeren, in de hoop dat het op een bepaald tijdstip in het bewaarvenster kan worden verrijkt en in overeenstemming gebracht/vastgemaakt. Deze cyclus loopt tot de rij voldoende is verwerkt of te groot wordt geacht om te blijven investeren in. Elke herhaling genereert uitgestelde gegevens die een superset zijn van alle uitgestelde gegevens in vorige herhalingen.

Adobe Experience Platform identificeert momenteel geen uitgestelde gegevens, zodat moeten de cliëntimplementaties zich op de ETL en de handconfiguraties van Dataset baseren om een andere dataset in Platform te creëren die de brondataset weerspiegelt die kan worden gebruikt om uitgestelde gegevens te houden. In dit geval zijn uitgestelde gegevens vergelijkbaar met momentopnamegegevens. Bij elke uitvoering van de ETL-transformatie worden de brongegevens verenigd met uitgestelde gegevens en verzonden voor verwerking.

Changelog