Jaa kautta

Natiivikyselytuki Power Query -mukautetuissa liittimissä

Note

Tämä artikkeli käsittelee edistyneitä aiheita, jotka liittyvät natiivikyselytuen toteuttamiseen mukautetuille liittimille sekä kyselyjen taittoa niiden päälle. Tämä artikkeli olettaa, että sinulla on jo toimiva tieto näistä käsitteistä.

Lisätietoja Power Queryn mukautetuista liittimistä löydät osoitteesta Power Query SDK Overview.

Power Queryssä voit suorittaa mukautettuja natiivikyselyitä tietolähteellesi hakeaksesi etsimäsi tiedot. Voit myös mahdollistaa kyselyjen taittomisen tämän prosessin aikana ja myöhemmät muunnosprosessit, jotka tehdään Power Queryn sisällä.

Tämän artikkelin tavoitteena on osoittaa, miten voit toteuttaa tällaisen ominaisuuden omaan liittimeesi.

edellytykset

Tässä artikkelissa käytetään lähtökohtana esimerkkiä , joka käyttää SQL ODBC -ajuria tietolähteenä. Natiivikyselyominaisuuden toteutus on tällä hetkellä tuettu vain ODBC-liittimille, jotka noudattavat SQL-92-standardia.

Esimerkkiliitin käyttää SQL Server Native Client 11.0 -ajuria. Varmista, että sinulla on tämä ajuri asennettuna, jotta voit seurata tätä opetusta.

Voit myös katsoa valmiin version sample-liittimestä Finish-kansiosta GitHub Repositoryssa.

Muokkaa liittimen SQLCapability-ominaisuuksia

Näyteliittimen SqlCapabilities tietueesta löytyy tietuekenttä, jossa on nimi Sql92Translation ja arvo PassThrough . Tämä uusi kenttä on välttämätön, jotta natiivikysely voidaan välittää Power Queryllä ilman validointia.

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 et, kohtaat myöhemmin varoituksia ja virheitä, kun kyse on kyvyn käytöstä, jota ei tueta, koska liitin ei ole ilmoittanut sitä.

Rakenna liitintiedosto (muodossa .mez tai .pqx) ja lataa se Power BI Desktopiin manuaalista testausta varten ja määrittämään kohde natiivikyselyllesi.

Testaa liittimesi natiivikyselyominaisuudet manuaalisesti

Note

Tässä artikkelissa käytämme AdventureWorks2019-esimerkkitietokantaa. Voit kuitenkin seurata mitä tahansa SQL Server -tietokantaa ja tehdä tarvittavat muutokset, kun kyse on valitun tietokannan yksityiskohdista.

Tässä artikkelissa natiivikyselytuki toteutetaan siten, että käyttäjää pyydetään syöttämään kolme arvoa:

  • Palvelimen nimi
  • Tietokannan nimi
  • Natiivikysely tietokantatasolla

Nyt Power BI Desktopin sisällä mene Get Data -kokemukseen ja etsi liitin nimeltä SqlODBC Sample.

Kuvakaappaus liittimestä, joka löytyy Power BI Desktopin get data experiencesta.

Liittimen valintaan syötä palvelimen parametrit ja tietokantasi nimi. Valitse sitten OK.

Kuvakaappaus liittimen dialogista, jossa palvelin ja tietokanta ovat parametreja.

Uusi navigaattorin ikkuna ilmestyy. Navigatorissa voit tarkastella natiivin navigointikäyttäytymisen SQL-ajurista, joka näyttää palvelimen hierarkkisen näkymän ja sen sisällä olevat tietokannat. Napsauta hiiren oikealla AdventureWorks2019-tietokantaa ja valitse sitten Muunna data.

Kuvakaappaus muunnosdatavaihtoehdosta Navigaattori-ikkunan kontekstivalikosta.

