Power BI REST API ile geliştirilmiş yenileme

Power BI Yenileme Veri Kümesi REST API'sini kullanarak anlam modeli yenileme işlemleri yapmak için REST çağrılarını destekleyen herhangi bir programlama dilini kullanabilirsiniz.

Büyük ve karmaşık bölümlenmiş modeller için iyileştirilmiş yenileme geleneksel olarak TOM (Tablolu Nesne Modeli), PowerShell cmdlet'leri veya TMSL (Tablolu Model Betik Dili) kullanan programlama yöntemleriyle çağrılır. Ancak, bu yöntemler güvenilir olmayan uzun süre çalışan HTTP bağlantıları gerektirir.

Power BI Yenileme Veri Kümesi REST API'si model yenileme işlemlerini zaman uyumsuz olarak gerçekleştirebilir, bu nedenle istemci uygulamalarından uzun süre çalışan HTTP bağlantıları gerekli değildir. Standart yenileme işlemleriyle karşılaştırıldığında REST API ile geliştirilmiş yenileme daha fazla özelleştirme seçeneği ve büyük modeller için yararlı olan aşağıdaki özellikleri sağlar:

• Toplu gönderimler
• Tablo ve bölüm düzeyinde yenileme
• Artımlı yenileme ilkeleri uygulama
• GET yenileme ayrıntıları
• Yenileme iptali
• Zaman aşımı yapılandırması

Not

• Daha önce, zaman uyumsuz yenileme, REST APIile gelişmiş yenileme olarak adlandırılıyordu. Ancak, Yenileme Veri Kümesi REST API'sini kullanan standart bir yenileme de doğası gereği zaman uyumsuz olarak çalışır.
• Gelişmiş Power BI REST API yenileme işlemleri kutucuk önbelleklerini otomatik olarak yenilemez. Kutucuk, yalnızca kullanıcı bir rapora eriştiğinde yenilemeyi önbelleğe alır.

Temel URL

Temel URL aşağıdaki biçimdedir:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes 

Kaynakları ve işlemleri parametrelere göre temel URL'ye ekleyebilirsiniz. Aşağıdaki diyagramda Groups, Datasetsve Refreshes, koleksiyonlardır. Group, Datasetve Refreshnesneleridir.

Zaman uyumsuz yenileme akışını gösteren

Gereksinimler

REST API'yi kullanmak için aşağıdaki gereksinimlere ihtiyacınız vardır:

• Power BI Premium, Kullanıcı başına Premium veya Power BI Embedded'de anlamsal model.
• İstek URL'sinde kullanılacak grup kimliği ve veri kümesi kimliği.
• Dataset.ReadWrite.All izin kapsamı.

Yenileme sayısı, Pro ve Premium modelleri için API tabanlı yenilemeler için genel sınırlamalara göre sınırlıdır.

Kimlik doğrulama

Tüm çağrıların Yetkilendirme üst bilgisinde geçerli bir Microsoft Entra Id OAuth 2 belirteci ile kimlik doğrulaması yapması gerekir. Belirteç aşağıdaki gereksinimleri karşılamalıdır:

• Kullanıcı belirteci veya uygulama hizmet sorumlusu olun.
• hedef kitlenin https://api.powerbi.comolarak doğru şekilde ayarlanmasını sağlayın.
• Model üzerinde yeterli izinlere sahip bir kullanıcı veya uygulama tarafından kullanılabilir.

Not

REST API değişiklikleri, model yenilemeleri için şu anda tanımlanmış izinleri değiştirmez.

POST/refreshes

Yenileme yapmak için ,/refreshes koleksiyonundaki POST fiilini kullanarak koleksiyona yeni bir yenileme nesnesi ekleyin. Yanıttaki Konum üst bilgisi requestIdiçerir. İşlem zaman uyumsuz olduğundan, bir istemci uygulaması bağlantıyı kesebilir ve gerekirse durumu daha sonra denetlemek için requestId kullanabilir.

