Spracovanie schémy

V závislosti od zdroja údajov môžu, ale nemusia byť explicitne uvedené informácie o typoch údajov a názvoch stĺpcov. Rozhrania OData REST API to zvyčajne riešia pomocou definície $metadata a metóda Power Query OData.Feed automaticky spracováva analýzu týchto informácií a ich použitie na údaje vrátené zo zdroja OData.

Mnohé rozhrania REST API neobsahujú spôsob, ako programovo určiť ich schému. V týchto prípadoch bude potrebné do konektora zahrnúť definíciu schémy.

Jednoduchý pevne zakódovaný prístup

Najjednoduchším prístupom je naprogramovať definíciu schémy do konektora. To je pre väčšinu prípadov použitia dostatočné.

Vcelku má vynútenie schémy na údajoch vrátených konektorom niekoľko výhod, ako napríklad:

• Nastavenie správnych typov údajov.
• odstránenie stĺpcov, ktoré sa nemusia zobrazovať koncovým používateľom (napríklad interné ID alebo informácie o stave).
• Uistite sa, že každá strana údajov má rovnaký tvar, a to pridaním všetkých stĺpcov, ktoré môžu chýbať v odpovedi (rozhrania REST API zvyčajne označujú, že polia majú mať hodnotu null, keď ich úplne vynecháte).

Zobrazenie existujúcej schémy pomocou Table.Schema

Zoberme si nasledujúci kód, ktorý vráti jednoduchú tabuľku z ukážkovej služby TripPin OData:

let
    url = "https://services.odata.org/TripPinWebApiService/Airlines",
    source = Json.Document(Web.Contents(url))[value],
    asTable = Table.FromRecords(source)
in
    asTable

Poznámka

TripPin je zdrojom OData, takže realisticky by dávalo väčší zmysel jednoducho použiť OData.Feed automatické spracovanie schémy funkcie. V tomto príklade budete považovať zdroj za typické rozhranie REST API a s cieľom Web.Contents ručne predviesť techniku pevného kódovania schémy.

Táto tabuľka je výsledkom:

Užitočnú Table.Schema funkciu môžete použiť na kontrolu typu údajov stĺpcov:

let
    url = "https://services.odata.org/TripPinWebApiService/Airlines",
    source = Json.Document(Web.Contents(url))[value],
    asTable = Table.FromRecords(source)
in
    Table.Schema(asTable)

Kód leteckej spoločnosti a Názov sú any typu. Table.Schema vráti veľa metaúdajov o stĺpcoch v tabuľke vrátane názvov, pozícií, informácií o type a mnohých pokročilých vlastností, ako sú presnosť, mierka a maxLength. Teraz by ste sa mali zaoberať len pripisovaným typom (TypeName), primitívnym typom (Kind) a otázkou, či hodnota stĺpca môže byť null (IsNullable).

Definovanie jednoduchej tabuľky schémy

Tabuľka schémy sa bude zostavovať z dvoch stĺpcov:

Stĺpec	Podrobnosti
Meno	Názov stĺpca. Musí sa zhodovať s názvom vo výsledkoch vrátených službou.
Typ	Typ údajov jazyka M, ktorý sa chystáte nastaviť. Môže to byť primitívny typ (text, číslo, dátum a čas atď.) alebo pripísaný typ (Int64.Type, Currency.Type a tak ďalej).

Tabuľka s pevnou schémou pre tabuľku Airlines nastaví jej AirlineCode stĺpce a Name na text takto vyzerá:

Airlines = #table({"Name", "Type"}, {
        {"AirlineCode", type text},
        {"Name", type text}
    })

Pri pohľade na niektoré z ďalších koncových bodov zvážte nasledujúce tabuľky schém:

Tabuľka Airports obsahuje štyri polia, ktoré si budete chcieť ponechať (vrátane jedného typu record):

Airports = #table({"Name", "Type"}, {
        {"IcaoCode", type text},
        {"Name", type text},
        {"IataCode", type text},
        {"Location", type record}
    })