Tämä valinta vie sinut Power Query -editoriin ja esikatseluun siitä, mikä käytännössä on natiivikyselysi kohde, koska kaikkien natiivikyselyjen tulisi suorittaa tietokantatasolla. Tarkista viimeisen vaiheen kaavapalkki ymmärtääksesi paremmin, miten liittimesi tulisi navigoida natiivikyselyidesi kohteeseen ennen niiden suorittamista. Tässä tapauksessa kaavapalkki näyttää seuraavat tiedot:

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

Lähde on edellisen vaiheen nimi, joka tässä tapauksessa on yksinkertaisesti liittimen julkaistu funktio, jossa parametrit on ohitettu. Lista ja sen sisällä oleva tietue auttavat vain taulun navigointia tiettyyn riviin. Rivi määritellään tietueen kriteereillä, joissa kentän Nimi on oltava yhtä suuri kuin AdventureWorks2019 ja Lajikkeen on oltava yhtä suuri kuin Tietokanta. Kun rivi on löydetty, listan {} ulkoreuna [Data] antaa Power Querylle pääsyn data-kentän sisällä olevaan arvoon, joka tässä tapauksessa on taulu. Voit palata edelliseen vaiheeseen (Lähde) ymmärtääksesi tätä navigointia paremmin.

Kuvakaappaus taulukosta, joka näyttää navigointivaiheessa käytetyt arvot ja kentät.

Testin natiivikysely

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

Kuvakaappaus fx-painikkeesta kaavan sisällä, jota käytetään mukautetun vaiheen luomiseen.

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

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

Kun olet tehnyt tämän muutoksen, kaavapalkin alle pitäisi ilmestyä varoitus, joka pyytää lupaa ajaa natiivikysely tietolähteellesi.

Tämän natiivin tietokantakyselyvaroitusviestin suorittamiseen vaaditaan käyttöoikeuden kuvakaappaus.

Valitse Muokkauslupa. Uusi Native Database Query -valintaikkuna ilmestyy, joka yrittää varoittaa sinua natiivikyselyjen mahdollisuuksista. Tässä tapauksessa tiedämme, että tämä SQL-lause on turvallinen, joten valitse Käynnistä suorittaaksesi komennon.

Kuvakaappaus, joka näyttää, miten natiivi tietokantakysely hyväksytään.

Kun olet suorittanut kyselysi, Power Query -editorissa näkyy esikatselu kyselystäsi. Tämä esikatselu vahvistaa, että liittimesi pystyy ajamaan natiivikyselyitä.

Kuvakaappaus alkuperäisestä yhteydenotosta, joka suoritettiin liittimen alkuperäisessä kehityksessä ja testauksessa.

Toteuta natiivikyselylogiikka liittimessäsi

Aiemmista osioista kerätyillä tiedoilla tavoitteena on nyt muuntaa nämä tiedot koodiksi liittimellesi.

Tämän käännöksen voi toteuttaa lisäämällä uuden NativeQueryProperties-tietueen liittimesi Julkaisu-tietueen, joka tässä tapauksessa on tietueSqlODBC.Publish. Tietueella NativeQueryProperties on ratkaiseva rooli siinä, miten liitin vuorovaikuttaa Value.NativeQuery funktion kanssa.

Uusi ennätyskenttä koostuu kahdesta kentästä:

  • NavigationSteps: Tämä kenttä määrittelee, miten navigointi tulee suorittaa tai käsitellä liittimelläsi. Se sisältää listan tietueista, jotka kuvaavat vaiheet, miten navigoidaan tiettyyn dataan, jota haluat haettavaksi funktion Value.NativeQuery avulla. Jokaisessa tietueessa määritellään, mitkä parametrit vaaditaan tai tarvitaan, jotta navigointi saavuttaa halutun kohteen.
  • DefaultOptions: Tämä kenttä auttaa tunnistamaan, miten tietyt valinnaiset parametrit tulisi sisällyttää tai lisätä asetuksiin Value.NativeQuery . Se tarjoaa joukon oletusasetuksia, joita voi käyttää tietolähteen kyselyissä.

