İngilizce dilinde oku

Aracılığıyla paylaş


Power Query özel bağlayıcılarında yerel sorgu desteği

Not

Bu makale, özel bağlayıcılar için yerel sorgu desteğinin uygulanması ve bunların üzerine sorguyu katlama ile ilgili gelişmiş konuları kapsar. Bu makalede, bu kavramlar hakkında zaten çalışan bir bilginiz olduğu varsayılır.

Power Query özel bağlayıcıları hakkında daha fazla bilgi edinmek için Power Query SDK'sına Genel Bakış'a gidin.

Power Query'de, aradığınız verileri almak için veri kaynağınızda özel yerel sorgular yürütebilirsiniz. Ayrıca, bu işlem boyunca sorguyu kaynağa döndürmeyi ve Power Query'nin içinde yapılan sonraki dönüştürme işlemlerini sürdürme özelliğini etkinleştirebilirsiniz.

Bu makalenin amacı, özel bağlayıcınız için bu özelliği nasıl uygulayabileceğinizi göstermektir.

Önkoşullar

Bu makalede, veri kaynağı için SQL ODBC sürücüsünü kullanan bir örnek başlangıç noktası olarak kullanılır. Yerel sorgu özelliğinin uygulanması şu anda yalnızca SQL-92 standardına uygun ODBC bağlayıcıları için desteklenmektedir.

Örnek bağlayıcı SQL Server Native Client 11.0 sürücüsünü kullanır. Bu öğreticiyi takip etmek için bu sürücünün yüklü olduğundan emin olun.

Örnek bağlayıcının tamamlanmış sürümünü GitHub Deposu'ndaki Son klasöründen de görüntüleyebilirsiniz.

Bağlayıcınızın SQLCapabilities değerini değiştirme

Örnek bağlayıcının SqlCapabilities kaydında adı ve PassThrough değerini içeren bir kayıt alanı Sql92Translation bulabilirsiniz. Bu yeni alan, yerel sorgunun herhangi bir doğrulama olmadan Power Query kullanılarak geçirilmesi için gereklidir.

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"
]),

Devam etmeden önce bu alanın bağlayıcınızda göründüğüne emin olun. Aksi takdirde, bağlayıcı tarafından bildirilmediğinden desteklenmeyen bir özelliği kullanmaya geldiğinde daha sonra uyarılarla ve hatalarla karşılaşırsınız.

Bağlayıcı dosyasını (.mez veya.pqx olarak) derleyin ve el ile test etmek ve yerel sorgunuzun hedefini tanımlamak için Power BI Desktop'a yükleyin.

Bağlayıcınızın yerel sorgu özelliklerini el ile test edin

Not

Bu makale için AdventureWorks2019 örnek veritabanını kullanacağız. Ancak, seçtiğiniz herhangi bir SQL Server veritabanıyla birlikte ilerleyebilir ve seçilen veritabanının ayrıntılarına indiğinde gerekli değişiklikleri yapabilirsiniz.

Bu makalede yerel sorgu desteğinin uygulanması için kullanıcının üç değer girmesi istenecektir:

  • Sunucu adı
  • Veritabanı adı
  • Veritabanı düzeyinde yerel sorgu

Şimdi Power BI Desktop'ta Veri Al deneyimine gidin ve SqlODBC Örneği adlı bağlayıcıyı bulun.

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

Bağlayıcı iletişim kutusu için sunucunuzun parametrelerini ve veritabanınızın adını girin. Ardından Tamam'ı seçin.

Screenshot of connector dialog with server and database as parameters.

Yeni bir gezgin penceresi görüntülenir. Gezgin'de sql sürücüsünden sunucunun ve içindeki veritabanlarının hiyerarşik görünümünü görüntüleyen yerel gezinti davranışını görüntüleyebilirsiniz. AdventureWorks2019 veritabanına sağ tıklayın ve Verileri Dönüştür'ü seçin.

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

