Aracılığıyla paylaş

Power BI REST API ile geliştirilmiş yenileme

  • Makale

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 işlemeler
  • Tablo ve bölüm düzeyinde yenileme
  • Artımlı yenileme ilkeleri uygulama
  • GET yenileme ayrıntıları
  • Yenileme iptali

Not

  • Daha önce rest API ile zaman uyumsuz yenileme olarak geliştirilmiş 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 Gruplar, Veri Kümeleri ve Yenilemeler koleksiyonlardır. Group, Dataset ve Refresh nesneleridir.

Diagram that shows asynchronous refresh flow.

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ğrulaması

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 doğru olarak ayarlanmasını sağlayın https://api.powerbi.com.
  • 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 öğesini requestIdiçerir. İşlem zaman uyumsuz olduğundan, bir istemci uygulaması bağlantısını kesebilir ve gerekirse daha sonra durumunu denetlemek için öğesini kullanabilir requestId .

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,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Not

Hizmet, bir model için aynı anda yalnızca bir yenileme işlemi kabul eder. Geçerli bir çalışan yenileme varsa ve başka bir istek gönderiliyorsa, http 400 Bad Request durum kodu döndürülüyordur.

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ı Tip 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, automatic, ve defragment. Türü add desteklenmez.
commitMode Numaralandırma transactional Nesnelerin toplu olarak mı yoksa yalnızca tamamlandığında mı işleneceğini belirler. Modlar ve partialBatchşeklindedirtransactional. Yenileme işlemi kullanıldığında partialBatch tek bir işlem içinde gerçekleşmez. Her komut ayrı ayrı işlenir. 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şlamadan önce modelde yer alan verileri korumak için ile commitMode = transactionaliş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 Sequence komutunda veya diğer yöntemler kullanılarak ayarlanabilen özelliğiyle MaxParallelism hizalanır.
retryCount Int 0 İşlemin başarısız olmadan önce yeniden deneme sayısı.
objects Dizi Modelin tamamı İşlenmek üzere bir nesne dizisi. Her nesne, bir tablonun tamamını işlerken veya tablepartition bir bölümü işlerken içerirtable. Hiçbir nesne belirtilmezse, modelin tamamı yenilenir.
applyRefreshPolicy Boolean true Artımlı yenileme ilkesi tanımlanmışsa, ilkenin uygulanıp uygulanmayacağını belirler. Modlar veya falseşeklindedirtrue. İ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.

ise commitModetransactionalapplyRefreshPolicy veya falseolabilirtrue. ise commitModepartialBatch, applyRefreshPolicy değeri true desteklenmez ve applyRefreshPolicy olarak ayarlanması falsegerekir.
effectiveDate Tarih Geçerli tarih Artımlı yenileme ilkesi uygulanırsa, effectiveDate parametre geçerli tarihi geçersiz kılar. Belirtilmezse, geçerli günü belirlemek için UTC kullanılır.

Response

202 Accepted

Yanıt, çağıranı oluşturulan ve kabul edilen yenileme işlemine işaret eden bir Location yanıt üst bilgisi alanı da içerir. Location, isteğin oluşturduğu ve bazı gelişmiş yenileme işlemlerinin gerektirdiğini içeren yeni kaynağın requestId konumudur. Örneğin, aşağıdaki yanıtta yanıttaki requestId87f31ef7-1e3a-4006-9b0b-191693e79e9eson 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",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "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 GUID Yenileme isteğinin tanımlayıcısı. Tek tek yenileme işlemi durumunu sorgulamanız veya devam eden yenileme işlemini iptal etmeniz gerekir requestId .
refreshType String OnDemand yenilemenin Power BI portalı üzerinden etkileşimli olarak tetiklendiğini gösterir.
Scheduled bir model yenileme zamanlamasının yenilemeyi 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 String Yenilemenin başlangıç tarihi ve saati.
endTime String Yenileme bitiş tarihi ve saati.
status String 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 belirlenemezseniz gösterir. Bu durumda boş endTime 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 String status Daha fazla bilgi sağlamak için özelliğini genişleter.

Not

Azure Analysis Services'te tamamlanan status sonuç şeklindedir succeeded. 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, öğesini belirterek yenileme nesnesinde GET fiilini requestIdkullanın. İşlem devam ediyorsa, status aşağıdaki örnek yanıt gövdesinde olduğu gibi döndürür InProgress:

{
    "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, öğesini belirterek yenileme nesnesinde DELETE fiilini requestIdkullanın.

Örneğin,

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 edilecekler ve sınırlamalar

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

Standart yenileme işlemleri

  • kullanarak DELETE /refreshes/<requestId>zamanlanmış veya isteğe bağlı el ile model yenilemelerini iptal yapamazsınız.
  • Zamanlanmış ve isteğe bağlı el ile model yenilemeleri kullanılarak GET /refreshes/<requestId>yenileme işlemi ayrıntılarını almayı desteklemez.
  • Ayrıntıları alın ve İptal, yalnızca gelişmiş yenileme için 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 boyunca kalır InProgress . Kapasite altı saat içinde devam ederse yenileme işlemi otomatik olarak sürdürülür. Kapasite altı saatten uzun bir süre sonra devam ederse yenileme işlemi 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ı

Tek bir yenileme işlemi için maksimum süre beş saattir. Yenileme işlemi beş saatlik sınır içinde başarıyla tamamlanmazsa ve retryCount istek gövdesinde belirtilmezse veya (varsayılan) olarak 0 belirtilirse, zaman aşımı hatası döndürülüyor.

veya başka bir sayı belirtirse retryCount1 , beş saatlik sınıra sahip yeni bir yenileme işlemi başlar. Bu yeniden deneme işlemi başarısız olursa, hizmet yenileme işlemini belirten en fazla sayıda yeniden denemeye retryCount veya ilk yenileme isteğinin başlangıcından itibaren 24 saatlik gelişmiş yenileme işleme süresi sınırına kadar yeniden denemeye devam eder.

İyileştirilmiş model yenileme çözümünüzü Yenileme Veri Kümesi REST API'siyle planlarken bu zaman sınırlarını ve parametresini retryCount göz önünde bulundurmanız önemlidir. İlk yenileme işlemi başarısız olursa ve retryCount veya daha fazlasını belirtirse 1 , başarılı bir yenilemenin tamamlanması beş saati aşabilir.

Örneğin, ile "retryCount": 1yenileme işlemi isteğinde bulunursanız ve ilk yeniden deneme işlemi başlangıç saatinden dört saat sonra başarısız olursa, bu istek için ikinci bir yenileme işlemi başlar. İkinci yenileme işlemi üç saat içinde başarılı olursa yenileme isteğinin başarıyla yürütülmesi için toplam süre yedi saattir.

Yenileme işlemleri düzenli olarak başarısız olursa, beş saatlik süre 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. Parametresinde commitMode de belirtebilirsinizpartialBatch.

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. Satırı client.BaseAddress = … bulun ve temel URL'nizi sağlayın.

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

İlgili içerik