Documentatie Experience Platform Handleiding voor bronaansluitingen

Een streaminggegevensstroom maken voor onbewerkte gegevens met de opdracht Flow Service API

Last update: Thu Dec 14 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Onderwerpen:
Bronnen

Gemaakt voor:

Ontwikkelaar

Deze zelfstudie behandelt de stappen voor het ophalen van onbewerkte gegevens van een streamingbronaansluiting en het naar Experience Platform brengen van deze gegevens via de Flow Service API.

Aan de slag

Voor deze zelfstudie hebt u een goed inzicht nodig in de volgende onderdelen van Adobe Experience Platform:

Experience Data Model (XDM) System: Het gestandaardiseerde kader waardoor Experience Platform gegevens van de klantenervaring organiseert.
- Basisbeginselen van de schemacompositie: Leer over de basisbouwstenen van schema's XDM, met inbegrip van zeer belangrijke principes en beste praktijken in schemacompositie.
- Handleiding voor ontwikkelaars van het schema Register: Bevat belangrijke informatie die u moet weten om met succes vraag aan de Registratie API van het Schema uit te voeren. Dit omvat uw {TENANT_ID}, het concept "containers" en de vereiste kopteksten voor het indienen van verzoeken (met speciale aandacht voor de Accept-koptekst en de mogelijke waarden ervan).
Catalog Service: Catalog is het recordsysteem voor de gegevenslocatie en -lijn in het Experience Platform.
Streaming ingestion: Streaming opname for Platform biedt gebruikers een methode om gegevens van client- en serverapparaten in real-time naar het Experience Platform te verzenden.
Sandboxen: Experience Platform biedt virtuele sandboxen die één platforminstantie in afzonderlijke virtuele omgevingen verdelen om toepassingen voor digitale ervaringen te ontwikkelen en te ontwikkelen.

Platform-API's gebruiken

Voor informatie over hoe te om vraag aan Platform APIs met succes te maken, zie de gids op aan de slag met platform-API's.

Een bronverbinding maken source

Deze zelfstudie vereist ook dat u een geldige bron-verbindings-id hebt voor een streamingconnector. Als u deze informatie niet hebt, raadpleegt u de volgende zelfstudies over het maken van een streamingbronverbinding voordat u deze zelfstudie probeert:

Een doel-XDM-schema maken target-schema

Om de brongegevens in Platform te gebruiken, moet een doelschema worden gecreeerd om de brongegevens volgens uw behoeften te structureren. Het doelschema wordt dan gebruikt om een dataset van het Platform tot stand te brengen waarin de brongegevens bevat zijn. Dit doel-XDM-schema breidt ook het XDM-schema uit Individual Profile klasse.

Om een doelXDM schema tot stand te brengen, doe een verzoek van de POST aan /schemas het eindpunt van de Schema Registry API.

API-indeling

POST /tenant/schemas

Verzoek

Met het volgende voorbeeldverzoek wordt een XDM-schema gemaakt dat de XDM uitbreidt Individual Profile klasse.

curl -X POST \
    'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
    -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 'Content-Type: application/json' \
    -d '{
        "type": "object",
        "title": "Sample schema for a streaming connector",
        "description": "Sample schema for a streaming connector",
        "allOf": [
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile"
            },
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
            },
            {
                "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
            }
        ],
        "meta:containerId": "tenant",
        "meta:resourceType": "schemas",
        "meta:xdmType": "object",
        "meta:class": "https://ns.adobe.com/xdm/context/profile"
    }'

Antwoord

Een succesvolle reactie keert details van het onlangs gecreëerde schema met inbegrip van zijn uniek herkenningsteken terug ($id). Deze id wordt vereist in recentere stappen om een doeldataset, afbeelding, en dataflow tot stand te brengen.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
    "meta:altId": "_{TENANT_ID}.schemas.e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "Sample schema for a streaming connector",
    "type": "object",
    "description": "Sample schema for a streaming connector",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "imsOrg": "{ORG_ID}",
    "meta:extensible": false,
    "meta:abstract": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1604960074752,
        "repo:lastModifiedDate": 1604960074752,
        "xdm:createdClientId": "{CREATED_CLIENT_ID}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT_ID}",
        "xdm:createdUserId": "{CREATED_USER_ID}",
        "xdm:lastModifiedUserId": "{MODIFIED_USER_ID}",
        "eTag": "8522a151effd974429518ed90c3eaf6efc9bf6ffb6644087a85c6d4455dcd045",
        "meta:globalLibVersion": "1.16.1"
    },
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:containerId": "tenant",
    "meta:sandboxId": "{SANDBOX_ID}",
    "meta:sandboxType": "production",
    "meta:tenantNamespace": "_{TENANT_ID}"
}

