Lue englanniksi

Jaa


Natiivi kyselyn tuki Power Queryn mukautetuissa liittimillä

Huomautus

Tässä artikkelissa käsitellään edistyneitä aiheita, jotka koskevat mukautettujen liittimien alkuperäisen kyselytuen toteutusta ja kyselyn delegointia lähteeseen. Tässä artikkelissa oletetaan, että sinulla on jo työtuntemusta näistä käsitteistä.

Jos haluat lisätietoja Power Queryn mukautetuista liittimista, siirry Power Query SDK:n yleiskatsaukseen.

Power Queryssa voit suorittaa tietolähteeseen mukautettuja alkuperäisiä kyselyitä etsimiesi tietojen noutamiseksi. Voit myös ottaa käyttöön ominaisuuden, joka säilyttää kyselyn delegoinnin lähteeseen tämän prosessin ajan ja power Queryn sisällä tehdyt myöhemmät muunnosprosessit.

Tämän artikkelin tavoitteena on esitellä, miten voit ottaa tällaisen ominaisuuden käyttöön mukautetussa liittimessäsi.

Edellytykset

Tässä artikkelissa käytetään lähtökohtana mallia, joka käyttää tietolähteelleen SQL ODBC -ohjainta. Alkuperäisen kyselyominaisuuden toteutusta tuetaan tällä hetkellä vain ODBC-yhdistimille, jotka noudattavat SQL-92-standardia.

Malliliitin käyttää SQL Server native Client 11.0 -ohjainta. Varmista, että sinulla on tämä ohjain asennettuna, jotta voit seurata tätä opetusohjelmaa.

Voit myös tarkastella malliliittimen valmista versiota GitHub-säilön Finish-kansiosta.

Liittimen SQLCapabilities-kapasiteetin muokkaaminen

SqlCapabilities Malliliittimen tietueesta löydät tietuekentän, jossa on nimi Sql92Translation ja sille määritetty arvo PassThrough. Tämä uusi kenttä on välttämätön, jotta alkuperäinen kysely voidaan välittää Power Queryn avulla ilman vahvistusta.

SqlCapabilities = Diagnostics.LogValue("SqlCapabilities_Options", defaultConfig[SqlCapabilities] & [
    // Place custom overrides here
    // The values below are required for the SQL Native Client ODBC driver, but might
    // not be required for your data source.
        SupportsTop = false,
        SupportsDerivedTable = true,
        Sql92Conformance = 8 /* SQL_SC_SQL92_FULL */,
        GroupByCapabilities = 4 /* SQL_GB_NO_RELATION */,
        FractionalSecondsScale = 3,
        Sql92Translation = "PassThrough"
]),

Varmista, että tämä kenttä näkyy liittimessäsi, ennen kuin jatkat eteenpäin. Jos toimintoa ei tueta, saat varoituksia ja virheitä myöhemmin, kun käytät ominaisuutta, jota ei tueta, koska yhdistin ei määritä sitä.

Luo liitintiedosto (muodossa .mez tai.pqx) ja lataa se Power BI Desktopiin manuaalista testausta varten ja kohteen määrittämiseksi alkuperäiselle kyselylle.

Testaa liittimesi alkuperäiset kyselytoiminnot manuaalisesti

Huomautus

Tässä artikkelissa käytetään AdventureWorks2019-mallitietokantaa. Voit kuitenkin seurata mitä tahansa valitsemaasi SQL Server -tietokantaa ja tehdä tarvittavat muutokset, kun valitset haluamasi tietokannan erityispiirteet.

Tässä artikkelissa otetaan käyttöön natiivikyselyn tuki siten, että käyttäjää pyydetään syöttämällä kolme arvoa:

  • Palvelimen nimi
  • Tietokannan nimi
  • Alkuperäinen kysely tietokantatasolla

Siirry nyt Power BI Desktopissa Nouda tiedot -kokemukseen ja etsi liitin nimellä SqlODBC Sample.

Screenshot of the connector found inside the get data experience of Power BI Desktop.

Anna liitinvalintaikkunassa palvelimen parametrit ja tietokannan nimi. Valitse sitten OK.

Screenshot of connector dialog with server and database as parameters.

Näkyviin tulee uusi siirtymistoimintoikkuna. Siirtymistoiminnossa voit tarkastella SQL-ohjaimen alkuperäistä siirtymistoimintoa, joka näyttää palvelimen hierarkkisen näkymän ja sen sisältämät tietokannat. Napsauta hiiren kakkospainikkeella AdventureWorks2019-tietokantaa ja valitse sitten Muunna tiedot.

Screenshot of the transform data option from the contextual menu inside the Navigator window.

