Power Apps denetleyicisi web API'sini kullanma

  • Makale

Power Apps Denetleyici Web API 'si, Microsoft Dataverse platforma yönelik özelleştirmelere ve uzantılara karşı statik çözümleme denetimlerini çalıştırmak için bir mekanizma sağlar. Yaratıcı ve geliştiriciler, bir zengin statik çözümleme denetim çözümlerinizi en iyi yöntem kuralları kümesiyle gerçekleştirebilir ve hızlı bir şekilde bu soruna neden olan desenleri belirlemek. Hizmet, Power Apps oluşturucu portalı'ndaki çözüm denetleyicisi özelliği için mantık sağlar ve AppSource uygulamasına gönderilen uygulamalar için otomasyonun bir parçası olarak dahildir. Servisle doğrudan bu şekilde etkileşim kurmak, yerinde (desteklenen tüm sürümler) ve çevrimiçi ortamlarının bir parçası olarak dahil olan çözümlerin analizine olanak tanır.

PowerShell kodundan denetleyicisi hizmeti kullanma hakkında bilgi için PowerShell kullanarak çözümlerle çalışma bölümüne bakın.

Not

  • Power Apps denetleyicisinin kullanımı, çözüm içeri aktarmanın başarılı olacağını garanti etmez. Çözüme karşı gerçekleştirilen statik çözümleme denetimleri, hedef ortamın yapılandırılmış durumunu bilmez ve içeri aktarma işleminin başarısı ortamdaki diğer çözümlere veya yapılandırmalara bağlı olabilir.

Alternatif yaklaşımlar

Web API'leriyle en düşük düzeyde etkileşim kurma ayrıntılarını okumadan önce PowerShell modülümüz olan Microsoft.PowerApps.Checker.PowerShell'i kullanmayı düşünün. PowerShell Galerisi'nde tamamen desteklenen bir araçtır. Geçerli kısıtlama, Windows PowerShell gerektirmesidir. Bu gereksinimi karşılayamazsanız, API'lerle doğrudan etkileşim kurmak en iyi yaklaşımdır.

Kullanmaya başlama

Bir çözüm analizinin uzun süren bir sürece neden olabileceğini unutmayın. Özelleştirmelerin ve kodların sayısı, boyutu ve karmaşıklığı gibi çeşitli etkenlere bağlı olarak genellikle altı (60) saniye, en çok beş (5) dakika sürebilir. Analiz akışı çok adımlıdır ve işin tamamlanmasını sorgulamak için kullanılan durum API'si ile bir analiz işi başlatılması zaman uyumsuzdur. Analiz için örnek bir akış aşağıdaki gibidir:

  1. OAuth belirteci edinme
  2. Çağrı yüklemesi (eşzamanlı olarak her dosya için)
  3. Çağrı analizi (analiz işini başlatır)
  4. Bitene kadar çağrı durumu (sonu işaret edilene veya eşikler karşılanana kadar aramalar arasında duraklama ile döngü oluşturur)
  5. Sonuçları, sağlanan SAS URI'sinden indirme

Birkaç farklı kullanımı şöyledir:

  • Kural kümesi veya kural aramasını bir ön adım olarak ekleyin. Ancak yapılandırılmış veya sabit kodlanmış bir kural kümesi kimliğini iletmek biraz daha hızlıdır. Gereksinimlerinizi karşılayan bir kural kümesi kullanmanız önerilir.
  • Karşıya yükleme mekanizmasını kullanmamayı tercih edebilirsiniz (sınırlamalar için bkz. karşıya yükleme).

Aşağıdaki gereksinimleri belirlemeniz gerekir:

Bireysel API'ler ile ilgili belgeler için aşağıdaki makalelere bakın:

Kural kümeleri listesini alma
Kurallar listesini alma
Dosyayı karşıya yükleme
Analiz çağırma
Analiz durumunu denetleme

Coğrafya belirleme

Power Apps denetim hizmetiyle etkileşim kurduğunuzda, dosyalar oluşturulan raporlarla birlikte geçici olarak Azure'da depolanır. Coğrafyaya özel bir API kullanarak verilerin nerede depolanacağını denetleyebilirsiniz. Bir coğrafya uç noktasına yapılan istekler, en iyi performansa (istekte bulunana gecikme) göre bölgesel bir örneğe yönlendirilir. Bir istek bölgesel bir hizmet örneğine girdiğinde, tüm işlem ve kalıcı veriler o bölge içinde kalır. Belirli API yanıtları, bir analiz işi belirli bir bölgeye yönlendirildiğinde, sonraki istekler için bölgesel kurulum URL'lerini döndürür. Her coğrafyanın herhangi bir zamanda dağıtılan servisin farklı bir sürümü olabilir. Farklı hizmet sürümlerinin kullanımı, tam sürüm uyumluluğu sağlayan çok aşamalı güvenli dağıtım işleminden kaynaklanır. Bu nedenle, analiz yaşam döngüsündeki her API çağrısı için aynı coğrafya kullanılmalıdır ve veriler kablo üzerinden uzağa taşınmak zorunda kalmayabileceğinden genel yürütme süresini azaltabilir. Aşağıdaki coğrafyalar kullanılabilir:

