EN

Endnu en måde at indlæse data i CluedIn

#cluedin #python 

youtu.be/OrrXgSTDAl8?si=obU6bEeEHvTJa7_o

CluedIn Contrib Submitter er en uofficiel implementering af en clue submitter til CluedIn.

Den har fordele og ulemper sammenlignet med de standard dataindlæsningsmetoder i CluedIn. En mere detaljeret sammenligning følger efter beskrivelsen af, hvordan denne Submitter fungerer.

Sådan fungerer det

Kort sagt er Submitteren en pod (deployment), der kører i den samme AKS-klynge som CluedIn og har adgang til CluedIns message queue.

En bruger eller en automatiseret proces sender en POST-forespørgsel til Submitteren. Forespørgslen skal indeholde:

  • minimal påkrævet information om mapping
  • API token
  • data

Submitteren parser mapping-informationen og genererer clues ud fra forespørgslens data. De genererede clues sendes direkte til message queue.

Request

En typisk forespørgsel kan se sådan ud:

curl --location 'https://app.mycluedindomain.com/submitter/data?entity_type=%2FPerson&origin_code=Salesforce%3Aid&vocab_prefix=organization.sample&name=name&codes=Dynamics%3Aid%2CSharepoint%3Aname&incoming_edges=%2FManager%7C%2FEmployee%23Sharepoint%3AManagerId%2C%2FCustomer%7C%2FContact%23CRM%3Aid&outgoing_edges=%2FWorks%7C%2FOrganization%23Salesforce%3Aorg_id%2C%2FManages%7C%2FEmployee%23Sharepoint%3Aemployee_id' \
--header 'Authorization: Bearer {JWT}' \
--header 'Content-Type: application/json' \
--data '[
    {
        "id": 1,
        "name": "John Doe",
        "city": "London"
    },
    {
        "id": 2,
        "name": "Mary Jane",
        "city": "Paris"
    }
]'

Eller, hvis du bruger et UI-værktøj som Postman, kan det være endnu mere brugervenligt:

Query string-parametrene definerer den mapping-konfiguration, som Submitteren anvender på forespørgslens data.

Her er den fulde liste over aktuelt understøttede parametre:

entity_type

Obligatorisk parameter, fordi du ikke kan oprette en Entity uden at angive dens Entity Type. Eksempel: &entity_type=/Person

origin_code

Origin Entity Code-parameteren er også obligatorisk, fordi hver entitet skal have én Origin Entity Code. Origin Entity Code afhænger også af Entity Type-parameteren, men da begge parametre er obligatoriske, har det kun betydning for fejlmeddelelserne - Submitteren kan ikke parse Entity Code uden at vide, hvad dens Entity Type er.

Eksempel: &origin_code=Salesforce:id.

Lad os kigge nærmere på dette eksempel: Entity Type er udeladt, fordi den er angivet i entity_type-parameteren. Salesforce er Entity Code'ens Origin, og id er navnet på den property, hvor Submitteren skal finde værdien for at generere en Origin Entity Code til en bestemt clue.

For eksempel, hvis posten er:

    {
        "id": 1,
        "name": "John Doe",
        "city": "London"
    },

Hvis konfigurationen er: &entity_type=/Person&&origin_code=Salesforce:id, tager Submitteren id-propertyen fra posten og genererer en Clue med Entity Type /Person og med Origin Entity Code /Person#Salesforce:1.

Du kan derfor betragte de fleste parametertemplates som noget, Submitteren oversætter til rigtige Clue-properties.

vocab_prefix

Vocabulary Prefix er den sidste af tre obligatoriske parametre. Et eksempel på en værdi er: &vocab_prefix=person.sample.

Så hver property fra den førnævnte post vil blive mappet til en vocabulary key som:

  • person.sample.id: 1
  • person.sample.name: John Doe
  • person.sample.city: London

Du behøver ikke oprette noget som Vocabulary eller Entity Type på forhånd, men du vil måske konfigurere mappingen senere i CluedIn.

codes

codes er valgfri for yderligere Entity Codes, hvis du har brug for dem. Formatet er det samme som for origin_code, men i dette tilfælde er det en kommasepareret liste af koder. For eksempel: &codes=Dynamics:id,Sharepoint:name vil generere koderne: /Person#Dynamics:1 og /Person#Sharepoint:John Doe.

Hvis en post ikke har en given property, vil den tilsvarende kode ikke blive oprettet, men det betragtes ikke som en fejl.

name

Entity Name. Denne parameter er valgfri, men anbefales kraftigt. Det er vigtigt at huske, at dette ikke er det faktiske navn, men navnet på den property, hvor Submitteren finder det.

incoming_edges og outgoing_edges

Disse er to valgfri parametre for Entity Edges. Hvis du ikke angiver dem, sker der ingenting. Hvis du angiver dem forkert, får du en fejl.

Formatet er en kommasepareret liste af edges, hvor hver edge er /EdgeType|Origin:id.

Lad os sige, at du har angivet en Outgoing Entity Edge /Works|/Organization#Salesforce:org_id

Det betyder, at hvis org_id findes i en post, vil Submitteren oprette en Clue og tilføje en Outgoing Entity Edge fra Clue'ens Origin Entity Code til /Organization#Salesforce:5, forudsat at org_id-propertyen i posten er 5.

Payload

Payloaden skal være et gyldigt JSON-array.

Mapping

