Spracovanie overovania

Typy overovania

Rozšírenie môže podporovať jeden alebo viac typov overovania. Každý typ overovania je iný typ poverenia. Používateľské rozhranie overovania zobrazené koncovým používateľom v doplnku Power Query je riadené typom poverení, ktoré rozšírenie podporuje.

Zoznam podporovaných typov overovania je definovaný ako súčasť definície typu zdroja údajov rozšírenia. Každá overovacia hodnota je záznam so špecifickými poľami. V nasledujúcej tabuľke sú uvedené očakávané polia pre každý druh. Všetky polia sa vyžadujú, pokiaľ nie je uvedené inak.

Typ overenia Pole Description
Implicitný Implicitný (anonymný) typ overovania nemá žiadne polia.
OAuth StartLogin Funkcia, ktorá poskytuje URL a informácie o stave na spustenie toku OAuth.

Pozrite si časť Implementing a OAuth Flow nižšie.
FinishLogin Funkcia, ktorá extrahuje access_token a ďalšie vlastnosti súvisiace s tokom OAuth.
Obnoviť (nepovinné) Funkcia, ktorá načíta nový prístupový token z tokenu obnovenia.
Odhlásiť sa (nepovinné) Funkcia, ktorá zruší platnosť aktuálneho prístupového tokenu používateľa.
Označenie (nepovinné) Textová hodnota, ktorá vám umožní prepísať predvolené označenie pre tento AuthenticationKind.
Aad AuthorizationUri text hodnota alebo funkcia, ktorá vráti koncový bod autorizácie služby Azure AD (príklad: "https://login.microsoftonline.com/common/oauth2/authorize" ).

Pozrite si časť overenia Azure Active Directory nižšie.
Prostriedok text hodnota alebo funkcia, ktorá vráti hodnotu prostriedku Azure AD pre vašu službu.
UsernamePassword UsernameLabel (nepovinné) Textová hodnota, ktorá nahradí predvolené označenie textového poľa Používateľské meno v používateľskom označení poverení.
PasswordLabel (nepovinné) Textová hodnota, ktorá nahradí predvolené označenie textového poľa Heslo v používateľskému označení poverení.
Označenie (nepovinné) Textová hodnota, ktorá vám umožní prepísať predvolené označenie pre tento AuthenticationKind.
Windows UsernameLabel (nepovinné) Textová hodnota, ktorá nahradí predvolené označenie textového poľa Používateľské meno v používateľskom označení poverení.
PasswordLabel (nepovinné) Textová hodnota, ktorá nahradí predvolené označenie textového poľa Heslo v používateľskému označení poverení.
Označenie (nepovinné) Textová hodnota, ktorá vám umožní prepísať predvolené označenie pre tento AuthenticationKind.
Kľúč KeyLabel (nepovinné) Textová hodnota, ktorá nahradí predvolené označenie textového poľa kľúča rozhrania API v rozhraní poverení.
Označenie (nepovinné) Textová hodnota, ktorá vám umožní prepísať predvolené označenie pre tento AuthenticationKind.

V nižšie uvedenom vzore sa zobrazuje overovací záznam konektora, ktorý podporuje OAuth, Key, Windows, Basic (Používateľské meno a heslo) a anonymné poverenia.

Príklad:

Authentication = [
    OAuth = [
        StartLogin = StartLogin,
        FinishLogin = FinishLogin,
        Refresh = Refresh,
        Logout = Logout
    ],
    Key = [],
    UsernamePassword = [],
    Windows = [],
    Implicit = []
]

Prístup k aktuálnym povereniam

Aktuálne poverenia je možné získať pomocou Extension.CurrentCredential() funkcie.

M funkcie zdroja údajov, ktoré boli povolené na rozšíriteľnosť, automaticky zdedia rozsah poverení rozšírenia. Vo väčšine prípadov nebudete musieť explicitne pristupovať k aktuálnym povereniam, existujú však výnimky, ako napríklad:

  • Odovzdanie poverenia vo vlastnom parametri hlavičky alebo reťazca dotazu (napríklad pri používaní typu kľúča API)
  • Nastavenie vlastností reťazca pripojenia pre rozšírenia ODBC alebo ADO.NET
  • Kontrola vlastných vlastností tokenu OAuth
  • Používanie poverení ako súčasti toku OAuth v1