Een doelgegevensset maken

Met een doel-XDM-schema gemaakt en uniek $id u kunt een doeldataset nu tot stand brengen om uw brongegevens te bevatten. Om een doeldataset te creëren, doe een verzoek van de POST aan dataSets het eindpunt van de Catalogusservice-API, terwijl het verstrekken van identiteitskaart van het doelschema binnen de lading.

API-indeling

POST /catalog/dataSets

Verzoek

curl -X POST \
    'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
    -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 'Content-Type: application/json' \
    -d '{
        "name": "Test streaming dataset",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "identity": [
            "enabled:true"
            ],
            "profile": [
            "enabled:true"
            ]
        }
    }'

Eigenschap

Beschrijving

name

De naam van de gegevensset die moet worden gemaakt.

schemaRef.id

De URI $id voor het schema XDM zal de dataset op worden gebaseerd.

schemaRef.contentType

De versie van het schema. Deze waarde moet worden ingesteld op application/vnd.adobe.xed-full-notext+json;version=1, die de laatste secundaire versie van het schema retourneert. Zie de sectie over schemaversie in de XDM API-handleiding voor meer informatie.

Antwoord

Een succesvolle reactie keert een serie terug die identiteitskaart van de pas gecreëerde dataset in het formaat bevat "@/datasets/{DATASET_ID}". De dataset ID is een read-only, systeem-geproduceerde koord dat wordt gebruikt om de dataset in API vraag van verwijzingen te voorzien. De doel dataset identiteitskaart wordt vereist in recentere stappen om een doelverbinding en een dataflow tot stand te brengen.

[
    "@/dataSets/5f7187bac6d00f194fb937c0"
]

Een doelverbinding maken target-connection

De verbindingen van het doel leiden tot en leiden een bestemmingsverbinding aan Platform of om het even welke plaats waar de overgebrachte gegevens zullen landen. De verbindingen van het doel bevatten informatie betreffende gegevensbestemming, gegevensformaat, en identiteitskaart van de doelverbinding die wordt vereist om een gegevensstroom tot stand te brengen. De de verbindingsinstanties van het doel zijn specifiek voor een huurder en organisatie.

Om een doelverbinding tot stand te brengen, doe een verzoek van de POST aan /targetConnections het eindpunt van de Flow Service API. Als onderdeel van de aanvraag moet u de volgende gegevens opgeven: dataSetId opgehaald in de vorige stap, en vaste identiteitskaart van de verbindingsspecificatie verbonden aan Data Lake. Deze id is c604ff05-7f1a-43c0-8e18-33bf874cb11c.

API-indeling

POST /targetConnections

Verzoek

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -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 'Content-Type: application/json' \
    -d '{
        "name": "Streaming target connection",
        "description": "Streaming target connection",
        "connectionSpec": {
            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        },
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
                "version": "application/vnd.adobe.xed-full+json;version=1"
            }
        },
        "params": {
            "dataSetId": "5f7187bac6d00f194fb937c0"
        }
    }'

Eigenschap

Beschrijving

data.format

De opgegeven indeling van de gegevens die u aan het datumpigment toevoegt.

params.dataSetId

Identiteitskaart van de doeldataset die in de vorige stap wordt geproduceerd. Opmerking: U moet een geldige dataset-id opgeven wanneer u een doelverbinding maakt. Een ongeldige dataset ID zal in een fout resulteren.

connectionSpec.id

De verbinding-specificatie-id die wordt gebruikt om verbinding te maken met het datumpeer. Deze id is: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Antwoord

Een geslaagde reactie retourneert de unieke id van de nieuwe doelverbinding (id). Deze id is vereist in latere stappen.

{
    "id": "d9300194-6a82-4163-b001-946a821163b8",
    "etag": "\"4006d3e4-0000-0200-0000-5f7189220000\""
}

Een toewijzing maken mapping

Opdat de brongegevens in een doeldataset moeten worden opgenomen, moet het eerst aan het doelschema worden in kaart gebracht dat de doeldataset zich aan houdt.