Navigointivaiheesi voidaan jakaa kahteen ryhmään. Ensimmäinen sisältää ne arvot, jotka loppukäyttäjä syöttää, kuten palvelimen nimen tai tietokannan, tässä tapauksessa. Toinen sisältää ne arvot, jotka tietyn liittimen toteutuksen perusteella johdetaan, kuten kenttien nimet, joita käyttäjä ei näy hakudatan aikana. Näihin kenttiin voi kuulua Name, Kind, Data, ja muita riippuen liittimen toteutuksesta.

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

  • Nimi: Tämä kenttä on tietokannan nimi, jonka loppukäyttäjä on välittänyt. Tässä tapauksessa se oli AdventureWorks2019, mutta tämä kenttä tulisi aina välittää as-is siitä, mitä loppukäyttäjä syötti tiedonhakukokemuksen aikana.
  • Laji: Tämä kenttä on tietoa, jota loppukäyttäjä ei näe ja joka on sidottu liittimen tai ajurin toteutukseen. Tässä tapauksessa tämä arvo kertoo, minkälaista objektia tulisi käyttää. Tässä toteutuksessa tämä kenttä on kiinteä arvo, joka koostuu merkkijonosta Database.

Tällaiset tiedot käännetään seuraavaan koodiin. Tämä koodi tulisi lisätä uutena kenttänä tietueseesi SqlODBC.Publish .

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

Tärkeää

Kenttien nimet ovat kirjainkoon herkkiä ja niitä on käytettävä yllä olevan esimerkin mukaisesti. Kaikki kentille välitetty tieto, joko ConstantValue, IndexName, tai FieldDisplayName on johdettava liittimen M-koodista.

Arvoille, jotka välitetään käyttäjän syöttämästä, voit käyttää paria FieldDisplayName ja IndexName. Arvoille, jotka ovat kiinteitä tai ennalta määriteltyjä eivätkä loppukäyttäjä voi välittää niitä, voit käyttää paria ConstantValue ja IndexName. Tässä mielessä NavigationSteps-tietue koostuu kahdesta kentästä:

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

DefaultOptions

Kenttä DefaultOptions antaa mahdollisuuden välittää valinnaisia parametreja Value.NativeQuery funktioon, kun käytät liittimen natiivikyselyominaisuutta.

Jotta kyselyn taittaminen säilyy natiivikyselyn jälkeen ja olettaen, että liittimelläsi on kyselyn taittokyky, voit käyttää seuraavaa esimerkkikoodia .EnableFolding = true

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

    DefaultOptions = [
        EnableFolding = true
    ]
]

Kun nämä muutokset on tehty, rakenna liitin ja lataa se Power BI Desktopiin testattavaksi ja validoitavaksi.

Testaa ja validoi liitin

Power BI Desktopissa, kun uusi mukautettu liitin on paikallaan, käynnistä liitin Get Data -kokemuksesta. Kun käynnistät liittimen, huomaat, että valintaikkunassa on nyt pitkä tekstikenttä nimellä Native query ja sulkeissa on tarvittavat kentät, jotta se toimii. Syötä samat arvot palvelimelle, tietokannalle ja SQL-lauseelle, jotka aiemmin syötit liitintä testatessasi.

Kuvakaappaus liittimen dialogista, jossa natiivi kysely pitkä tekstikenttä näkyy.

Kun valitset OK:n, uudessa valikossa näytetään suoritetun natiivikyselyn esikatselu taulun esikatselusta.

Kuvakaappaus dialogista, jossa on tauluesikatselu suoritetusta natiivikyselystä.

Valitse OK. Uusi kysely latautuu nyt Power Query -editoriin, jossa voit tarvittaessa testata liitintäsi lisää.

Note

Jos liittimelläsi on kyselyn taittokyky ja se on nimenomaisesti EnableFolding=true määritelty osaksi valinnaista tietuetta , Value.NativeQueryvoit testata liitintä Power Query -editorissa tarkistamalla, taitetaanko lisämuunnokset takaisin lähteeseen vai eivät.

  • Last updated on