Extension.CurrentCredential()Funkcia vráti objekt záznamu. Polia, ktoré obsahuje, budú špecifické pre typ overenia. Podrobnosti nájdete v nasledujúcej tabuľke.

Pole Description Používa sa
AuthenticationKind Obsahuje názov autentifikačného druhu priradeného k tomuto povereniu (UsernamePassword, OAuth atď.). Všetko
Meno používateľa Hodnota používateľského mena UsernamePassword, Windows
Heslo Hodnota hesla. Zvyčajne sa používa s UsernamePassword, ale je tiež nastavený pre kľúč. Kľúč, UsernamePassword, Windows
access_token Hodnota tokenu prístupu OAuth. OAuth
Vlastnosti Záznam obsahujúci ďalšie vlastné vlastnosti pre dané poverenie. Zvyčajne sa používa s OAuth na ukladanie ďalších vlastností (napríklad refresh_token) vrátených s access_token počas toku overovania. OAuth
Kľúč Hodnota kľúča API. Všimnite si, že hodnota kľúča je k dispozícii aj v poli Heslo. V predvolenom nastavení ho mashup engine vloží do hlavičky autorizácie, ako keby táto hodnota bola základným auth heslom (bez používateľského mena). Ak toto nie je požadované správanie, musíte v zázname možností zadať možnosť ManualCredentials = true. Kľúč
EncryptConnection Logická hodnota, ktorá určuje, či sa má vyžadovať šifrované pripojenie k zdroju údajov. Táto hodnota je k dispozícii pre všetky typy overovania, ale nastaví sa len vtedy, ak je encryptconnection zadaná v definícii zdroja údajov. Všetko

Nasledujúca vzorka kódu pristupuje k aktuálnemu povereniu pre kľúč API a používa ho na vyplnenie vlastnej hlavičky ( x-APIKey ).

Príklad:

MyConnector.Raw = (_url as text) as binary =>
let
    apiKey = Extension.CurrentCredential()[Key],
    headers = [

        #"x-APIKey" = apiKey,
        Accept = "application/vnd.api+json",
        #"Content-Type" = "application/json"
    ],
    request = Web.Contents(_url, [ Headers = headers, ManualCredentials = true ])
in
    request

Implementácia Flow OAuth

Typ overovania OAuth umožňuje rozšírenie na implementáciu vlastnej logiky pre ich službu. Za týmto cieľom rozšírenie poskytne funkcie StartLogin (vrátenie povolenia URI na spustenie toku OAuth) a FinishLogin (výmena autorizačného kódu za prístupový token). Rozšírenia môžu voliteľne implementovať Refresh (výmena tokenu obnovenia za nový prístupový token) a Logout (vyprší aj aktuálne funkcie obnovenia a prístupu) .

Poznámka

Rozšírenia doplnku Power Query sa vyhodnocujú v aplikáciách spustených na klientskych počítačoch. Dátové konektory by nemali používať dôverné tajomstvá vo svojich tokoch OAuth, pretože používatelia môžu skontrolovať rozšírenie alebo sieťový prenos, aby sa dozvedeli tajomstvo. Ďalšie podrobnosti o poskytovaní tokov, ktoré sa nespoliehajú na zdieľané tajomstvá, nájdete v dôkaznom kľúči pre kód Exchange od OAuth Public Clients RFC (tiež známy ako PKCE). Ukážkovú implementáciu tohto toku nájdete na našom GitHub mieste.

Existujú dve sady podpisov funkcií OAuth; pôvodný podpis, ktorý obsahuje minimálny počet parametrov, a pokročilý podpis, ktorý akceptuje ďalšie parametre. Väčšina tokov OAuth je možné implementovať pomocou pôvodných podpisov. Môžete tiež kombinovať a zhodovať typy podpisov v implementácii. Hovory funkcií sú zhody na základe počtu parametrov (a ich typov). Názvy parametrov sa neberú do úvahy.

Ďalšie podrobnosti nájdete vo vzorke Github.

Originálne podpisy OAuth

StartLogin = (dataSourcePath, state, display) => ...;

FinishLogin = (context, callbackUri, state) => ...;

Refresh = (dataSourcePath, refreshToken) =>  ...;

Logout = (accessToken) => ...;

Rozšírené podpisy OAuth

