REST API ile zaman uyumsuz yenileme

  • Makale

REST çağrılarını destekleyen herhangi bir programlama dilini kullanarak Azure Analysis Services tablolu modellerinizde zaman uyumsuz veri yenileme işlemleri gerçekleştirebilirsiniz. Bu, sorgu ölçeği genişletme için salt okunur çoğaltmaların eşitlenmesini içerir.

Veri yenileme işlemleri, veri hacmi, bölümleri kullanarak iyileştirme düzeyi gibi çeşitli faktörlere bağlı olarak biraz zaman alabilir. Bu işlemler geleneksel olarak TOM (Tablolu Nesne Modeli), PowerShell cmdlet'leri veya TMSL (Tablosal Model Betik Dili) gibi mevcut yöntemlerle çağrılır. Ancak, bu yöntemler genellikle güvenilir olmayan, uzun süre çalışan HTTP bağlantıları gerektirebilir.

Azure Analysis Services için REST API, veri yenileme işlemlerinin zaman uyumsuz olarak yürütülmesini sağlar. REST API kullanılarak, istemci uygulamalarından uzun süre çalışan HTTP bağlantıları gerekli değildir. Güvenilirlik için otomatik yeniden denemeler ve toplu işlemeler gibi başka yerleşik özellikler de vardır.

Temel URL

Temel URL şu biçimi izler:

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

Örneğin, Batı ABD Azure bölgesinde bulunan adlı bir sunucuda AdventureWorks adlı myserverbir model düşünün. Sunucu adı:

asazure://westus.asazure.windows.net/myserver

Bu sunucu adının temel URL'si:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

Temel URL kullanılarak, kaynaklar ve işlemler aşağıdaki parametrelere göre eklenebilir:

Diagram that shows asynchronous refresh logic.

  • ile biten her şey bir koleksiyondur.
  • () ile biten her şey bir işlevdir.
  • Diğer her şey bir kaynak/nesnedir.

Örneğin, yenileme işlemi gerçekleştirmek için Refreshes koleksiyonundaki POST fiilini kullanabilirsiniz:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

Kimlik Doğrulaması

Yetkilendirme üst bilgisinde tüm çağrıların kimliği geçerli bir Microsoft Entra ID (OAuth 2) belirteci ile doğrulanmalıdır ve aşağıdaki gereksinimleri karşılamalıdır:

  • Belirteç bir kullanıcı belirteci veya uygulama hizmet sorumlusu olmalıdır.

  • Belirtecin doğru hedef kitle olarak ayarlanmış https://*.asazure.windows.netolması gerekir.

  • Kullanıcı veya uygulamanın istenen çağrıyı yapmak için sunucu veya model üzerinde yeterli izinlere sahip olması gerekir. İzin düzeyi, modeldeki rollere veya sunucudaki yönetici grubuna göre belirlenir.

    Önemli

    Şu anda sunucu yöneticisi rolü izinleri gereklidir.

POST/refreshes

Yenileme işlemi gerçekleştirmek için ,/refreshes koleksiyonundaki POST fiilini kullanarak koleksiyona yeni bir yenileme öğesi ekleyin. Yanıttaki Konum üst bilgisi yenileme kimliğini içerir. İstemci uygulaması zaman uyumsuz olduğundan gerekirse daha sonra bağlantıyı kesebilir ve durumu denetleyebilir.

Bir model için aynı anda yalnızca bir yenileme işlemi kabul edilir. Geçerli bir çalışan yenileme işlemi varsa ve başka bir işlem gönderildiyse, 409 Çakışma HTTP durum kodu döndürülür.

Gövde aşağıdakine benzer olabilir:

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Parametreler

Parametreleri belirtmek gerekli değildir. Varsayılan değer uygulanır.

Ad Tür Tanım Varsayılan
Type Numaralandırma Gerçekleştirilecek işleme türü. Türler TMSL yenileme komut türleriyle hizalanır: full, clearValues, calculate, dataOnly, automatic ve defragment. Ekleme türü desteklenmiyor. otomatik
CommitMode Numaralandırma Nesnelerin toplu olarak mı yoksa yalnızca tamamlandığında mı işleneceğini belirler. Modlar şunlardır: default, transactional, partialBatch. Işlem
MaxParallelism Int Bu değer, işlem komutlarının paralel olarak çalıştırıldığı en fazla iş parçacığı sayısını belirler. Bu değer, TMSL Sırası komutunda veya diğer yöntemler kullanılarak ayarlanabilen MaxParallelism özelliğiyle hizalanır. 10
RetryCount Int İşlemin başarısız olmadan önce kaç kez yeniden deneyeceğini gösterir. 0
Objects Dizi İşlenecek nesne dizisi. Her nesne şunları içerir: tablonun tamamını işlerken "tablo" veya bir bölümü işlerken "tablo" ve "bölüm". Hiçbir nesne belirtilmezse, modelin tamamı yenilenir. Modelin tamamını işleme

