CDM folderin julkaisu REST endpointeina

Sami Ovaska | 03.02.2020
Lukuaika 4 min

Tavoite prototyypille on opiskella CDM SDK ja tutkia miten SDK:n avulla voisi CDM folderin julkaista REST endpointteina.

Tausta

Mitä CDM ja CDM folder ovat?

Common Data Model (CDM) on standardi ja laajennettava kokoelma schemoja (entiteettejä, attribuutteja, suhteita), jotka määrittelevät businesskonsepteja sekä aktiviteetteja. Nämä mahdollistavat datan yhteentoimivuuden eri sovellusten välillä. Entiteettien esimerkkejä: Account, Contact, Lead, Opportunity, Product, jne. Lisätietoa CDM:stä löydät täältä.

CDM folder pitää sisällään CDM metadata määritelmän tiedostossa model.json + datan CSV tiedostoissa, tallennettuna Azure DataLake gen2 storageen.

CDM on jo tuettu Common Data Servicessä, Dynamics 365:ssä, PowerAppsissa, Power BI:ssä, ja useassa Azuren data servicessä.

CDM:ää voi myös laajentaa omilla entiteeteillä, jotka kuvaavat juuri sinun datamallisi, ja tallentaa datan CDM folderiin. Jos sinulla on esimerkiksi legacy sovellus (esim. ERP tai PLM), joka ei tue dataformaattia jota voisi käyttää muista sovelluksista (esim. PowerBI tai Azure ML), voit määrittää datamallin CDM formatissa ja tallentaa datan legacy sovelluksesta Azure datalakeen. SDK tukee myös datan kirjoittamista CDM folderiin, mutta sitä ei käsitellä tässä artikkelissa.

Esimerkkidata

On helppoa luoda esimerkkidataa demotarkoitukseen jos organisaatiollasi on Microsoft Dynamics ja PowerApps. Huom: vain Admin voi tehdä tämän.

1. Luo Azure DataLake gen 2 storage https://portal.azure.com kautta
2. Kirjaudu sisään tenanttiisi osoitteessa https://www.powerapps.com
3. Vasemman puolen navigaatiosta valitse Data => Export to data lake
4. Valitse DataLake gen 2 storage jonka loit ensimmäisessä stepissä
5. Valitse Common Data Service (CDS) Entiteetit jotka haluat exportoida ja hyväksy muutokset (voit myös valita exportoidaanko data vain kerran, vai onko export jatkuvaa)

PowerApps exportoi valitut Entiteetit DataLakeen:

Esimerkissä valitsimme kolme Entiteettiä exportoitaviksi: systemuser, role ja fax (koska CTO ;)).

CDM metadata tiedosto on nimeltään model.json ja se löytyy juurikansioista. Entity specifinen data on tallennettu alihakemistoihin ”role” ja ”systemuser”. Yllättäen meillä ei ollut yhtään fax -sanomaa joten ”fax” alihakemistoa ei löydy datalakesta.

Avaamalla model.json tiedoston pystyt tutkimaan Entiteettien määritelmiä ja niihin liitettyjä datapartitioita. Entity määritelmät sisältävät useita attribuutteja (name ja datatyyppi).

SDK

SDK and CDM metadata määritelmät löytyvät osoitteesta https://aka.ms/cdmrepo. SDK:n avulla voi niin kirjoittaa kuin lukea dataa CDM folderiin/folderista.

Huomaa että SDK on aika uusi ja sen kanssa saattaa tulla ongelmia eteen. Itselläni tuli yksi ongelma vastaan, model.json tiedostossa partition uri sisältää https porttinumeron, mutta ADSL storage adapter ei tue sitä. Onneksi SDK sisältää lähdekoodit, joten pystyin korjaamaan bugin itse.

Proto API toteutus

Varoitus

Toteutus on quick-and-dirty tyyppinen esimerkki miten CDM folderin pystyy tarjoamaan REST apeina. Älä käytä sitä sellaisenaan tuotannossa. Esimerkissä on paljon asioita, joita pitää toteuttaa/parantaa tuotantokäyttöä ajatellen:

  • Autentikointi
  • Virhekäsittely
  • Salaisuudet KeyVaultiin

Toteutus

Käytän esimerkissä Asp.Net Corea. Aluksi loin tyhjän API -totutuksen komennolla

dotnet new web -n CDMApi

Sitten kopioin SDK:n hakemiston objectModel\CSharp\Microsoft.CommonDataModel.ObjectModel CDMApi hakemiston viereen, ja lisäsin referenssin SDK -projektiin CDMApi projektista.

Sovelluksessa on yksi ominaisuushakemisto jokaista Entiteettiä varten (Features/Faxes, Features/Roles ja Features/Systemusers). Noiden lisäksi on jaettu hakemisto Entiteettien kesken jaettuja luokkia varten.

Ominaisuushakemistoissa on kolme luokkaa

  • [EntityName]Controller – API controller
  • [EntityName]Model – POCO
  • [EntityName]Extensions – Extension methodi ominaisuuden DI:n konfigurointia varten

Jaettu hakemisto sisältää

  • ADLSSettings – DataLake asetukset
  • CDMMetadataRepository – Lukee CDM folderin ja käyttää EntityGeneratoria lukemaan Entiteettien data muistiin
  • CDMQuery<T> – Tarjoaa geneerisen metodin muistissa olevan Entity -datan hakuihin
  • CDMService<T> – Alustaa ja säilyttää Entiteetin muistissa olevan datan
  • CsvContentParser – CSV tiedoston parsinta
  • EntityGenerator – Rakentaa Entiteetin object mallin ja parsii Entiteetittien datat käyttäen CsvContentParseria

Huom: Muista asettaa ADLS asetukset appsettings.json -tiedostoon ennen kuin ajat sovellusta.

Kun sovellus käynnistyy, se lataa Entiteettien datat CDM folderista muistiin ennen kuin se aloittaa kuuntelemaan HTTP liikennettä.

Lähdekoodi löytyy https://github.com/sovaska/CDMApi

Mitä seuraavaksi

  • Olisi hienoa jos pystyisi luomaan C# POCOt ajon aikaisesti CDM:n perusteella
  • Tuki muille Entiteettien metadatalle, esim. primaryKey
  • Tuki Entiteettien suhteille
  • Tuki kaikille CDM:n tukemille datatyypeille
  • Tuki kaikille CSV formaateille, joita CDM tukee (tai vielä mieluummin pitäisi ottaa joku valmis CSV parseri käyttöön)
  • Datan uudelleen lukeminen kun se muuttuu DataLakessa
  • Isojen datamäärien tuki
  • Virhekäsittelyn parantaminen
  • Kirjoita metadataa ja siihen liittyvää dataa CDM folderiin