Roman Klimenko
EN

CluedIn-databerigelse

cluedinpythonazure

youtu.be/EHFraghW71Q?si=UBKnzONb7EosEcUJ

Med Enrich Rule Action kan du berige data i CluedIn med eksterne kilder.

Den kalder et API, som modtager en liste over Vocabulary Keys og returnerer en liste over properties. CluedIn gemmer disse properties med et bestemt Vocabulary Prefix. Du kan implementere API'et som en Azure Function, et REST API eller en anden tjeneste, der er tilgængelig via HTTP.

API'et henter data fra den eksterne kilde, behandler dem og returnerer properties til CluedIn.

Rule Action bruger følgende parametre:

  • URL: URL'en til enrichment-API'et.
  • Payload: En kommasepareret liste over Vocabulary Keys, der sendes til API'et.
  • Vocabulary Prefix: Det Vocabulary Prefix, der bruges til at gemme de properties, som API'et returnerer.

Når handlingen køres, sender den payloaden til API'et i en HTTP POST-request og gemmer de returnerede properties med det angivne Vocabulary Prefix.

Eksempel

I dette eksempel er customer.postcode en Vocabulary Key med britiske postnumre.

Den eksterne kilde er det åbne postcodes.io-API.

En request ser sådan ud:

curl --location 'api.postcodes.io/postcodes/CA2 6PJ'

Svar:

{
    "status": 200,
    "result": {
        "postcode": "CA2 6PJ",
        "quality": 1,
        "eastings": 338102,
        "northings": 554389,
        "country": "England",
        "nhs_ha": "North West",
        "longitude": -2.966283,
        "latitude": 54.880414,
        "european_electoral_region": "North West",
        "primary_care_trust": "Cumbria Teaching",
        "region": "North West",
        "lsoa": "Carlisle 009D",
        "msoa": "Carlisle 009",
        "incode": "6PJ",
        "outcode": "CA2",
        "parliamentary_constituency": "Carlisle",
        "parliamentary_constituency_2024": "Carlisle",
        "admin_district": "Cumberland",
        "parish": null,
        "admin_county": null,
        "date_of_introduction": "198001",
        "admin_ward": "Morton",
        "ced": "Morton",
        "ccg": "NHS North East and North Cumbria",
        "nuts": "Carlisle",
        "pfa": "Cumbria",
        "codes": {
            "admin_district": "E06000063",
            "admin_county": "E99999999",
            "admin_ward": "E05014205",
            "parish": "E43000295",
            "parliamentary_constituency": "E14000620",
            "parliamentary_constituency_2024": "E14001152",
            "ccg": "E38000215",
            "ccg_id": "01H",
            "ced": "E58000165",
            "nuts": "TLD12",
            "lsoa": "E01019231",
            "msoa": "E02003995",
            "lau2": "E07000028",
            "pfa": "E23000002"
        }
    }
}

Vi kan placere et API mellem CluedIn og postcodes.io. Her er en JavaScript Azure Function, som modtager nøglen customer.postcode, henter postnummerdata og returnerer dem til CluedIn:

const { app } = require("@azure/functions");
const querystring = require("node:querystring");

app.http("postcodes", {
  methods: ["POST"],
  authLevel: "anonymous",
  handler: async (request, context) => {
    const parsedBody = querystring.parse(await request.text());

    const postcode = parsedBody["customer.postcode"];

    const response = await fetch(
      `https://api.postcodes.io/postcodes/${postcode}`,
      {
        method: "GET",
        headers: {
          "Content-Type": "application/json",
        },
      }
    );

    return {
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(await response.json()),
      status: response.status,
    };
  },
});

Kald Azure Functionen med denne request:

curl --location 'https://postcodes.azurewebsites.net/api/postcodes' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'customer.postcode=CA2 6PJ'

Funktionen returnerer svaret fra postcodes.io-API'et.

Dette mellemled holder enrichment-logikken uden for CluedIn. Du kan skrive API'et i et hvilket som helst sprog og hoste det på enhver platform, der understøtter HTTP-requests.