Tämä valinta tuo sinut Power Query -editoriin ja esikatseluun siitä, mikä on käytännössä alkuperäisen kyselyn kohde, koska kaikki alkuperäiset kyselyt suoritetaan tietokantatasolla. Tarkista viimeisen vaiheen kaavarivi, jotta ymmärrät paremmin, miten liittimesi pitäisi siirtyä alkuperäisten kyselyjen kohteeseen ennen niiden suorittamista. Tässä tapauksessa kaavarivi näyttää seuraavat tiedot:

= Source{[Name="AdventureWorks2019",Kind="Database"]}[Data]

Lähde on edellisen vaiheen nimi, joka tässä tapauksessa on liittimesi julkaistu funktio, jonka parametrit välitetään. Luettelo ja sen sisällä oleva tietue vain auttavat siirtymään taulukon tietylle riville. Rivi määritetään tietueen ehdoilla. Kentän Nimen on oltava AdventureWorks2019 ja Laji-kentän on oltava sama kuin Tietokanta. Kun rivi on sijoitettu, [Data] luettelon {} ulkopuolella oleva Antaa Power Queryn käyttää Data-kentän sisällä olevaa arvoa, joka on tässä tapauksessa taulukko. Voit palata edelliseen vaiheeseen (Source), jotta ymmärrät paremmin tämän siirtymisen.

Screenshot of a table that shows the values and fields that were used for the navigation step.

Testaa alkuperäistä kyselyä

Kun kohde on nyt tunnistettu, luo mukautettu vaihe siirtymisvaiheen jälkeen valitsemalla fx-kuvake kaavariviltä.

Screenshot of the fx button inside the formula that's used to create a custom step.

Korvaa kaavarivin sisällä oleva kaava seuraavalla kaavalla ja valitse sitten Enter.