Bu seçim sizi Power Query düzenleyicisine getirir ve tüm yerel sorguların veritabanı düzeyinde çalışması gerektiğinden yerel sorgunuzun hedefinin etkili bir şekilde önizlemesini sağlar. Bağlayıcınızı yürütmeden önce yerel sorgularınızın hedefine nasıl gidilmesi gerektiğini daha iyi anlamak için son adımın formül çubuğunu inceleyin. Bu durumda formül çubuğunda aşağıdaki bilgiler görüntülenir:

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

Kaynak , önceki adımın adıdır ve bu örnekte, geçirilen parametrelerle bağlayıcınızın yayımlanmış işlevidir. Liste ve içindeki kayıt, bir tabloda belirli bir satıra gitmenize yardımcı olur. Satır, Ad alanının AdventureWorks2019 ve Kind alanının da Database'e eşit olması gereken kayıt ölçütlerine göre tanımlanır. Satır bulunduktan sonra, listenin [Data]{} dışı Power Query'nin Veri alanının içindeki değere erişmesine olanak tanır ve bu durumda tablodur. Bu gezintiyi daha iyi anlamak için önceki adıma (Kaynak) dönebilirsiniz.

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

Yerel sorguyu test et

Hedef belirlendikten sonra, formül çubuğunda fx simgesini seçerek gezinti adımından sonra özel bir adım oluşturun.

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

Formül çubuğunun içindeki formülü aşağıdaki formülle değiştirin ve enter tuşuna basın.

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

Bu değişikliği uyguladıktan sonra, veri kaynağınızda yerel sorguyu çalıştırma izni isteyen formül çubuğunun altında bir uyarı görüntülenmelidir.

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

İzni Düzenle'yi seçin. Yerel sorgu çalıştırma olasılıkları hakkında sizi uyarmaya çalışan yeni bir Yerel Veritabanı Sorgusu iletişim kutusu görüntülenir. Bu durumda, bu SQL Deyiminin güvenli olduğunu biliyoruz, bu nedenle komutunu yürütmek için Çalıştır'ı seçin.

Screenshot showing how to approve a native database query dialog.

Sorgunuzu çalıştırdıktan sonra Power Query düzenleyicisinde sorgunuzun önizlemesi görüntülenir. Bu önizleme, bağlayıcınızın yerel sorgu çalıştırabildiğini doğrular.

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

Bağlayıcınıza yerel sorgu mantığı uygulama

Önceki bölümlerden toplanan bilgilerle, şimdi amaç bu bilgileri bağlayıcınız için koda çevirmektir.

Bu çeviriyi gerçekleştirmenin yolu, bağlayıcınızın Yayımla kaydına yeni bir NativeQueryProperties kayıt alanı eklemektir. Bu durumda kayıt budurSqlODBC.Publish. Kayıt, NativeQueryProperties bağlayıcının işlevle Value.NativeQuery nasıl etkileşim kuracağını tanımlamada önemli bir rol oynar.

Yeni kayıt alanı iki alandan oluşur:

  • NavigationSteps: Bu alan, gezintinin bağlayıcınız tarafından nasıl gerçekleştirilmesi veya işlenmesi gerektiğini tanımlar. İşlevi kullanarak sorgulamak istediğiniz belirli verilere gitmek için adımları özetleyen kayıtların Value.NativeQuery listesini içerir. Her kayıtta, bu gezintinin istediğiniz hedefe ulaşması için hangi parametrelerin gerekli olduğunu veya gerekli olduğunu tanımlar.
  • DefaultOptions: Bu alan, belirli isteğe bağlı parametrelerin seçenekler kaydına nasıl eklenmesi veya eklenmesi gerektiğini belirlemeye Value.NativeQuery yardımcı olur. Veri kaynağını sorgularken kullanılabilecek bir dizi varsayılan seçenek sağlar.

Gezinti adımlarınız iki gruba ayrılmış olabilir. İlki, son kullanıcı tarafından girilen sunucu veya veritabanının adı gibi değerleri içerir. Bu durumda. İkincisi, veri alma deneyimi sırasında kullanıcıya görüntülenmeyen alanların adı gibi belirli bağlayıcı uygulaması tarafından türetilen değerleri içerir. Bu alanlar, bağlayıcı uygulamanıza bağlı olarak , Kind, Datave diğer alanları içerebilirName.