Poznámky k pokročilým podpisom:

  • Všetky podpisy akceptujú clientApplication hodnotu záznamu, ktorá je vyhradená pre budúce použitie.
  • Všetky podpisy akceptujú dataSourcePath a (tiež označované ako resourceUrl vo väčšine vzoriek).
  • RefreshFunkcia akceptuje oldCredential parameter, ktorý je record predchádzajúcim vráteným FinishLogin vašou funkciou (alebo predchádzajúcim hovorom na Refresh ).
StartLogin = (clientApplication, dataSourcePath, state, display) => ...;

FinishLogin = (clientApplication, dataSourcePath, context, callbackUri, state) => ...;

Refresh = (clientApplication, dataSourcePath, oldCredential) =>  ...;

Logout = (clientApplication, dataSourcePath, accessToken) => ...;

overenie Azure Active Directory

Typ Aad autentifikácie je špecializovaná verzia OAuth pre Azure Active Directory. Používa rovnaký klient Azure AD ako vstavané konektory Power Query, ktoré podporujú overovanie konta organizácie.

Poznámka

Ak zdroj údajov vyžaduje iné rozsahy ako user_impersonation alebo nie je kompatibilný s používaním , mali by ste použiť typ user_impersonation OAuth overovania.

Poznámka

Ak implementujete vlastný tok OAuth pre azure AD, používatelia, ktorí povolili podmienený prístup pre svojho nájomníka, sa môžu vyskytnúť problémy pri obnovovaní pomocou služby Power BI. Neovplyejní to obnovenie založené na bráne, ale ovplyvní certifikovaný konektor, ktorý podporuje obnovenie zo služby Power BI. Používatelia sa môžu pri konfigurácii webových poverení prostredníctvom služby Power BI vyskytnúť problém vyplývajúci z konektora pomocou verejnej klientskej aplikácie. Prístupový token generovaný týmto postupom sa nakoniec použije na inom počítači (t. j. službe Power BI v dátovom centre Azure, nie v sieti spoločnosti) ako ten, ktorý sa pôvodne používal na overenie (t. j. počítač používateľa, ktorý konfiguruje poverenia zdroja údajov v sieti spoločnosti). Vstavaný Aad typ tento problém rieši pomocou iného klienta služby Azure AD pri konfigurácii poverení v službe Power BI. Táto možnosť nebude k dispozícii pre konektory, ktoré používajú OAuth typ overovania.

Väčšina konektorov bude musieť poskytnúť hodnoty pre AuthorizationUri polia a Resource polia. Obe polia môžu byť text hodnoty alebo funkcia jedného argumentu, ktorá vráti text value .

AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize"
AuthorizationUri = (dataSourcePath) => FunctionThatDeterminesAadEndpointFromDataSourcePath(dataSourcePath)
Resource = "77256ee0-fe79-11ea-adc1-0242ac120002"   // Azure AD resource value for your service - Guid or URL
Resource = (dataSourcePath) => FunctionThatDeterminesResourceFromDataSourcePath(dataSourcePath)

Konektory, ktoré používajú identifikátor založený na Uri, nemusia poskytovať Resource hodnotu. Predvolene sa hodnota bude rovnať koreňovej ceste parametra Uri konektora. Ak sa zdroj Azure AD zdroja údajov líši od hodnoty domény (napríklad používa identifikátor GUID), Resource potom je potrebné poskytnúť hodnotu.

Vzory aad autentifikačného druhu

V tomto prípade zdroj údajov podporuje globálny cloud Azure AD pomocou bežného nájomníka (žiadna podpora Azure B2B).

Authentication = [
    Aad = [
        AuthorizationUri = "https://login.microsoftonline.com/common/oauth2/authorize",
        Resource = "77256ee0-fe79-11ea-adc1-0242ac120002" // Azure AD resource value for your service - Guid or URL
    ]
]

V tomto prípade zdroj údajov podporuje zisťovanie nájomníka na základe openID Pripojenie (OIDC) alebo podobného protokolu. To umožňuje konektoru určiť správny koncový bod Azure AD, ktorý sa má použiť na základe jedného alebo viacerých parametrov v ceste zdroja údajov. Tento dynamický prístup k zisťovaniu umožňuje konektoru podporovať Azure B2B.


// Implement this function to retrieve or calculate the service URL based on the data source path parameters
GetServiceRootFromDataSourcePath = (dataSourcePath) as text => ...;