Aşağıdaki kodda örnek bir istek gösterilmektedir:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

İstek gövdesi aşağıdaki örneğe benzeyebilir:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "timeout": "02:00:00",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Not

Hizmet, bir model için aynı anda yalnızca bir yenileme işlemi kabul eder. Devam eden bir yenileme varsa ve başka bir istek gönderilirse, HTTP durum kodu 400 Bad Request döner.

Parametreler

Gelişmiş yenileme işlemi yapmak için istek gövdesinde bir veya daha fazla parametre belirtmeniz gerekir. Belirtilen parametreler varsayılan veya isteğe bağlı bir değeri belirtebilir. İstek parametreleri belirttiğinde, diğer tüm parametreler varsayılan değerleriyle işleme uygulanır. İstek parametre belirtmiyorsa, tüm parametreler varsayılan değerlerini kullanır ve standart bir yenileme işlemi gerçekleşir.

Ad	Tür	Varsayılan	Açıklama
type	Numaralandırma	automatic	Gerçekleştirilecek işleme türü. Türler TMSL yenileme komut türleriyle hizalanır: full, clearValues, calculate, dataOnly, automaticve defragment. add türü desteklenmez.
commitMode	Numaralandırma	transactional	Nesnelerin toplu olarak mı yoksa yalnızca tamamlandığında mı işleneceğini belirler. Modlar transactional ve partialBatch. partialBatch kullanırken yenileme işlemi tek bir işlem içinde gerçekleşmez. Her komut ayrı ayrı kaydedilir. Bir hata varsa, model boş olabilir veya verilerin yalnızca bir alt kümesini içerebilir. Hataya karşı koruma sağlamak ve işlem başlatılmadan önce modelde yer alan verileri korumak için, commitMode = transactionalile işlemi yürütür.
maxParallelism	Int	10	İşleme komutlarını paralel olarak çalıştırabilecek en fazla iş parçacığı sayısını belirler. Bu değer, TMSL MaxParallelism komutunda veya diğer yöntemler kullanılarak ayarlanabilen Sequence özelliğiyle hizalanır.
retryCount	Int	0	İşlemin başarısız olmadan önce yeniden deneme sayısı.
objects	Dizi	Tüm model	İşlenmek üzere bir nesne dizisi. Her nesne, tablonun tamamını işlerken table veya bir bölümü işlerken table ve partition içerir. Hiçbir nesne belirtilmezse, modelin tamamı yenilenir.
applyRefreshPolicy	Boolean	true	Artımlı yenileme ilkesi tanımlanmışsa, ilkenin uygulanıp uygulanmayacağını belirler. Modlar true veya false. İlke uygulanmazsa, tam işlem bölüm tanımlarını değiştirmeden bırakır ve tablodaki tüm bölümleri tamamen yeniler. commitMode transactionalise applyRefreshPolicytrue veya falseolabilir. commitMode'nin partialBatcholması durumunda, applyRefreshPolicy'nin true'si desteklenmez ve applyRefreshPolicy, falseolarak ayarlanmalıdır.
effectiveDate	Tarih	Geçerli tarih	Artımlı yenileme ilkesi uygulanırsa, effectiveDate parametresi geçerli tarihi geçersiz kılar. Belirtilmezse, geçerli gün 'Yenile'altındaki saat dilimi yapılandırması kullanılarak belirlenir.
timeout	Dizgi	05:00:00 (5 saat)	Bir timeout belirtilirse, anlamsal modeldeki her veri yenileme girişimi bu zaman aşımına bağlıdır. Tek bir yenileme isteği, retryCount belirtilirse birden çok deneme içerebilir ve bu da toplam yenileme süresinin belirtilen zaman aşımını aşmasına neden olabilir. Örneğin, 1 saatlik bir timeout ve 2 retryCount ayarlamak, toplam yenileme süresinin 3 saate kadar çıkmasına yol açabilir. Kullanıcılar, daha hızlı hata algılama için yenileme süresini kısaltmak için timeout ayarlayabilir veya daha karmaşık veri yenilemeleri için varsayılan 5 saati aşabilir. Ancak, yeniden denemeler de dahil olmak üzere toplam yenileme süresi 24 saati aşamaz.