Nu kan du oprette en Data Part- eller Golden Record-regel i CluedIn:

  • URL: URL'en til Azure Functionen.
  • Payload: customer.postcode, som sendes i request body.
  • Vocabulary Prefix: postcode, som bruges til at gemme de returnerede properties.

Når Rule Action køres, sender den payloaden til Azure Functionen og flader properties i JSON-svaret ud. Svaret ovenfor gemmes i den berigede Entity sådan:

{
  "postcode.status": 200,
  "postcode.result.postcode": "CA2 6PJ",
  "postcode.result.quality": 1,
  "postcode.result.eastings": 338102,
  "postcode.result.northings": 554389,
  "postcode.result.country": "England",
  "postcode.result.nhs_ha": "North West",
  "postcode.result.longitude": -2.966283,
  "postcode.result.latitude": 54.880414,
  "postcode.result.european_electoral_region": "North West",
  "postcode.result.primary_care_trust": "Cumbria Teaching",
  "postcode.result.region": "North West",
  "postcode.result.lsoa": "Carlisle 009D",
  "postcode.result.msoa": "Carlisle 009",
  "postcode.result.incode": "6PJ",
  "postcode.result.outcode": "CA2",
  "postcode.result.parliamentary_constituency": "Carlisle",
  "postcode.result.parliamentary_constituency_2024": "Carlisle",
  "postcode.result.admin_district": "Cumberland",
  "postcode.result.parish": null,
  "postcode.result.admin_county": null,
  "postcode.result.date_of_introduction": "198001",
  "postcode.result.admin_ward": "Morton",
  "postcode.result.ced": "Morton",
  "postcode.result.ccg": "NHS North East and North Cumbria",
  "postcode.result.nuts": "Carlisle",
  "postcode.result.pfa": "Cumbria",
  "postcode.codes.admin_district": "E06000063",
  "postcode.codes.admin_county": "E99999999",
  "postcode.codes.admin_ward": "E05014205",
  "postcode.codes.parish": "E43000295",
  "postcode.codes.parliamentary_constituency": "E14000620",
  "postcode.codes.parliamentary_constituency_2024": "E14001152",
  "postcode.codes.ccg": "E38000215",
  "postcode.codes.ccg_id": "01H",
  "postcode.codes.ced": "E58000165",
  "postcode.codes.nuts": "TLD12",
  "postcode.codes.lsoa": "E01019231",
  "postcode.codes.msoa": "E02003995",
  "postcode.codes.lau2": "E07000028",
  "postcode.codes.pfa": "E23000002"
}

Flere scenarier og gode råd

Datanormalisering

Hvis API'et returnerer en nøgle, der allerede findes i den berigede Entity, overskriver Rule Action værdien. Hvis du for eksempel vil normalisere telefonnumre eller adresser, kan API'et returnere de normaliserede data under de samme nøgler, som blev sendt til enrichment.

Datavalidering

Du kan også bruge Rule Action til at validere data. Et API kan for eksempel kontrollere, om en e-mailadresse er gyldig, og returnere en boolesk værdi. Rule Action gemmer værdien med det angivne Vocabulary Prefix.

Caching

Hvis den eksterne kilde er langsom eller har rate limits, kan dit API cache svar og genbruge dem, når det modtager den samme request inden for et bestemt tidsrum.

Rate Limiting

Hvis den eksterne kilde håndhæver rate limits, kan dit API implementere sin egen rate limiting-logik og returnere en fejl, når grænsen nås. Du kan genbehandle de berørte Entities senere.

Tilføj response-headeren Retry-After for at angive, hvornår requesten skal prøves igen, og returnér statuskoden 429 Too Many Requests.

Alternativt kan dit API modtage dataene og lægge dem i en kø til senere behandling.

Fejlhåndtering

Returnér altid JSON, også når der opstår en fejl. Rule Action gemmer fejlmeddelelsen i Entity, hvor den kan bruges til debugging eller overvågning.

Sikkerhed

Rule Action sender den API-nøgle, der er konfigureret i variablen CLUEDIN_RULE_ACTION_API_KEY. Dit API kan validere den, før requesten behandles.

Preview

Når du åbner Preview for Rule Action, sendes en request til API'et med is_preview sat til true. CluedIn-UI'et viser det preview-svar, som API'et returnerer.