Als u een toewijzingenset wilt maken, vraagt u een POST aan de mappingSets het eindpunt van de Data Prep API terwijl u uw doel-XDM-schema aanbiedt $id en de details van de toewijzingssets die u wilt maken.

API-indeling

POST /mappingSets

Verzoek

curl -X POST \
    'https://platform.adobe.io/data/foundation/mappingSets' \
    -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 'Content-Type: application/json' \
    -d '{
        "version": 0,
        "xdmSchema": "_{TENANT_ID}.schemas.e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
        "xdmVersion": "1.0",
        "mappings": [
            {
                "destinationXdmPath": "person.name.firstName",
                "sourceAttribute": "firstName",
                "identity": false,
                "version": 0
            },
            {
                "destinationXdmPath": "person.name.lastName",
                "sourceAttribute": "lastName",
                "identity": false,
                "version": 0
            }
        ]
    }'

Eigenschap

Beschrijving

xdmSchema

De $id van het doel-XDM-schema.

Antwoord

Een geslaagde reactie retourneert details van de nieuwe toewijzing inclusief de unieke id (id). Deze id is in een latere stap vereist om een gegevensstroom te maken.

{
    "id": "380b032b445a46008e77585e046efe5e",
    "version": 0,
    "createdDate": 1604960750613,
    "modifiedDate": 1604960750613,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

Een lijst met gegevensstroomspecificaties ophalen specs

Een gegevensstroom is verantwoordelijk voor het verzamelen van gegevens uit bronnen en het brengen van hen in Platform. Als u een gegevensstroom wilt maken, moet u eerst de dataflow-specificaties verkrijgen door een verzoek van de GET naar de Flow Service API.

API-indeling

GET /flowSpecs

Verzoek

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/flowSpecs' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwoord

Een succesvolle reactie keert een lijst van dataflow specificaties terug. De gegevensstroomspecificatie-id die u moet ophalen om een gegevensstroom te maken met behulp van een van de volgende Amazon Kinesis, Azure Event Hubs, of Google PubSub, is d69717ba-71b4-4313-b654-49f9cf126d7a.

{
    "items": [
        {
            "id": "d69717ba-71b4-4313-b654-49f9cf126d7a",
            "name": "Stream data with optional transformation",
            "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
            "version": "1.0",
            "sourceConnectionSpecIds": [
                "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
                "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
                "86043421-563b-46ec-8e6c-e23184711bf6",
                "70116022-a743-464a-bbfe-e226a7f8210c"
            ],
            "targetConnectionSpecIds": [
                "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
                "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
                "db4fe783-ef79-4a12-bda9-32b2b1bc3b2c"
            ],
            "transformationSpecs": [
                {
                    "name": "Mapping",
                    "spec": {
                        "$schema": "http://json-schema.org/draft-07/schema#",
                        "type": "object",
                        "description": "defines various params required for different mapping from source to target",
                        "properties": {
                            "mappingId": {
                                "type": "string"
                            }
                        }
                    }
                }
            ],
            "attributes": {
                "uiAttributes": {
                    "apiFeatures": {
                        "flowRunsSupported": false
                    }
                }
            },
            "permissionsInfo": {
                "view": [
                    {
                        "@type": "lowLevel",
                        "name": "StreamingSource",
                        "permissions": [
                            "read"
                        ]
                    }
                ],
                "manage": [
                    {
                        "@type": "lowLevel",
                        "name": "StreamingSource",
                        "permissions": [
                            "write"
                        ]
                    }
                ]
            }
        },
    ]
}

Een gegevensstroom maken

De laatste stap op weg naar het verzamelen van streaminggegevens is het maken van een gegevensstroom. Momenteel zijn de volgende vereiste waarden voorbereid:

Bronverbinding-id
Doel-verbindings-id
Toewijzing-id
Dataflow-specificatie-id

Een dataflow is verantwoordelijk voor het plannen en verzamelen van gegevens uit een bron. U kunt een gegevensstroom tot stand brengen door een verzoek van de POST uit te voeren terwijl het verstrekken van de eerder vermelde waarden binnen de lading.

API-indeling

POST /flows

Verzoek

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/flows' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Streaming dataflow",
        "description": "Streaming dataflow",
        "flowSpec": {
            "id": "d69717ba-71b4-4313-b654-49f9cf126d7a",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "e96d6135-4b50-446e-922c-6dd66672b6b2"
        ],
        "targetConnectionIds": [
            "723222e2-6ab9-4b0b-b222-e26ab9bb0bc2"
        ],
        "transformations": [
            {
                "name": "Mapping",
                "params": {
                    "mappingId": "380b032b445a46008e77585e046efe5e",
                    "mappingVersion": 0
                }
            }
        ]
    }'

