Power BI’ı uygulamalara taşımak: gömme, REST API, otomasyon ve özel görseller

Buraya kadar raporlar Power BI Service’te yaşadı. Ama Anadolu Market’in iki yeni isteği var: bayiler kendi satışlarını Anadolu Market’in bayi portalında görsün (bayilerin Power BI hesabı yok), ve BT ekibi her gece yüzlerce yenilemeyi elle değil, kodla yönetsin. Bu ders bir BI geliştiricisinin “rapor yazmanın ötesindeki” araç kutusudur.

İki gömme senaryosu

Learn, Premium P SKU’larının satıştan kaldırıldığını ve yeni projelerde Fabric F SKU’larının düşünülmesini öneriyor. Kodsuz bir seçenek de var: Power Pages raporu kod yazmadan gömebilir.

Hizmet sorumlusu ve gömme belirteci

Müşteriler için gömmede akış şöyledir:

1. Microsoft Entra’da bir uygulama kaydı oluşturulur; bu uygulamanın kimliği hizmet sorumlusudur (service principal). Bir Power BI yöneticisi kiracı ayarlarında “Hizmet sorumlularının Power BI API’lerini kullanmasına izin ver” seçeneğini açar ve sorumluyu izinli gruba ekler. Sorumlu, çalışma alanına Üye ya da Yönetici olarak eklenir.
2. Uygulamanın sunucu tarafı, sorumlunun gizli anahtarı ya da sertifikasıyla Entra’dan bir erişim belirteci alır.
3. Bu belirteçle Power BI REST API’den rapor için bir gömme belirteci (embed token) ister.
4. Tarayıcıdaki sayfa, gömme belirteciyle raporu bir iframe içinde açar.

Ana kullanıcı (master user) hesabıyla da gömme yapılabilir, ama Learn üretim için hizmet sorumlusunu öneriyor: daha güvenli, otomasyona daha uygun ve sayfalandırılmış raporları da destekliyor.

POST https://api.powerbi.com/v1.0/myorg/GenerateToken
Authorization: Bearer {sorumlunun-erişim-belirteci}
Content-Type: application/json

{
  "reports":  [ { "id": "{raporId}" } ],
  "datasets": [ { "id": "{modelId}" } ],
  "identities": [
    {
      "username": "bayi-izmir-07",
      "roles":    [ "BayiRolu" ],
      "datasets": [ "{modelId}" ]
    }
  ]
}

Gömülü RLS: etkin kimlik

Bayiler Power BI’da oturum açmadığı için Power BI onların kim olduğunu bilmez. Bunu uygulama söyler: gömme belirteci isterken etkin kimlik (effective identity) gönderir. Yukarıdaki istekte username, modeldeki dinamik rolde USERNAME() ya da USERPRINCIPALNAME() fonksiyonunun döndüreceği değerdir; roles uygulanacak rol, datasets modeldir.

Dinamik RLS’nin model tarafı “Satır ve nesne düzeyinde güvenlik” dersinde anlatıldı. Aynı mantığı bir ölçüyle deneyebilirsin. Bu uygulamada USERPRINCIPALNAME() sabit bir test kullanıcısı döndürür (ayse.kaya@anadolumarket.com). Küçük bir yetki tablosu, bu kullanıcının Ege ve Akdeniz bölgelerini görmesini söylüyor:

Benim Bölgelerim Satışı =
VAR Yetkiler =
    DATATABLE(
        "Eposta", STRING, "Bolge", STRING,
        {
            {"ayse.kaya@anadolumarket.com", "Ege"},
            {"ayse.kaya@anadolumarket.com", "Akdeniz"},
            {"selim.aksoy@anadolumarket.com", "Marmara"}
        }
    )
VAR Bolgelerim =
    SELECTCOLUMNS(FILTER(Yetkiler, [Eposta] = USERPRINCIPALNAME()), "Bolge", [Bolge])
RETURN
    CALCULATE([Net Satış], TREATAS(Bolgelerim, Musteriler[Bolge]))

Sonuç 310.138 ₺: Ege (146.768 ₺) ile Akdeniz (163.370 ₺) toplamı. Gömülü senaryoda username alanına “bayi-izmir-07” gönderilseydi, aynı fonksiyon o değeri döndürür ve yetki tablosunda o bayinin satırı aranırdı.