Yanıt

202 Accepted

Yanıt, çağıranı oluşturulan ve kabul edilen yenileme işlemine işaret eden bir Location yanıt başlığı alanı da içerir. Location, isteğin oluşturduğu yeni kaynağın konumudur ve bazı gelişmiş yenileme işlemlerinin gerektirdiği requestId içerir. Örneğin, aşağıdaki yanıtta requestId87f31ef7-1e3a-4006-9b0b-191693e79e9eyanıttaki son tanımlayıcıdır.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /refreshes

Geçmiş, geçerli ve bekleyen yenileme işlemlerini listelemek için /refreshes koleksiyonundaki GET fiilini kullanın.

Yanıt gövdesi aşağıdaki örnekteki gibi görünebilir:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Not

Kısa bir süre içinde çok fazla istek varsa Power BI istekleri bırakabilir. Power BI yenileme yapar, sonraki isteği kuyruğa alır ve diğerlerini bırakır. Tasarım gereği, bırakılan isteklerde durumu sorgulayamazsınız.

Yanıt özellikleri

Ad	Tür	Açıklama
requestId	Kılavuz	Yenileme isteğinin tanımlayıcısı. Tek tek yenileme işlemi durumunu sorgulamak veya devam eden yenileme işlemini iptal etmek için requestId gerekir.
refreshType	Dizgi	OnDemand yenilemenin Power BI portalı aracılığıyla etkileşimli olarak tetiklendiğini gösterir. Scheduled, yenilemeyi model yenileme zamanlamasının tetiklediğini gösterir. ViaApi yenilemeyi bir API çağrısının tetiklediğini gösterir. ViaEnhancedApi, bir API çağrısının gelişmiş yenileme tetiklediğini gösterir.
startTime	Dizgi	Yenilemenin başlangıç tarihi ve saati.
endTime	Dizgi	Yenileme bitiş tarihi ve saati.
status	Dizgi	Completed yenileme işleminin başarıyla tamamlandığını gösterir. Failed yenileme işleminin başarısız olduğunu gösterir. Unknown tamamlanma durumunun belirlenemeyeceğini gösterir. Bu durumla endTime boş olur. Disabled, yenilemenin seçmeli yenileme tarafından devre dışı bırakıldığını gösterir. Cancelled yenilemenin başarıyla iptal edildiğine işaret eder.
extendedStatus	Dizgi	Daha fazla bilgi sağlamak için status özelliğini genişleter.

Not

Azure Analysis Services'te tamamlanan status sonucu succeeded'dir. Bir Azure Analysis Services çözümünü Power BI'a geçirirseniz çözümlerinizi değiştirmeniz gerekebilir.

Döndürülen yenileme işlemlerinin sayısını sınırlayın

Power BI REST API,isteğe bağlı $top parametresini kullanarak yenileme geçmişinde istenen girdi sayısını sınırlamayı destekler. Belirtilmezse, varsayılan tüm kullanılabilir girdiler olur.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}      

GET /refreshes/<requestId>

Yenileme işleminin durumunu denetlemek için, requestIdbelirterek yenileme nesnesinde GET fiilini kullanın. İşlem devam ediyorsa, status aşağıdaki örnek yanıt gövdesinde olduğu gibi InProgressdöndürür:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

Devam eden gelişmiş yenileme işlemini iptal etmek için, requestIdbelirterek yenileme nesnesindeki DELETE fiilini kullanın.

Mesela

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

Dikkat edilmesi gerekenler ve sınırlamalar

Yenileme işlemi aşağıdaki önemli noktalara ve sınırlamalara sahiptir:

Standart yenileme işlemleri