Du har i princippet ingen datamodellering på CluedIn-siden, fordi al mapping leveres i din forespørgsel, og det kan være så simpelt som:

  • Entity Type
  • Origin Entity Code
  • Vocabulary Prefix

Submitteren opretter clues ud fra de data, du sendte, og derefter kan du altid mappe vocabulary keys til andre keys, eller oprette yderligere Entity Codes eller Edges med Rules.

Response

Et typisk svar ser sådan ud:

{
    "submission": {
        "id": "8cfe4503-b38e-481d-ae92-0ae985ccf533",
        "timestamp": 1713503423257
    },
    "query_string": "?entity_type=/Person&vocab_prefix=organization.sample&codes=Dynamics:id,Sharepoint:name&origin_code=Salesforce:id&incoming_edges=/Manager|/Employee%23Sharepoint:ManagerId,/Customer|/Contact%23CRM:id&outgoing_edges=/Works|/Organization%23Salesforce:org_id,/Manages|/Employee%23Sharepoint:employee_id&name=name",
    "configuration": {
        "name_template": "name",
        "origin_entity_code_template": "/Person#Salesforce:id",
        "entity_type": "/Person",
        "vocabulary_prefix": "organization.sample",
        "entity_code_templates": "/Person#Dynamics:id,/Person#Sharepoint:name",
        "incoming_edges_templates": "EdgeType: /Manager; From: C:/Employee#Sharepoint:ManagerId; To: C:/Person#Salesforce:id; Properties: 0,EdgeType: /Customer; From: C:/Contact#CRM:id; To: C:/Person#Salesforce:id; Properties: 0",
        "outgoing_edges_templates": "EdgeType: /Works; From: C:/Person#Salesforce:id; To: C:/Organization#Salesforce:org_id; Properties: 0,EdgeType: /Manages; From: C:/Person#Salesforce:id; To: C:/Employee#Sharepoint:employee_id; Properties: 0"
    },
    "status": {
        "code": 200,
        "description": "OK"
    },
    "errors": [],
    "records": {
        "received": 2,
        "accepted": 2,
        "rejected": 0
    }
}

Det kan se ud som for meget information, men det er udelukkende nyttig information. For eksempel kan du korrelere submission-ID'et og tidsstemplet med dine postede data. Du kan også nemt tjekke svarkoden og beskrivelsen.

Derudover er to meget nyttige felter query_string og configuration. query_string viser dig, hvad du sendte i forespørgslens query string-parametre. Det er meget nyttigt at logge disse aktiviteter. configuration viser dig, hvordan denne query string blev parset af Submitteren. Hvis du ved et uheld lavede en tastefejl i et parameternavn, vil du altså kunne se, at det ikke blev opfanget af Submitteren, så du kan opdage problemet tidligt.

Posttællingerne viser, hvor mange poster der blev parset fra payloaden (received), hvor mange poster der blev succesfuldt transformeret til Clues og publiceret til message queue (accepted), og hvor mange poster der ikke blev accepteret (rejected).

Submitteren fejler hurtigt. Dvs. hvis du postede 100 tusind poster i samme batch, og post nummer 255 ikke havde en property, der er nødvendig for at oprette en Origin Entity Code, vil Submitteren ikke tjekke de resterende 99745 poster, men returnere en "Bad Request" med: received - 100000, accepted - 254, rejected - 99746. Desuden vil errors-samlingen indeholde information om den problematiske post, så du nemt kan lokalisere problemet.

Request-komprimering

Du kan fremskynde netværkskommunikationen med request compression. En CSV-fil på 1 GB kan normalt komprimeres til 200-250 MB, så du ikke overskrider grænsen for svarstørrelse og sender dine data hurtigere.

Her er et kodeeksempel på, hvordan du poster komprimeret indhold med Python:

import gzip
import json
import requests

def post_batch(batch):

    compressed_data = gzip.compress(json.dumps(batch).encode('utf-8'))

    response = requests.post(
        url='https://app.mycluedindomain.com/submitter/data?entity_type=/Test&origin_code=Test:UUID&vocab_prefix=test.demo&name=Name',
        data=compressed_data,
        headers={
            "Authorization": f"Bearer {CLUEDIN_TOKEN}",
            "Content-Encoding": "gzip",
            "Content-Type": "application/json"
        },
        timeout=600)

    try:
        print(response.status_code, response.json())
    except:
        print(response.status_code, response.text)

Fordele og ulemper

Som det ofte er tilfældet, kan den samme egenskab være en fordel eller en ulempe, afhængigt af hvem der bruger den.

Den vigtigste forskel ved den uofficielle Submitter er, at den forenkler dataindlæsning ved at springe alle funktioner over, der kan springes over på vejen til at indlæse data i CluedIn. Hvis du har Submitteren konfigureret, har du bare én URL (bortset fra forskelle i query string-parametre), og du kan sende alle dine data til det samme endpoint på næsten samme måde, som du ville sende dem til et standard CluedIn Ingestion Endpoint.

Denne tilgang gør livet lettere for en data engineer, der skal automatisere indlæsningen af flere datasæt i CluedIn. Du behøver ikke oprette endpoints i UI'et først, og du behøver ikke lave UI-mapping.

Af samme grund vil en forretningsbruger foretrække den standard CluedIn Ingestion Endpoints-tilgang, fordi al konfiguration sker i CluedIn UI med mulighed for at forhåndsvise, automatisk mappe properties til eksisterende vocabularies, oprette manglende vocabularies osv.