= Value.NativeQuery( AdventureWorks2019_Database, "SELECT TOP (1000) *
  FROM [Person].[Address]")

Kun otat tämän muutoksen käyttöön, kaavarivin alla pitäisi näkyä varoitus, jossa pyydetään lupaa suorittaa alkuperäinen kysely tietolähteessä.

Screenshot of the permission is required to run this native database query warning message.

Valitse Muokkaa käyttöoikeutta. Näyttöön tulee uusi Alkuperäinen tietokantakysely -valintaikkuna, joka yrittää varoittaa alkuperäisten kyselyiden suorittamismahdollisuuksista. Tässä tapauksessa tiedämme, että tämä SQL-lause on turvallinen, joten suorita komento valitsemalla Suorita .

Screenshot showing how to approve a native database query dialog.

Kun olet suorittanut kyselyn, kyselysi esikatselu tulee näkyviin Power Query -editoriin. Tämä esikatselu vahvistaa, että liitin pystyy suorittamaan alkuperäisiä kyselyitä.

Screenshot of the native query executed in initial connector development and testing.

Natiivin kyselylogiikan toteuttaminen liittimessä

Edellisistä osioista kerättyjen tietojen avulla tavoitteena on nyt kääntää nämä tiedot liittimesi koodiksi.

Voit tehdä tämän käännöksen lisäämällä uuden NativeQueryProperties-tietuekentän liittimen Julkaise-tietueeseen, joka tässä tapauksessa on SqlODBC.Publish tietue. Tietueella NativeQueryProperties on tärkeä rooli määritettäessä, miten liitin on vuorovaikutuksessa funktion Value.NativeQuery kanssa.

Uusi tietuekenttä koostuu kahdesta kentästä:

  • NavigationSteps: Tämä kenttä määrittää, miten liittimesi suorittaa tai käsittelee siirtymistoiminnot. Se sisältää luettelon tietueista, joissa on kuvattu vaiheet, joiden avulla voit siirtyä tiettyihin tietoihin, joita haluat kysellä -funktion Value.NativeQuery avulla. Se määrittää kussakin tietueessa, mitä parametreja tarvitaan tai mitä tarvitaan, jotta tällainen siirtyminen saavuttaa haluamasi kohteen.
  • DefaultOptions: Tämän kentän avulla määritetään, miten tietyt valinnaiset parametrit sisällytetään asetustietueisiin Value.NativeQuery tai lisätään niihin. Se tarjoaa joukon oletusasetuksia, joita voidaan käyttää tietolähdekyselyssä.

Siirtymisvaiheet voidaan luokitella kahteen ryhmään. Ensimmäinen sisältää käyttäjän syöttämät arvot, kuten palvelimen tai tietokannan nimen, tässä tapauksessa. Toinen sisältää arvot, jotka johdetaan tietyn liittimen toteutuksesta, kuten niiden kenttien nimi, joita käyttäjä ei näe Nouda tiedot -kokemuksen aikana. Näitä kenttiä voivat olla esimerkiksi Name, Kind, Dataja muita sen mukaan, miten liitin on toteutettu.

Tässä tapauksessa oli vain yksi siirtymisvaihe, joka koostui kahdesta kentästä:

  • Nimi: Tämä kenttä on sen tietokannan nimi, jonka loppukäyttäjä välitti. Tässä tapauksessa se oli AdventureWorks2019, mutta tämä kenttä tulee aina välittää sellaisenaan siitä, mitä loppukäyttäjä antoi tietojen noutamisen aikana.
  • Laji: Tämä kenttä on tieto, joka ei näy loppukäyttäjälle ja joka liittyy liittimen tai kuljettajan toteutukseen. Tässä tapauksessa tämä arvo tunnistaa, minkä tyyppistä objektia tulee käyttää. Tätä toteutusta varten tämä kenttä on kiinteä arvo, joka koostuu merkkijonosta Database.

Nämä tiedot käännetään seuraavaan koodiin. Tämä koodi tulee lisätä uutena kenttänä tietueeseen SqlODBC.Publish .

NativeQueryProperties = [
    NavigationSteps = {
        [
            Indices = {
                [
                    FieldDisplayName = "database",
                    IndexName = "Name"
                ],
                [
                    ConstantValue = "Database",
                    IndexName = "Kind"
                ]
            },
            FieldAccess = "Data"
        ]
    }
]

Tärkeä

Kenttien nimessä kirjainkoko on merkitsevä, ja sitä on käytettävä kuten yllä olevassa esimerkissä. Kaikki kenttiin välitetyt tiedot, joko ConstantValue, IndexNametai FieldDisplayName , on johdettava liittimen M-koodista.

Arvoille, jotka välitetään käyttäjän syöttämästä kohteesta, voit käyttää paria FieldDisplayName ja IndexName. Jos arvot ovat kiinteitä tai ennalta määritettyjä ja joita loppukäyttäjä ei voi välittää, voit käyttää paria ConstantValue ja IndexName. Tässä mielessä NavigationSteps-tietue sisältää kaksi kenttää:

  • Indeksit: Määrittää, mitä kenttiä ja mitä arvoja käytetään siirryessäsi tietueeseen, joka sisältää funktion Value.NativeQuery kohteen.
  • FieldAccess: Määrittää, mikä kenttä sisältää kohteen, joka on yleensä taulukko.

Oletusasetukset

- DefaultOptions kentän avulla voit välittää funktiolle Value.NativeQuery valinnaisia parametreja, kun käytät liittimesi alkuperäistä kyselytoimintoa.

Jos haluat säilyttää kyselyn delegoinnin lähteeseen alkuperäisen kyselyn jälkeen ja olettaen, että liittimessäsi on kyselyn delegointi lähteeseen -ominaisuudet, voit käyttää seuraavaa esimerkkikoodia parametrille EnableFolding = true.

NativeQueryProperties = [
    NavigationSteps = {
        [
            Indices = {
                [
                    FieldDisplayName = "database",
                    IndexName = "Name"
                ],
                [
                    ConstantValue = "Database",
                    IndexName = "Kind"
                ]
            },
            FieldAccess = "Data"
        ]
    },

    DefaultOptions = [
        EnableFolding = true
    ]
]

Kun nämä muutokset ovat käytössä, luo liitin ja lataa se Power BI Desktopiin testausta ja vahvistusta varten.

Liittimen testaaminen ja vahvistaminen

Käynnistä liitin Power BI Desktopissa uusi mukautettu liitin Nouda tiedot -toiminnosta. Kun käynnistät liittimen, huomaat, että valintaikkunassa on nyt pitkä tekstikenttä, jonka nimi on Native query , ja sulkeissa on tarvittavat kentät, joiden avulla se toimii. Anna samat arvot palvelimelle, tietokannalle ja SQL-lausekkeelle, jotka syötit aiemmin liittimen testauksen aikana.

Screenshot of the connector dialog with the native query long text field shown.

Kun olet valinnut OK, suoritettavan alkuperäisen kyselyn taulukon esikatselu näytetään uudessa valintaikkunassa.

Screenshot of the dialog with a table preview of the executed native query.

Valitse OK. Uusi kysely ladataan nyt Power Query -editoriin, jossa voit testata liitintä tarpeen mukaan.

Huomautus

Jos liittimessä on kyselyn delegointi lähteeseen -ominaisuuksia ja se on määritetty EnableFolding=true eksplisiittisesti osana valinnaista tietuetta lle Value.NativeQuery, voit edelleen testata liitintä Power Query -editorissa tarkistamalla, muuntuuko lisää lähteeseen vai ei.