Tabuľka People má sedem polí vrátane lists (Emails, AddressInfo), stĺpca s povolenou hodnotou null (Gender) a stĺpca s pripísaným typom (Concurrency):

People = #table({"Name", "Type"}, {
        {"UserName", type text},
        {"FirstName", type text},
        {"LastName", type text},
        {"Emails", type list},
        {"AddressInfo", type list},
        {"Gender", type nullable text},
        {"Concurrency", Int64.Type}
    })

Všetky tieto tabuľky môžete vložiť do jednej hlavnej tabuľky SchemaTableschémy:

SchemaTable = #table({"Entity", "SchemaTable"}, {
        {"Airlines", Airlines},
        {"Airports", Airports},
        {"People", People}
    })

Pomocná funkcia schemaTransformTable

Pomocná SchemaTransformTablefunkcia popísaná nižšie sa použije na vynútenie schém na vašich údajoch. Nadobúda nasledujúce parametre:

Parameter	Zadať	Description
table	table	Tabuľka údajov, pre ktorú chcete schému vynútiť.
schéma	table	Tabuľka schémy na čítanie informácií o stĺpci z tabuľky s nasledujúcim typom: type table [Name = text, Type = type].
enforceSchema (vynútiť schému)	number	(voliteľné) Enum, ktorý riadi správanie funkcie. Predvolená hodnota (EnforceSchema.Strict = 1) zabezpečí, že výstupná tabuľka sa bude zhodovať s tabuľkou schémy, ktorá bola poskytnutá pridaním chýbajúcich stĺpcov a odstránením ďalších stĺpcov. Možnosť EnforceSchema.IgnoreExtraColumns = 2 možno použiť na zachovanie ďalších stĺpcov vo výsledku. Keď EnforceSchema.IgnoreMissingColumns = 3 sa použije, chýbajúce stĺpce aj ďalšie stĺpce sa budú ignorovať.

Logika pre túto funkciu vyzerá približne takto:

1. Určte, či v zdrojovej tabuľke chýbajú stĺpce.
2. Určte, či existujú ďalšie stĺpce.
3. Ignorovať štruktúrované stĺpce (typu list, recorda table) a stĺpce nastavené na typ any.
4. Používa Table.TransformColumnTypes sa na nastavenie každého typu stĺpca.
5. Zmeňte poradie stĺpcov na základe poradia, v akom sa zobrazujú v tabuľke schém.
6. Nastavte typ v samotnej tabuľke pomocou typu Value.ReplaceType.

Poznámka

Posledným krokom na nastavenie typu tabuľky bude odstránenie potreby, aby používateľské rozhranie Power Query odvodzovala informácie o type pri zobrazovaní výsledkov v editore dotazov, čo môže niekedy spôsobiť dvojité volanie rozhrania API.

Zhrnutie

Vo väčšom kontexte úplného rozšírenia sa spracovanie schémy uskutoční po vrátení tabuľky z rozhrania API. Táto funkcia sa zvyčajne vykonáva na najnižšej úrovni stránkovanej funkcie (ak existuje), pričom informácie o entite sa odovzdávajú z navigačnej tabuľky.

Keďže implementácia stránkovaných a navigačných tabuliek je špecifická pre kontext, tu sa nezobrazí úplný príklad implementácie mechanizmu spracovania naprogramovanej schémy. Tento príklad TripPin ukazuje, ako môže vyzerať komplexné riešenie.

Sofistikovaný prístup

Pevne zakódovaná implementácia, ktorá je popísaná vyššie, robí dobrú prácu a zabezpečuje, aby schémy boli aj naďalej konzistentné pre jednoduché repsonsony JSON, ale je obmedzené na analýzu prvej úrovne odpovede. Hlboko vnorené množiny údajov by mohli využívať nasledujúci prístup, ktorý využíva typy jazyka M.