CommitMode, partialBatch değerine eşittir. Saatler sürebilecek büyük veri kümelerinin ilk yükünü gerçekleştirirken kullanılır. Yenileme işlemi bir veya daha fazla toplu işlemi başarıyla işledikten sonra başarısız olursa, başarıyla işlenen toplu işler işlenmeye devam eder (başarıyla işlenen toplu işlemleri geri almaz).

Dekont

Yazma sırasında toplu iş boyutu MaxParallelism değeridir, ancak bu değer değişebilir.

Durum değerleri

Durum değeri Tanım
notStarted İşlem henüz başlatılmadı.
inProgress İşlem devam ediyor.
timedOut kullanıcı tarafından belirtilen zaman aşımına bağlı olarak işlem zaman aşımına uğradı.
cancelled İşlem kullanıcı veya sistem tarafından iptal edildi.
failed İşlem başarısız oldu.
succeeded İşlem başarılı oldu.

GET /refreshes/<refreshId>

Yenileme işleminin durumunu denetlemek için yenileme kimliğindeki GET fiilini kullanın. Yanıt gövdesinin bir örneği aşağıda verilmiştır. İşlem devam ediyorsa, inProgress durumunda döndürülür.

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

GET /refreshes

Modelin geçmiş yenileme işlemlerinin listesini almak için /refreshes koleksiyonundaki GET fiilini kullanın. Yanıt gövdesinin bir örneği aşağıda verilmiştır.

Dekont

Yazma sırasında, son 30 günlük yenileme işlemleri depolanır ve döndürülür, ancak bu sayı değişebilir.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

Devam eden yenileme işlemini iptal etmek için yenileme kimliğindeki DELETE fiilini kullanın.

POST /sync

Yenileme işlemlerini gerçekleştirdikten sonra, yeni verilerin sorgu ölçeği genişletilmesi için çoğaltmalarla eşitlenmesi gerekebilir. Bir model için eşitleme işlemi gerçekleştirmek için /sync işlevinde POST fiilini kullanın. Yanıttaki Konum üst bilgisi eşitleme işlemi kimliğini içerir.

GET /sync durumu

Eşitleme işleminin durumunu denetlemek için, işlem kimliğini parametre olarak geçiren GET fiilini kullanın. Yanıt gövdesinin bir örneği aşağıda verilmişti:

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

için değerler syncstate:

  • 0: Çoğaltma. Veritabanı dosyaları bir hedef klasöre çoğaltılıyor.
  • 1: Yeniden doldurma. Veritabanı salt okunur sunucu örneklerinde yeniden dolduruluyor.
  • 2: Tamamlandı. Eşitleme işlemi başarıyla tamamlandı.
  • 3: Başarısız oldu. Eşitleme işlemi başarısız oldu.
  • 4: Son haline getirme. Eşitleme işlemi tamamlandı ancak temizleme adımları gerçekleştiriyor.

Kod örneği

GitHub'da RestApiSample adlı çalışmaya başlamanıza yardımcı olacak bir C# kod örneği aşağıda verilmiştir.

Kod örneğini kullanmak için

  1. Depoyu kopyalayın veya indirin. RestApiSample çözümünü açın.
  2. Satır istemcisini bulun. BaseAddress = ... ve temel URL'nizi sağlayın.

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

Hizmet sorumlusu

Azure AS'de hizmet sorumlusu ayarlama ve gerekli izinleri atama hakkında daha fazla bilgi için bkz . Hizmet sorumlusu oluşturma - Azure portalı ve Sunucu yöneticisi rolüne hizmet sorumlusu ekleme. Adımları tamamladıktan sonra aşağıdaki ek adımları tamamlayın:

  1. Kod örneğinde dize yetkilisi = ...değerini bulun, common değerini kuruluşunuzun kiracı kimliğiyle değiştirin.
  2. ClientCredential sınıfının cred nesnesinin örneğini oluştururken kullanılması için açıklama/açıklamayı kaldırma. Uygulama Kimliği> ve <Uygulama Anahtarı> değerlerine <güvenli bir şekilde erişildiğinden emin olun veya hizmet sorumluları için sertifika tabanlı kimlik doğrulamasını kullanın.
  3. Örnek uygulamayı çalıştırın.

Ayrıca bkz.

Örnekler
REST API