GetAuthorizationUrlFromWwwAuthenticate = (url as text) as text =>
    let
        // Sending an unauthenticated request to the service returns
        // a 302 status with WWW-Authenticate header in the response. The value will
        // contain the correct authorization_uri.
        // 
        // Example:
        // Bearer authorization_uri="https://login.microsoftonline.com/{tenant_guid}/oauth2/authorize"
        responseCodes = {302, 401},
        endpointResponse = Web.Contents(url, [
            ManualCredentials = true,
            ManualStatusHandling = responseCodes
        ])
    in
        if (List.Contains(responseCodes, Value.Metadata(endpointResponse)[Response.Status]?)) then
            let
                headers = Record.FieldOrDefault(Value.Metadata(endpointResponse), "Headers", []),
                wwwAuthenticate = Record.FieldOrDefault(headers, "WWW-Authenticate", ""),
                split = Text.Split(Text.Trim(wwwAuthenticate), " "),
                authorizationUri = List.First(List.Select(split, each Text.Contains(_, "authorization_uri=")), null)
            in
                if (authorizationUri <> null) then
                    // Trim and replace the double quotes inserted before the url
                    Text.Replace(Text.Trim(Text.Trim(Text.AfterDelimiter(authorizationUri, "=")), ","), """", "")
                else
                    error Error.Record("DataSource.Error", "Unexpected WWW-Authenticate header format or value during authentication."), [
                        #"WWW-Authenticate" = wwwAuthenticate
                    ])
        else
            error Error.Unexpected("Unexpected response from server during authentication."));

<... snip ...>

Authentication = [
    Aad = [
        AuthorizationUri = (dataSourcePath) =>
            GetAuthorizationUrlFromWwwAuthenticate(
                GetServiceRootFromDataSourcePath(dataSourcePath)
            ),
        Resource = "https://myAadResourceValue.com", // Azure AD resource value for your service - Guid or URL
    ]
]

Cesty zdroja údajov

Motor M identifikuje zdroj údajov pomocou kombinácie jeho druhu a cesty. Keď sa počas hodnotenia dotazu vyskytne zdroj údajov, motor M sa pokúsi nájsť zodpovedajúce poverenia. Ak sa nenašli žiadne poverenia, nástroj vráti špeciálnu chybu, ktorá má za následok výzvu na poverenie v doplnku Power Query.

Hodnota Kind pochádza z definície Druh zdroja údajov.

Hodnota Cesta je odvodená od požadovaných parametrov funkcie zdroja údajov. Voliteľné parametre sa nezaohľadní do identifikátora cesty zdroja údajov. V dôsledku toho musia mať všetky funkcie zdroja údajov priradené k druhu zdroja údajov rovnaké parametre. K dispozícii je špeciálne ovládanie funkcií, ktoré majú jeden parameter typu Uri.Type . Podrobnosti nájdete v časti nižšie.

Príklad ukladania poverení v dialógovom okne Nastavenia zdroja údajov v Power BI Desktop nájdete v dialógovom okne Nastavenia zdroja údajov. V tomto dialógovom okne je kind reprezentovaný ikonou a hodnota Cesta sa zobrazí ako text.

DataSourcePaths.

Poznámka

Ak počas vývoja zmeníte požadované parametre funkcie zdroja údajov, predtým uložené poverenia už nebudú fungovať (pretože hodnoty cesty sa už nezhodujú). Všetky uložené poverenia by ste mali odstrániť vždy, keď zmeníte parametre funkcie zdroja údajov. Ak sa nájdu nekompatibilné poverenia, môže sa zobraziť chyba v čase behu.

Formát cesty zdroja údajov

Hodnota Cesta pre zdroj údajov je odvodená z požadovaných parametrov funkcie zdroja údajov. Požadované parametre je možné vylúčiť z cesty pridaním DataSource.Path = false metadát funkcie(pozri nižšie).

Predvolene môžete zobraziť skutočnú hodnotu reťazca v dialógovom okne Nastavenia zdroja údajov v Power BI Desktop a v výzve na poverenie. Ak definícia Druh zdroja údajov zahŕňa Label hodnotu, namiesto toho sa zobrazí hodnota menovky.

Napríklad funkcia zdroja údajov vo vzorke HelloWorldWithDocs má nasledujúci podpis:

HelloWorldWithDocs.Contents = (message as text, optional count as number) as table => ...

Funkcia má jeden požadovaný parameter ( message ) typu a použije sa na výpočet text cesty zdroja údajov. Voliteľný parameter ( count ) by sa ignoroval. Cesta sa zobrazí

Výzva na poverenie:

DataSourceCredentials.

Používateľské rozhranie nastavenia zdroja údajov:

DataSourceSettings.

Keď je definovaná hodnota menovky, hodnota cesty zdroja údajov sa nezobrazí:

DataSourceLabel.

Poznámka

V súčasnosti odporúčame, aby ste nezahŕňali označenie zdroja údajov, ak vaša funkcia vyžaduje parametre, pretože používatelia nebudú môcť rozlišovať medzi rôznymi povereniami, ktoré zadali. Dúfame, že to v budúcnosti zlepšíme (to znamená, že umožníme dátovým konektorom zobraziť svoje vlastné cesty zdroja údajov).

Vylúčenie požadovaných parametrov z cesty zdroja údajov

Ak chcete, aby sa vyžadoval parameter funkcie, ale nemal byť zahrnutý ako súčasť cesty zdroja údajov, môžete DataSource.Path = false pridať do dokumentácie funkcie metaúdaje. Táto vlastnosť môže byť pridaná k jednému alebo viacerým parametrom vašej funkcie. Toto pole odstráni hodnotu z cesty zdroja údajov (čo znamená, že už nebude odovzdaná vašej TestConnection funkcii), takže by sa mala používať len pre parametre, ktoré nie sú potrebné na identifikáciu zdroja údajov alebo na rozlíšenie medzi povereniami používateľa.

Napríklad konektor vo vzorke HelloWorldWithDocs by vyžadoval rôzne poverenia pre rôzne message hodnoty. DataSource.Path = falsePridanie message k parametru ho odstráni z výpočtu cesty zdroja údajov, čím sa konektor stáva "singleton". Všetky hovory sa HelloWorldWithDocs.Contents považujú za rovnaký zdroj údajov a používateľ poskytne poverenia iba raz.

HelloWorldType = type function (
    message as (type text meta [
        DataSource.Path = false,
        Documentation.FieldCaption = "Message",
        Documentation.FieldDescription = "Text to display",
        Documentation.SampleValues = {"Hello world", "Hola mundo"}
    ]),
    optional count as (type number meta [
        Documentation.FieldCaption = "Count",
        Documentation.FieldDescription = "Number of times to repeat the message",
        Documentation.AllowedValues = { 1, 2, 3 }
    ]))
    as table meta [
        Documentation.Name = "Hello - Name",
        Documentation.LongDescription = "Hello - Long Description",
        Documentation.Examples = {[
            Description = "Returns a table with 'Hello world' repeated 2 times",
            Code = "HelloWorldWithDocs.Contents(""Hello world"", 2)",
            Result = "#table({""Column1""}, {{""Hello world""}, {""Hello world""}})"
        ],[
            Description = "Another example, new message, new count!",
            Code = "HelloWorldWithDocs.Contents(""Goodbye"", 1)",
            Result = "#table({""Column1""}, {{""Goodbye""}})"
        ]}
    ];

Funkcie s parametrom Uri

Keďže zdroje údajov s identifikátorom založeným na Uri sú také bežné, používateľské rozhranie Power Query je pri riešení ciest zdroja údajov založené na Uri špeciálne spracovanie. Keď sa vyskytne zdroj údajov založený na Uri, dialógové okno poverenia poskytuje rozbaľovaciu reláciu, ktorá umožňuje používateľovi vybrať základnú cestu, a nie úplnú cestu (a všetky cesty medzi nimi).

DataSourceUrl.

Rovnako ako Uri.Type pripísaný typ skôr než primitívny typ v jazyku M, budete musieť použiť funkciu Value.ReplaceType na označenie, že textový parameter by sa mal považovať za Uri.

shared GithubSample.Contents = Value.ReplaceType(Github.Contents, type function (url as Uri.Type) as any);

Ďalšie typy autentifikácie

Informácie o ďalších typoch overovania, na ktoré sa nevzťahuje tento článok, ako je napríklad jediné prihlásenie založené na protokole Kerberos, nájdete v článku o ďalších funkciách konektora a získajte ďalšie informácie.