Tu je rýchle obnovenie typov v jazyku M podľa Špecifikácie jazyka:

Hodnota typu je hodnota, ktorá klasifikuje iné hodnoty. Znamená to, že hodnota, ktorá je klasifikovaná typom , zodpovedá danmu typu. Systém typov jazyka M sa skladá z nasledujúcich druhov typov:

• Jednoduché typy, ktoré klasifikujú primitívne hodnoty (binary, , datetimedate, durationdatetimezone, , list, logical, null, number, record, text, , time, type) a zahŕňajú aj množstvo abstraktných typov (function, table, anya none).
• Typy záznamov, ktoré klasifikujú hodnoty záznamu na základe názvov polí a typov hodnôt.
• Typy zoznamu, ktoré klasifikujú zoznamy pomocou jedného základného typu položky.
• Typy funkcií, ktoré klasifikujú hodnoty funkcií na základe typov ich parametrov a vrátených hodnôt.
• Typy tabuľky, ktoré klasifikujú hodnoty tabuľky na základe názvov stĺpcov, typov stĺpcov a kľúčov.
• Typy s povolenou hodnotou Null, ktoré klasifikujú hodnotu null okrem všetkých hodnôt klasifikovaných základným typom.
• Typy typov, ktoré klasifikujú hodnoty, ktoré sú typmi.

Pomocou nespracovaných výstupov JSON, ktoré získate (a/alebo pri pohľade na definície v $metadata služby), môžete definovať nasledujúce typy záznamov, ktoré predstavujú komplexné typy OData:

LocationType = type [
    Address = text,
    City = CityType,
    Loc = LocType
];

CityType = type [
    CountryRegion = text,
    Name = text,
    Region = text
];

LocType = type [
    #"type" = text,
    coordinates = {number},
    crs = CrsType
];

CrsType = type [
    #"type" = text,
    properties = record
];

Všimnite si, ako LocationType sa odkazuje na CityType a LocType predstavuje jeho štruktúrované stĺpce.

Pre entity najvyššej úrovne, ktoré budete chcieť reprezentovať ako tabuľky, môžete definovať typy tabuliek:

AirlinesType = type table [
    AirlineCode = text,
    Name = text
];
AirportsType = type table [
    Name = text,
    IataCode = text,
    Location = LocationType
];
PeopleType = type table [
    UserName = text,
    FirstName = text,
    LastName = text,
    Emails = {text},
    AddressInfo = {nullable LocationType},
    Gender = nullable text,
    Concurrency  Int64.Type
];

Potom môžete aktualizovať premennú SchemaTable (ktorú môžete použiť ako vyhľadávaciu tabuľku pre priradenia entity k typu) a použiť tieto nové definície typu:

SchemaTable = #table({"Entity", "Type"}, {
    {"Airlines", AirlinesType},
    {"Airports", AirportsType},
    {"People", PeopleType}
});

Na vynútenie schémy na údajoch sa môžete spoľahnúť na bežnú funkciu (Table.ChangeType), podobne ako v SchemaTransformTable predchádzajúcom cvičení. Na rozdiel od SchemaTransformTable– Table.ChangeType berie skutočný typ tabuľky jazyka M ako argument a použije vašu schému rekurzívne na všetky vnorené typy. Jeho podpis je:

Table.ChangeType = (table, tableType as type) as nullable table => ...

Poznámka

Pre flexibilitu je možné funkciu použiť v tabuľkách, ako aj v zoznamoch záznamov (čo je spôsob, akým sú tabuľky zastúpené v dokumente JSON).

Potom bude potrebné aktualizovať kód konektora, aby ste zmenili schema parameter z table na typea a pridajte volanie do Table.ChangeType. Opäť platí, že podrobnosti o tom sú veľmi špecifické pre implementáciu, a preto sa tu nedajú zapísať do podrobností. Tento rozšírený príklad konektora TripPin ukazuje komplexné riešenie implementujúce tento sofistikovanejší prístup na spracovanie schémy.