Bu durumda, iki alandan oluşan yalnızca bir gezinti adımı vardı:

  • Ad: Bu alan, son kullanıcı tarafından geçirilen veritabanının adıdır. Bu durumda , AdventureWorks2019ancak bu alan her zaman veri alma deneyimi sırasında son kullanıcının girdiği şekilde geçirilmelidir.
  • Tür: Bu alan, son kullanıcı tarafından görülmeyecek ve bağlayıcı veya sürücü uygulamasına özgü bilgilerdir. Bu durumda, bu değer hangi nesne türüne erişilmesi gerektiğini tanımlar. Bu uygulama için, bu alan dizesini Databaseiçeren sabit bir değer olacaktır.

Bu bilgiler aşağıdaki koda çevrilir. Bu kod kaydınıza SqlODBC.Publish yeni bir alan olarak eklenmelidir.

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

Önemli

Alanların adı büyük/küçük harfe duyarlıdır ve yukarıdaki örnekte gösterildiği gibi kullanılmalıdır. , veya FieldDisplayName alanlarına ConstantValueIndexNamegeçirilen tüm bilgiler bağlayıcının M kodundan türetilmelidir.

Kullanıcının girdiği değerlerden geçirilecek değerler için ve IndexNameçiftini FieldDisplayName kullanabilirsiniz. Sabit veya önceden tanımlanmış ve son kullanıcı tarafından geçirilmeyecek değerler için ve IndexNameçiftini ConstantValue kullanabilirsiniz. Bu anlamda NavigationSteps kaydı iki alandan oluşur:

  • Dizinler: İşlevin hedefini içeren kayda gitmek için Value.NativeQuery hangi alanların ve hangi değerlerin kullanılacağını tanımlar.
  • FieldAccess: Hedefi tutan alanı tanımlar ve bu genellikle bir tablodur.

DefaultOptions

alanı, DefaultOptions bağlayıcınız için yerel sorgu özelliğini kullanırken isteğe bağlı parametreleri Value.NativeQuery işleve geçirmenizi sağlar.

Yerel sorgudan sonra sorguyu kaynağa döndürmeyi korumak ve bağlayıcınızın sorgu katlama özelliklerine sahip olduğunu varsayarsak, için EnableFolding = trueaşağıdaki örnek kodu kullanabilirsiniz.

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

    DefaultOptions = [
        EnableFolding = true
    ]
]

Bu değişiklikler gerçekleştiğinde bağlayıcıyı derleyin ve test ve doğrulama için Power BI Desktop'a yükleyin.

Bağlayıcıyı test edin ve doğrulayın

Yeni özel bağlayıcınız hazır durumda olan Power BI Desktop'ta Veri Al deneyiminden bağlayıcıyı başlatın. Bağlayıcıyı başlatırken, iletişim kutusunun artık Yerel sorgu adlı uzun bir metin alanına sahip olduğunu ve parantez içinde çalışması için gerekli alanlara sahip olduğunu fark edeceksiniz. Bağlayıcıyı test ederken daha önce girdiğiniz sunucu, veritabanı ve SQL deyimi için aynı değerleri girin.

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

Tamam'ı seçtikten sonra, yürütülen yerel sorgunun tablo önizlemesi yeni bir iletişim kutusunda gösterilir.

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

Tamam seçeneğini işaretleyin. Artık bağlayıcınızın daha fazla testini gerektiği gibi yapabileceğiniz Power Query düzenleyicisinin içine yeni bir sorgu yüklenir.

Not

Bağlayıcınızın sorgu katlama özellikleri varsa ve için isteğe bağlı kaydın Value.NativeQuerybir parçası olarak açıkça tanımladıysaEnableFolding=true, daha fazla dönüştürmenin kaynağa geri katlanıp katlanmadığını denetleyerek bağlayıcınızı Power Query düzenleyicisinde daha fazla test edebilirsiniz.