Tarayıcı tarafı: istemci API’si

Sayfada gömme için powerbi-client JavaScript/TypeScript kitaplığı kullanılır. Bu kitaplıkla sayfalar arasında gezinme, filtre ve dilimleyici ayarlama, yer işaretleri ve olaylara (yüklendi, veri noktası seçildi) tepki verebilirsin. Learn’deki Power BI Embedded Analytics Playground denemek için örnek içerik sunar.

import * as pbi from "powerbi-client";

const ayar: pbi.IEmbedConfiguration = {
  type: "report",
  id: raporId,
  embedUrl: gommeAdresi,
  accessToken: gommeBelirteci,            // sunucudan gelen embed token
  tokenType: pbi.models.TokenType.Embed,
  settings: { panes: { filters: { visible: false } } }
};

const servis = new pbi.service.Service(
  pbi.factories.hpmFactory, pbi.factories.wpmpFactory, pbi.factories.routerFactory);

const rapor = servis.embed(document.getElementById("rapor-alani")!, ayar);
rapor.on("loaded", () => console.log("Rapor yüklendi"));

Gömme belirtecinin süresi dolar; uygulama süre bitmeden yenisini isteyip setAccessToken ile raporu kesintisiz sürdürmelidir.

REST API ile otomasyon

Power BI REST API (api.powerbi.com/v1.0/myorg) ve Fabric REST API (api.fabric.microsoft.com/v1), Service’te elle yaptığın işlerin çoğunu kodla yapmanı sağlar. Sık kullanılanlar:

// 1) Anlam modelini yenile (202 Accepted döner)
POST https://api.powerbi.com/v1.0/myorg/groups/{calismaAlaniId}/datasets/{modelId}/refreshes
{ "notifyOption": "MailOnFailure", "retryCount": 3 }

// 2) Yenileme geçmişini oku (durum takibi)
GET  https://api.powerbi.com/v1.0/myorg/groups/{calismaAlaniId}/datasets/{modelId}/refreshes?$top=10

// 3) Çalışma alanlarını listele (Fabric REST API)
GET  https://api.fabric.microsoft.com/v1/workspaces

// 4) Raporu PDF olarak dışa aktar: başlat, durumu sorgula, dosyayı al
POST https://api.powerbi.com/v1.0/myorg/groups/{calismaAlaniId}/reports/{raporId}/ExportTo
{ "format": "PDF" }

// 5) Bir Fabric işlem hattını isteğe bağlı çalıştır
POST https://api.fabric.microsoft.com/v1/workspaces/{calismaAlaniId}/items/{ogeId}/jobs/instances?jobType=Pipeline

• Yenileme API’si Dataset.ReadWrite.All kapsamı ister. Paylaşılan kapasitede günde en fazla 8 yenileme isteği yapılır (zamanlanmışlar dâhil) ve gövdede yalnızca notifyOption verilebilir. Kapasitede ise tablo ya da bölüm seçen gelişmiş yenileme yapılabilir; o zaman notifyOption gönderilmez.
• notifyOption, hizmet sorumlusuyla yapılan çağrılarda geçerli değildir; hata bildirimini kendin kurmalısın.
• Her çağrıda Authorization: Bearer … başlığı gerekir.

Yenileme geçmişinden gelen kayıtlar bir izleme raporuna dönüşebilir. Aşağıdaki sorgu küçük bir geçmiş tablosundan başarı oranı ve ortalama süre üretir; gerçek projede bu tablo API’den bir not defteriyle doldurulur:

EVALUATE
VAR Gecmis =
    DATATABLE(
        "Model", STRING, "Durum", STRING, "Dakika", INTEGER,
        {
            {"Satış", "Completed", 12}, {"Satış", "Completed", 14}, {"Satış", "Failed", 3},
            {"Stok", "Completed", 25}, {"Stok", "Completed", 31},
            {"Web", "Failed", 1}, {"Web", "Completed", 6}, {"Web", "Completed", 5}
        }
    )
VAR Basarili = FILTER(Gecmis, [Durum] = "Completed")
RETURN
    ROW(
        "Deneme", COUNTROWS(Gecmis),
        "Başarılı", COUNTROWS(Basarili),
        "Başarı %", DIVIDE(COUNTROWS(Basarili), COUNTROWS(Gecmis)),
        "Ort. süre (dk)", AVERAGEX(Basarili, [Dakika])
    )

