CluedIn databerigelse
youtu.be/EHFraghW71Q?si=UBKnzONb7EosEcUJ
Enrich Rule Action er en fleksibel måde at berige data i CluedIn med eksterne datakilder.
Denne Rule Action kræver et API, der modtager en liste af vocabulary keys og returnerer en liste af properties. De returnerede properties gemmes med et angivet vocabulary-præfiks. API'et kan implementeres som en Azure Function, et REST API eller enhver anden tjeneste, der kan tilgås via HTTP.
API'et er også ansvarligt for at hente data fra den eksterne kilde, behandle dem og returnere properties til CluedIn.
Rule Action tager følgende parametre:
URL: URL'en til det berigende API.Payload: Kommasepareret liste af vocabulary keys, der sendes til API'et.Vocabulary Prefix: Vocabulary-præfikset, der bruges til at gemme properties returneret af API'et.
Når handlingen udføres, sender den payloaden til API'et (HTTP POST) og gemmer de returnerede properties med det angivne vocabulary-præfiks.
Eksempel
Vocabulary key med britiske postnumre: customer.postcode.
Åbent API, der returnerer postnummerdata: https://postcodes.io/.
For eksempel:
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 implementerer et API, for eksempel som en JavaScript Azure Function, der modtager customer.postcode-nøglen, henter postnummerdata fra postcodes.io-API'et og returnerer properties 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,
};
},
});
Når vi sender følgende request til Azure Function:
curl --location 'https://postcodes.azurewebsites.net/api/postcodes' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'customer.postcode=CA2 6PJ'
Returnerer den det samme svar som svaret fra postcodes.io-API'et.
API'et mellem CluedIn og den eksterne kilde er nødvendigt for at forenkle databerigelsesprocessen. API'et kan implementeres i ethvert sprog og hostes 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 Function.Payload-customer.postcode. Den sendes i request body.Vocabulary Prefix-postcode. De returnerede properties gemmes med dette præfiks.
Når Rule Action udføres, sender den payloaden til Azure Function og gemmer de returnerede properties med det angivne vocabulary-præfiks. JSON-request-properties flades ud, så svaret ovenfor gemmes i den berigede entitet som:
{
"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"
}
Yderligere scenarier og best practices
Datanormalisering
Hvis API'et returnerer en nøgle, der allerede findes i den berigede entitet, overskriver Rule Action værdien i entiteten. Du kan bruge det til at normalisere data som telefonnumre eller adresser -- implementer blot et API, der returnerer de normaliserede data i de samme nøgler, som sendes til berigelse.
Datavalidering
Du kan bruge Rule Action til at validere data. For eksempel kan du implementere et API, der kontrollerer, om en e-mailadresse er gyldig, og returnerer en boolsk værdi. Rule Action gemmer den boolske værdi med det angivne vocabulary-præfiks.
Caching
Hvis den eksterne kilde er langsom eller har rate limits, kan du implementere en caching-mekanisme i API'et. API'et kan cache svarene og returnere de cachede data, hvis den samme request sendes inden for en bestemt tidsramme.
Rate Limiting
Hvis den eksterne kilde har rate limits, kan du implementere en rate limiting-mekanisme i API'et. API'et kan returnere et fejlsvar, hvis rate limit overskrides. I så fald kan du genbehandle entiteterne med fejlsvaret senere.
Du kan også sende Retry-After-headeren i svaret for at angive, hvornår entiteten skal genbehandles. Og returnere 429 Too Many Requests-statuskoden.
Desuden kan dit API stadig modtage data og sende dem til en kø til senere behandling.
Fejlhåndtering
Returner altid JSON, selv hvis der opstår en fejl. Rule Action gemmer fejlmeddelelsen i entiteten, og du kan bruge den til debugging eller overvågningsformål.
Sikkerhed
Rule Action sender en API-nøgle konfigureret i variablen CLUEDIN_RULE_ACTION_API_KEY. API'et kan validere nøglen, inden det behandler requesten.
Preview
Når du bruger Preview-grænsefladen i Rule Action, sender den en request til API'et med is_preview-nøglen sat til true. API'et kan returnere et preview-svar, der vises i CluedIn-brugergrænsefladen.