Eigenschap

Beschrijving

flowSpec.id

De stroom-specificatie-id opgehaald in de vorige stap.

sourceConnectionIds

De bron-verbindings-id opgehaald in een eerdere stap.

targetConnectionIds

De doel-verbindings-id opgehaald in een eerdere stap.

transformations.params.mappingId

De toewijzing-id opgehaald in een eerdere stap.

Antwoord

Een geslaagde reactie retourneert de id (id) van de nieuwe gegevensstroom.

{
    "id": "1f086c23-2ea8-4d06-886c-232ea8bd061d",
    "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}

Gegevens voor inname plaatsen

Bekijk hieronder de voorbeeldlading voor voorbeelden van ruw of XDM-Volgzaam json die u voor opname kunt verzenden.

NOTE

U moet een vertraging van minstens ~5 minuten toevoegen tussen het maken van een gegevensstroom en het invoeren van streaming gegevens. Hierdoor kan de gegevensstroom volledig worden ingeschakeld, voordat er gegevens worden ingevoerd.

De volgende voorbeelden zijn van toepassing op alle:

Onbewerkte gegevens

code language-json

code language-json
`'{ "name": "Johnson Smith", "location": { "city": "Seattle", "country": "United State of America", "address": "3692 Main Street" }, "gender": "Male", "birthday": { "year": 1984, "month": 6, "day": 9 } }'`

'{
      "name": "Johnson Smith",
      "location": {
          "city": "Seattle",
          "country": "United State of America",
          "address": "3692 Main Street"
      },
      "gender": "Male",
      "birthday": {
          "year": 1984,
          "month": 6,
          "day": 9
      }
  }'

XDM-gegevens

code language-json

code language-json
{ "header": { "schemaRef": { "id": "https://ns.adobe.com/aepstreamingservicesint/schemas/73cae7e6db06ebca535cd973e3ece85e66253962f504e7d8", "contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0" } }, "body": { "xdmMeta": { "schemaRef": { "id": "https://ns.adobe.com/aepstreamingservicesint/schemas/73cae7e6db06ebca535cd973e3ece85e66253962f504e7d8", "contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0" } }, "xdmEntity": { "_id": "acme", "workEmail": { "address": "mike@acme.com", "primary": true, "type": "work", "status": "active" }, "person": { "gender": "male", "name": { "firstName": "Mike", "lastName": "Wazowski" }, "birthDate": "1985-01-01" }, "identityMap": { "ecid": [ { "id": "01262118050522051420082102000000000000" } ] } } } }

{
  "header": {
    "schemaRef": {
      "id": "https://ns.adobe.com/aepstreamingservicesint/schemas/73cae7e6db06ebca535cd973e3ece85e66253962f504e7d8",
      "contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
    }
  },
  "body": {
    "xdmMeta": {
      "schemaRef": {
        "id": "https://ns.adobe.com/aepstreamingservicesint/schemas/73cae7e6db06ebca535cd973e3ece85e66253962f504e7d8",
        "contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
      }
    },
    "xdmEntity": {
      "_id": "acme",
      "workEmail": {
        "address": "mike@acme.com",
        "primary": true,
        "type": "work",
        "status": "active"
      },
      "person": {
        "gender": "male",
        "name": {
          "firstName": "Mike",
          "lastName": "Wazowski"
        },
        "birthDate": "1985-01-01"
      },
      "identityMap": {
        "ecid": [
          {
            "id": "01262118050522051420082102000000000000"
          }
        ]
      }
    }
  }
}

Volgende stappen

Aan de hand van deze zelfstudie hebt u een gegevensstroom gemaakt voor het verzamelen van streaminggegevens via de streamingconnector. Inkomende gegevens kunnen nu worden gebruikt door downstreamplatformdiensten zoals Real-Time Customer Profile en Data Science Workspace. Raadpleeg de volgende documenten voor meer informatie:

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089