Sonuç: 8 denemenin 6’sı başarılı (%75), başarılı yenilemeler ortalama 15,5 dakika.

PowerShell ile yönetim

Yöneticiler için MicrosoftPowerBIMgmt modülü var. Windows PowerShell 3.0 ve üzeri ile PowerShell 6 ve üzeri sürümlerde çalışır. Learn, kimlik doğrulama değişikliği nedeniyle 1.3.84 ya da daha yeni bir sürüm kullanılmasını söylüyor.

Install-Module -Name MicrosoftPowerBIMgmt
Connect-PowerBIServiceAccount

# Kuruluştaki tüm çalışma alanları (yönetici yetkisi gerekir)
Get-PowerBIWorkspace -Scope Organization -All

# Bir raporu .pbix olarak indir
Export-PowerBIReport -Id {raporId} -OutFile .SatisRaporu.pbix

# Cmdlet’i olmayan bir uç noktayı çağır
Invoke-PowerBIRestMethod -Url "groups/{calismaAlaniId}/datasets/{modelId}/refreshes" -Method Post -Body '{"notifyOption":"NoNotification"}'

Not defterinden modele: semantic link

Semantic link (SemPy), Fabric not defterinden anlam modeline Python ile erişmeyi sağlar. Spark 3.4 ve üzeri varsayılan çalışma ortamında hazır yüklüdür. Veri bilimci, ölçüleri kendisi yeniden yazmak yerine modeldeki [Net Satış] tanımını kullanır; böylece rapor ve model aynı sayıyı verir.

import sempy.fabric as fabric

fabric.list_datasets()                               # çalışma alanındaki modeller
fabric.list_measures("Anadolu Market Satış")         # modeldeki ölçüler

# Ölçüyü kategori ve yıla göre hesapla, pandas benzeri tablo al
df = fabric.evaluate_measure("Anadolu Market Satış", "Net Satış",
                             ["Urunler[Kategori]", "Tarih[Yil]"])

# Doğrudan DAX sorgusu
df2 = fabric.evaluate_dax("Anadolu Market Satış",
    "EVALUATE SUMMARIZECOLUMNS(Tarih[Yil], \"Net Satış\", [Net Satış])")

Sık kullanım: model kalitesini otomatik denetlemek (açıklaması olmayan ölçüler, kullanılmayan sütunlar), tahmin sonuçlarını to_lakehouse_table ile lakehouse’a yazıp modele geri vermek.

Özel görsel geliştirmek

Hazır görseller ve AppSource yetmiyorsa kendi görselini yazabilirsin. Özel görsel, Power BI görsel API’sini kullanan bir TypeScript projesidir; çizim için çoğu zaman D3 kullanılır.

npm i -g powerbi-visuals-tools@latest   # pbiviz komut satırı aracı
pbiviz new MagazaIsiHaritasi            # proje iskeleti: capabilities.json, pbiviz.json, src/visual.ts
cd MagazaIsiHaritasi
pbiviz start                            # yerelde çalıştır, geliştirici görseliyle canlı izle
pbiviz package                          # dist/ altında .pbiviz paketi üret

• capabilities.json: görselin alan kutuları (veri rolleri), veri eşlemesi ve biçim seçenekleri.
• pbiviz.json: ad, sürüm ve kullanılan görsel API sürümü.
• Desktop’ta denemek için Dosya → Seçenekler → Rapor ayarları → Görsel geliştir seçeneği açılır; ayar yalnızca o oturum için geçerlidir.

Sertifika: Görsel önce Partner Center üzerinden AppSource’a gönderilir, sonra isteğe bağlı olarak sertifika istenir. Sertifikalı görsel dış servislere HTTP ya da WebSocket isteği yapamaz, eval gibi dinamik kod kullanamaz ve kod incelemesinden geçer. Karşılığında PowerPoint’e dışa aktarma ve e-posta aboneliklerinde görünme gibi ek yetenekler kazanır. Kurumlar çoğu zaman yalnızca sertifikalı ya da yönetici tarafından onaylanmış görsellere izin verir.

Hangi araç ne zaman?

Bu araçların CI/CD akışındaki yeri (Git, dağıtım işlem hatları) “Yaşam döngüsü” dersinde anlatılıyor.