• portalda yenile düğmesi seçilerek tetiklenen zamanlanmış veya isteğe bağlı model yenilemelerini DELETE /refreshes/<requestId>kullanarak iptal yapamazsınız.
• Portalda yenile düğmesi seçilerek tetiklenen zamanlanmış ve isteğe bağlı model yenilemeleri, GET /refreshes/<requestId>kullanılarak yenileme işlemi ayrıntılarını almayı desteklemez.
• "Ayrıntıları Al ve İptal, yalnızca gelişmiş yenileme için tasarlanmış yeni işlemlerdir." Standart yenileme bu işlemleri desteklemez.

Power BI Embedded

Kapasite Power BI portalında veya PowerShell kullanılarak el ile duraklatılırsa veya bir sistem kesintisi oluşursa, devam eden gelişmiş yenileme işleminin durumu en fazla altı saat InProgress kalır. Kapasite altı saat içinde devam ederse yenileme işlemi otomatik olarak sürdürülür. Eğer kapasite altı saatten daha uzun bir süre sonra devam ederse, yenileme işlemi bir zaman aşımı hatası döndürebilir. Ardından yenileme işlemini yeniden başlatmanız gerekir.

Anlamsal model çıkarma

Power BI, kapasite belleğini iyileştirmek için dinamik bellek yönetimi kullanır. Yenileme işlemi sırasında model bellekten çıkarılırsa aşağıdaki hata döndürülebilir:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

Çözüm, yenileme işlemini yeniden çalıştırmaktır. Dinamik bellek yönetimi ve model çıkarma hakkında daha fazla bilgi edinmek için bkz. Model çıkarma.

Yenileme işlemi süresi sınırları

Yenileme işlemi, retryCount belirtilirse birden çok deneme içerebilir. Her denemenin varsayılan zaman aşımı 5 saattir ve bu süre timeout parametresi kullanılarak ayarlanabilir. Yeniden denemeler de dahil olmak üzere toplam yenileme süresi 24 saati geçmemelidir.

retryCount bir sayı belirtirse, yeni bir yenileme işlemi zaman aşımı sınırıyla başlar. Hizmet, bu işlemi başarılı olana, retryCount sınırına ulaşana veya ilk denemeden itibaren 24 saatlik maksimum süreye ulaşana kadar yeniden dener.

Daha hızlı hata algılama için yenileme süresini kısaltmak için timeout ayarlayabilir veya daha karmaşık veri yenilemeleri için varsayılan 5 saati aşabilirsiniz.

Veri Kümesini Yenile REST API'siyle anlamsal model yenilemenizi planlarken zaman sınırlarını ve retryCount parametresini göz önünde bulundurun. İlk deneme başarısız olursa ve retryCount değeri 1 veya daha fazla olarak ayarlanırsa yenileme zaman aşımını aşabilir. "retryCount" : 1 ile yenileme isteğinde bulunursanız ve ilk deneme 4 saat sonra başarısız olursa, ikinci bir deneme başlar. Bu işlem 3 saat içinde başarılı olursa yenilemenin toplam süresi 7 saattir.

Yenileme işlemleri düzenli olarak başarısız olursa, zaman aşımı süresi sınırını aşıyorsa veya istediğiniz başarılı yenileme işlemi süresini aşıyorsa, veri kaynağından yenilenen veri miktarını azaltmayı göz önünde bulundurun. Yenilemeyi birden çok isteğe bölebilirsiniz, örneğin her tablo için bir istek. commitMode parametresinde partialBatch de belirtebilirsiniz.

Kod örneği

Başlamanıza yardımcı olacak bir C# kod örneği için bkz. GitHub'da RestApiSample .

Kod örneğini kullanmak için:

1. Depoyu kopyalayın veya indirin.
2. RestApiSample çözümünü açın.
3. client.BaseAddress = … satırını bulun ve temel URL'nizisağlayın.

Kod örneği hizmet sorumlusu kimlik doğrulamasını kullanır.

İlgili içerik

• Power BI Veri Kümesi Yenileme REST API
• Power BI REST API'lerini kullanma