Azure veri merkezi Ad Coğrafi Bölge Temel URI
Kamu Önizleme Birleşik Devletler unitedstatesfirstrelease.api.advisor.powerapps.com
Kamu Üretim Birleşik Devletler unitedstates.api.advisor.powerapps.com
Kamu Üretim Avrupa europe.api.advisor.powerapps.com
Kamu Üretim Asya asia.api.advisor.powerapps.com
Kamu Üretim Avustralya australia.api.advisor.powerapps.com
Kamu Üretim Japonya japan.api.advisor.powerapps.com
Kamu Üretim Hindistan india.api.advisor.powerapps.com
Kamu Üretim Kanada canada.api.advisor.powerapps.com
Kamu Üretim Güney Amerika southamerica.api.advisor.powerapps.com
Kamu Üretim Birleşik Krallık unitedkingdom.api.advisor.powerapps.com
Kamu Üretim Fransa france.api.advisor.powerapps.com
Sunulabilir Üretim Almanya germany.api.advisor.powerapps.com
Sunulabilir Üretim Birleşik Arap Emirlikleri unitedarabemirates.api.advisor.powerapps.com
Sunulabilir Üretim İsviçre switzerland.api.advisor.powerapps.com
Sunulabilir Üretim Güney Afrika southafrica.api.advisor.powerapps.com
Sunulabilir Üretim Güney Kore korea.api.advisor.powerapps.com
Sunulabilir Üretim Norveç norway.api.advisor.powerapps.com
Sunulabilir Üretim Singapur singapore.api.advisor.powerapps.com
Sunulabilir Üretim US Government gov.api.advisor.powerapps.us
Kamu Üretim US Government L4 high.api.advisor.powerapps.us
Kamu Üretim US Government L5 (DOD) mil.api.advisor.appsplatform.us
Kamu Üretim 21Vianet tarafından işletilen Çin china.api.advisor.powerapps.cn

Not

En son özellikleri ve değişiklikleri eklemek için önizleme coğrafyasını kullanmayı seçebilirsiniz. Ancak önizlemenin yalnızca Birleşik Devletler Azure bölgelerini kullandığını unutmayın.

Sürüm oluşturma

Gerekli olmasa da API sürümü sorgu dizesi parametresinin istenen API sürümüne eklenmesi önerilir. Geçerli API sürümü kurallar ve kurallar için 2.0 ve diğer tüm istekler için 1.0'dır. Örneğin, aşağıdaki kural kümesi 2.0 API sürümünü kullanmayı belirten bir HTTP isteğidir:

https://unitedstatesfirstrelease.api.advisor.powerapps.com/api/ruleset?api-version=2.0

Sağlanmazsa, en son API sürümü varsayılan olarak kullanılır. Değişiklikler ortaya çıktıysa sürüm artdıkça açık bir sürüm numarası kullanılması önerilir. Sürüm numarası bir istekte belirtilirse sonraki (sayısal olarak daha büyük) sürümlerde geriye dönük uyumluluk desteği korunur.

Kural kümeleri ve kurallar

Power Apps denetleyicisi, çalışırken bir kurallar listesi gerektirir. Bu kurallar, tek tek kurallar veya kural kümesi olarak adlandırılan bir kurallar grubu şeklinde sağlanabilir. Kural kümesi, her kuralı ayrı ayrı belirtmek yerine bir grup kuralı belirtmek için kullanışlı bir yoldur. Örneğin, çözüm denetleyicisi özelliği Çözüm Denetleyicisi adlı bir kural kümesi kullanır. Yeni kurallar eklendikçe veya kaldırıldıkça, servis tüketen uygulamanın herhangi bir değişikliğini gerektirmeden bu değişiklikleri otomatik olarak içerir. Kurallar listesinin yukarıda açıklandığı gibi otomatik olarak değişmesini istemiyorsanız kurallar tek tek belirtilebilir. Kural kümelerinin sınır olmadan bir veya daha fazla kuralı olabilir. Bir kural, hiçbir kural kümesinde olmayabilir veya birden çok kural kümesinde olabilir. API'yi, şurada belirtildiği şekilde çağırarak tüm kural kümelerinin bir listesini alabilirsiniz: [Geographical URL]/api/ruleset. Bu uç nokta için kimlik doğrulaması gerekli.

Çözüm denetleyicisi kural kümesi

Çözüm denetleyicisi kural kümesi, hatalı pozitif sonuçlar için sınırlı olasılığa sahip bir dizi etkili kural içerir. Çözümlemeyi varolan bir çözüme karşı çalıştırıyorsanız, bu kural kümesiyle başlamanız önerilir. Bu kural seti, çözüm denetleyicisi özelliği tarafından kullanılır.

AppSource sertifikası kural kümesi

