Power Apps denetleyicisi web API'sini kullanma

Power Apps denetleyicisi web API'si, Microsoft Dataverse platformundaki özelleştirmelere ve uzantılara karşı statik analiz denetimleri çalıştırmaya yönelik 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ı içindeki çözüm denetleyici özelliğinin mantığını sağlar ve Marketplace'e gönderilen uygulamalar için otomasyonun bir parçası olarak dahil edilir. 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.

Uyarı

Power Apps denetleyicisinin kullanılması, çözüm içeri aktarma işleminin 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 seviyede nasıl etkileşim kuracağınıza dair ayrıntıları okumadan önce, bunun yerine PowerShell modülümüz olan Microsoft.PowerApps.Checker.PowerShell'i kullanmayı düşünün. bu, PowerShell Galerisi içinde kullanılabilen tam olarak desteklenen bir araçtır. Geçerli kısıtlama, Windows PowerShell gerektirdiğidir. Bu gereksinimi karşılayamazsanız, API'lerle doğrudan etkileşim kurmak en iyi yaklaşımdır.

Başlarken

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 aracılara 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:

OAuth belirteci edinme
Çağrı yüklemesi (eşzamanlı olarak her dosya için)
Çağrı analizi (analiz işini başlatır)
Bitene kadar çağrı durumu (sonu işaret edilene veya eşikler karşılanana kadar aramalar arasında duraklama ile döngü oluşturur)
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:

Hangi coğrafya?
Hangi sürüm?
Hangi kural kümeleri ve kurallar?
Kiracı kimliğiniz nedir?

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 denetleyicisi hizmetiyle etkileşime geçtiğinizde dosyalar, oluşturulan raporlarla birlikte geçici olarak Azure 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	Name	Coğrafya	Temel URI
Public	Önizleme	Birleşik Devletler	unitedstatesfirstrelease.api.advisor.powerapps.com
Public	Üretim	Birleşik Devletler	unitedstates.api.advisor.powerapps.com
Public	Üretim	Europe	europe.api.advisor.powerapps.com
Public	Üretim	Asya	asia.api.advisor.powerapps.com
Public	Üretim	Australia	australia.api.advisor.powerapps.com
Public	Üretim	Japonya	japan.api.advisor.powerapps.com
Public	Üretim	Hindistan	india.api.advisor.powerapps.com
Public	Üretim	Canada	canada.api.advisor.powerapps.com
Public	Üretim	Güney Amerika	southamerica.api.advisor.powerapps.com
Public	Üretim	Birleşik Krallık	unitedkingdom.api.advisor.powerapps.com
Public	Üretim	Fransa	france.api.advisor.powerapps.com
Public	Üretim	Almanya	germany.api.advisor.powerapps.com
Public	Üretim	Birleşik Arap Emirlikleri	unitedarabemirates.api.advisor.powerapps.com
Public	Üretim	İsviçre	switzerland.api.advisor.powerapps.com
Public	Üretim	Güney Afrika	southafrica.api.advisor.powerapps.com
Public	Üretim	Güney Kore	korea.api.advisor.powerapps.com
Public	Üretim	Norveç	norway.api.advisor.powerapps.com
Public	Üretim	Singapur	singapore.api.advisor.powerapps.com
Public	Üretim	İsveç	sweden.api.advisor.powerapps.com
Public	Üretim	Polonya	poland.api.advisor.powerapps.com
Public	Üretim	İtalya	italy.api.advisor.powerapps.com
Public	Üretim	ABD Hükümeti	gov.api.advisor.powerapps.us
Public	Üretim	ABD Hükümeti L4	high.api.advisor.powerapps.us
Public	Üretim	ABD Hükümeti L5 (DOD)	mil.api.advisor.appsplatform.us
Public	Üretim	21Vianet tarafından işletilen Çin	china.api.advisor.powerapps.cn

Uyarı

En son özellikleri ve değişiklikleri eklemek için önizleme coğrafyasını kullanmayı seçebilirsiniz. Ancak önizlemede yalnızca Birleşik Devletler Azure bölgelerin kullanıldığına dikkat edin.

Versiyonlama

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ıştırıldığında bir kural 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.

Pazaryeri sertifikasyon kurallar dizisi

Market'te uygulama yayımlarken uygulamanızın sertifikasını almanız gerekir. Market'te yayımlanan uygulamaların yüksek kalite standardına uyması gerekir. Market sertifika kural kümesi, çözüm denetleyicisi kural kümesinin parçası olan kuralların yanı sıra mağazada yalnızca yüksek kaliteli uygulamaların yayımlandığından emin olmak için diğer kuralları içerir. Marketplace sertifikasyon kurallarından bazıları hatalı pozitiflere daha yatkındır ve bunların çözümlenmesi daha fazla dikkat gerektirebilir.

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, ObjectId öğesinden döndürülen Get-AzureADTenantDetail ö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 Power Apps Denetleyicisi kimlik doğrulaması ve yetkilendirme bölümüne bakın. 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 Authentication Library (MSAL) veya başka bir mekanizma kullanmayı seçebilirsiniz. Aşağıda, C# ve MSAL .NET kitaplığı kullanılarak bunun nasıl gerçekleştirilebileceğine ilişkin bir örnek verilmiştir:

// 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. .NET Framework için TLS konusunda en iyi uygulamalar hakkında kılavuz almak için Transport Katman Güvenliği (TLS) en iyi uygulamaları bölümüne bakın.

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.