AppSource üzerinde uygulama yayımlarken uygulamanızı onaylatmanız gerekir. AppSource uygulamasında yayımlanan uygulamaların yüksek kalite standartlarını karşılaması gerekir. AppSource sertifika kuralları kümesi, çözüm denetleyicisi kural kümesinin parçası olan kuralların yanı sıra yalnızca yüksek kaliteli uygulamaların mağaza üzerinde yayınlanmasını sağlamak için diğer kuralları içerir. Bazı AppSource sertifika kuralları yanlış olumlulara daha eğilimli olup, bu kuralların çözümlenmesine daha fazla dikkat edilmesi gerekebilir.

Kiracı kimliğinizi bulma

Belirteç gerektiren API'lerle etkileşim kurmak için kiracınızın kimliği gereklidir. Kiracı kimliğinin nasıl elde edileceğiyle ilgili ayrıntılar için bu makale'ye bakın. Kiracı kimliğini almak için PowerShell komutlarını da kullanabilirsiniz. Aşağıdaki örnek AzureAD modülündeki cmdlet'ler için geçerlidir.

# Login to Microsoft Entra ID as your user
Connect-AzureAD

# Establish your tenant ID
$tenantId = (Get-AzureADTenantDetail).ObjectId

Kiracı kimliği, Get-AzureADTenantDetail öğesinden döndürülen ObjectId özelliğinin değeridir. Bunu cmdlet çıkışındaki Connect-AzureAD cmdlet'ini kullanarak oturum açtıktan sonra da görebilirsiniz. Bu durumda TenantId olarak adlandırılır.

Kimlik doğrulaması ve yetkilendirme

Kurallar ve kural kümeleri için sorgu oAuth belirteci gerektirmez ancak diğer tüm API'ler belirteç gerektirir. API'ler, belirteç gerektiren API'lerden herhangi birini çağırarak yetkilendirme keşfini destekler. Yanıt, WWW-Authenticate üstbilgisi, kimlik doğrulama URI'sı ve kaynak kimliğiyle birlikte 401 numaralı yetkisiz HTTP durum kodudur. Kiracı kimliğinizi x-ms-tenant-id başlığında da belirtmelisiniz. Daha fazla bilgi için bkz. Power Apps Denetleyicisi kimlik doğrulaması ve yetkilendirme. Aşağıdaki API isteğinden döndürülen yanıt başlığına bir örnek verilmiştir:

WWW-Authenticate →Bearer authorization_uri="https://login.microsoftonline.com/0082fff7-33c5-44c9-920c-c2009943fd1e", resource_id="https://api.advisor.powerapps.com/"

Bu bilgilere sahip olduktan sonra belirteci almak için Microsoft Kimlik Doğrulaması Kitaplığı'nı (MSAL) veya başka bir mekanizmayı kullanabilirsiniz. Aşağıda, bunun C# ve MSAL .NET kitaplığı kullanılarak nasıl yapılacağına dair bir örnek vardır:

// Substitute your own environment URL here.
string resource = "https://<env-name>.api.<region>.dynamics.com";

// Example Microsoft Entra app registration.
// For your custom apps, you will need to register them with Microsoft Entra ID yourself.
// See https://docs.microsoft.com/powerapps/developer/data-platform/walkthrough-register-app-azure-active-directory
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback required for the interactive login.

var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/.default";
string[] scopes = { scope };

AuthenticationResult tokenResult =
     await authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync();

Tam çalışan kod için bkz. Web API'si Hızlı Başlangıç örneği.

Belirteci aldıktan sonra istek yaşam döngüsü içinde yer alan sonraki çağrılara aynı belirteci sağlamanız önerilir. Ancak, daha fazla istek güvenlik nedeniyle yeni bir belirtecin alınması için garanti verebilir.

Taşıma güvenliği

Sınıfının en iyisi şifreleme için, denetleyicisi hizmeti yalnızca Aktarım Katmanı Güvenliği (TLS) 1.2 ve daha üst düzey iletişimleri destekler. TLS çevresindeki .NET en iyi uygulamaları hakkında rehberlik için bkz. .NET Framework ile Aktarım Katmanı Güvenliği (TLS) en iyi uygulamaları.

Rapor biçimi

Çözüm analizinin sonucu, standartlaştırılmış JSON biçiminde bir veya daha fazla rapor içeren zip dosyasıdır. Rapor biçimi, Statik Analiz Sonuçları Değişim Biçimi (SARIF) olarak adlandırılan statik analiz sonuçlarını temel alır. SARIF belgelerini görüntülemek ve bunlarla etkileşim kurmak için kullanılabilecek araçlar vardır. Ayrıntılar için bu web sitesi'ne bakın. Serviste, OASIS standardının iki sürümü kullanılmaktadır.

Ayrıca bkz.

Kural kümeleri listesini alma
Kurallar listesini alma
Dosyayı karşıya yükleme
Analiz çağırma
Analiz durumunu denetleme