使用 Power Apps 檢查器 Web API

發行項
10/16/2024

Power Apps WEB API 檢測工具提供一項機制，可為 Microsoft Dataverse 平台的自訂和擴充項目執行靜態分析檢查。製作者和開發者都能夠使用，將解決方案對比一組最佳做法規則，執行各式各樣靜態分析檢查，以便能快速識別出問題模式。此服務為 Power Apps 製作者入口網站中的解決方案檢查工具功能提供邏輯，並且已在提交至 AppSource 的應用程式自的動化過程中加入。以這種方式直接與服務互動，可以分析已包含做為內部部署 (所有支援的版本) 與線上環境之一部分的解決方案。

如需有關透過 PowerShell 程式碼使用檢查器服務的詳細資訊，請參閱使用 PowerShell 管理解決方案。

注意

使用 Power Apps 檢查程式並不能保證解決方案將會匯入成功。針對解決方案所進行的靜態分析檢查並不知道目標環境的設定狀態，而匯入成功可能要依靠環境中的其他解決方案或設定。

替代方法

在閱讀有關如何在最低級別與 Web API 交互的詳細資訊之前，請考慮使用我們的 PowerShell 模組， Microsoft.PowerApps.Checker.PowerShell 的 Widget 來獲取。這是 PowerShell 資源庫中所提供受完整支援的工具。目前的限制是您必須有 Windows PowerShell。如果無法符合此需求，則直接與 API 互動很可能是最好的方式。

開始使用

請務必注意，解決方案分析可能會產生長時間的執行過程。通常可能需要六十 (60) 秒到五 (5) 分鐘的時間，取決於各種因素，例如自訂數目、大小和複雜度以及程式碼。分析流程是從起始分析工作開始的多步驟非同步流程，並使用狀態 API 來查詢工作是否完成。分析的範例流程如下：

獲取 OAuth 令牌
呼叫上傳 (以平行方式對每個檔案進行)
呼叫分析 (起始分析工作)
呼叫狀態，直到完成為止 (以兩項呼叫之間暫停一次的方式重複進行，直到系統指示結束或達到閾值為止)
從提供的 SAS URI 下載結果

有幾種不同的方式：

將規則集或規則的查詢納入做為準備步驟。不過，傳入此設定或硬式編碼的規則集識別碼，會稍微快一些。建議您使用符合自己需要的規則集。
您可以選擇不使用上傳機制 (請參閱「上傳」以了解限制)。

您需要確定以下要求：

哪個地理位置？
哪個版本？
哪些規則集和規則？
您的租戶 ID 是什麼？

如需個別 API 的相關文件，請參閱下列文章：

檢索規則集清單
 檢索規則清單
 上傳檔
 調用分析
 檢查分析狀態

判斷地理位置

與 Power Apps 檢查器服務互動時，檔案會與產生的報表一起暫時儲存在 Azure 中。您可以使用地理特定 API 來控制資料的儲存位置。根據最佳效能 (對要求者的延遲)，對地理端點的要求路由至區域執行個體。要求進入區域服務執行個體之後，所有處理和保存的資料都會保留在該特定區域中。當分析工作傳遞至特定區域後，某些 API 回應就會為了後續要求中回傳區域執行個體 URL。每個地理位置可能在任何給定時間點部署不同版本的服務。使用不同的服務版本是由於多階段安全部署過程，這確保了完整的版本相容性。因此，分析生命週期中的每個 API 呼叫，都必須使用相同的地理位置，而且當資料可能不需透過線路傳輸那麼遠時，可能會減少總執行時間。以下是可用的地理位置：

Azure 資料中心	姓名	地理位置	基底 URI
上市公司	預覽	美國	unitedstatesfirstrelease.api.advisor.powerapps.com
上市公司	生產	美國	unitedstates.api.advisor.powerapps.com
上市公司	生產	歐洲	europe.api.advisor.powerapps.com
上市公司	生產	亞洲	asia.api.advisor.powerapps.com
上市公司	生產	澳大利亞	australia.api.advisor.powerapps.com
上市公司	生產	日本	japan.api.advisor.powerapps.com
上市公司	生產	印度	india.api.advisor.powerapps.com
上市公司	生產	加拿大	canada.api.advisor.powerapps.com
上市公司	生產	南美地區	southamerica.api.advisor.powerapps.com
上市公司	生產	英國	unitedkingdom.api.advisor.powerapps.com
上市公司	生產	法國	france.api.advisor.powerapps.com
公開	生產環境	德國	germany.api.advisor.powerapps.com
公開	生產環境	阿拉伯聯合大公國	unitedarabemirates.api.advisor.powerapps.com
公開	生產環境	瑞士	switzerland.api.advisor.powerapps.com
公開	生產環境	南非	southafrica.api.advisor.powerapps.com
公開	生產環境	南韓	korea.api.advisor.powerapps.com
公開	生產環境	挪威	norway.api.advisor.powerapps.com
公開	生產環境	新加坡	singapore.api.advisor.powerapps.com
公開	實際執行環境	瑞典	sweden.api.advisor.powerapps.com
公開	實際執行環境	美國政府	gov.api.advisor.powerapps.us
上市公司	生產	美國政府 L4	high.api.advisor.powerapps.us
上市公司	生產	美國政府 L5（DOD）	mil.api.advisor.appsplatform.us
上市公司	生產	中國由 21Vianet 營運	china.api.advisor.powerapps.cn

Note

您可以選擇使用預覽地理位置，早一點將最新的功能和變更加入。但請注意，預覽只會使用美國 Azure 區域。

版本管理

雖然不需要，但還是建議您隨同所需的 API 版本加入 API 版本查詢字串參數。對於規則集和規則，當前 API 版本為 2.0，對於所有其他要求，當前 API 版本為 1.0。例如，下列規則集是指定使用 2.0 API 版本的 HTTP 要求：

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

如果未提供，預設會使用最新的 API 版本。建議使用明確版本號碼，因為發生中斷性變更時，版本會累加。如果已在要求中指定版本號碼，則仍將保留較晚 (數值較大) 版本中的回溯相容性支援。

規則集和規則

Power Apps 檢查器執行時需要一份規則清單。這些規則可以使用個別規則或規則群組 (稱為規則集) 的形式來提供。規則集是指定規則群組的簡便方式，反而不必個別指定每個規則。例如，解決方案檢查工具功能會使用名為解決方案檢查工具的規則集。新增或移除新規則時，服務會自動包含這些變更，而不需要取用的應用程式進行任何變更。如果您要求規則清單不依上述方式自動變更，則可以個別指定規則。規則集可以有一個或多個規則，沒有任何限制。規則可以不在任何規則集中，也可以在多個規則集中。您可以呼叫 API 來取得所有規則集的清單，如下所示：[Geographical URL]/api/ruleset。此端點現在需要身份驗證。

解決方案檢查工具規則集

解決方案檢查工具規則集包含一組有效的規則，發生誤判的機率相當低。如果要對現有的解決方案執行分析，建議您使用此規則集開始進行。這是解決方案檢查工具功能所使用的規則集。

AppSource 認證規則集

在 AppSource 上發佈應用程式時，您必須讓應用程式認證通過認證。發佈的 AppSource 應用程式需要滿足高質量標準。 AppSource 認證規則集包含屬於解決方案檢查工具規則集的一部分規則以及其他規則，以確保只有高品質的應用程式才會 Microsoft Store 上發佈。有些 AppSource 認證規則比較容易誤判，可能需要多加注意才能解決。

尋找您的用戶識別碼

您必須有用戶的識別碼，才能與需要權杖的 API 互動。如需有關如何取得用戶識別碼的詳細資料，請參閱此文章。您也可以使用 PowerShell 命令來擷取用戶識別碼。下列範例會運用 AzureAD 模組中的 Cmdlet。

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

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

用戶識別碼是 Get-AzureADTenantDetail 所傳回的 ObjectId 屬性值。使用 Connect-AzureAD Cmdlet 登入之後，您也可能會在 Cmdlet 輸出中看到這個值。在此案例中，這會命名為 TenantId。

驗證和授權

查詢規則和規則集不需要 OAuth 令牌，但所有其他 API 都需要令牌。 API 可以呼叫任何需要權杖的 API 來進行支援授權探索。回應將會是包含 WWW-Authenticate 標頭、授權 URI 及資源識別碼的 401未授權 HTTP 狀態碼。您也應該在 x-ms-tenant-id 標頭中提供您的用戶識別碼。如需詳細資訊，請參閱 Power Apps 檢查器驗證和授權。以下是 API 要求所傳回的回應標頭範例：

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

獲得此資訊后，可以選擇使用 Microsoft 身份驗證庫 (MSAL) 或其他機制來獲取令牌。以下是如何使用 C# 和 MSAL .NET 方法庫這樣做的範例：

// 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();

如需完整運作的程式碼，請參見 Web API 快速入門範例。

取得權杖之後，建議您為要求生命週期中的後續呼叫提供相同的權杖。不過，基於安全性考量，可能還需要其他要求才能確保取得新權杖。

傳輸安全性

為了獲得最佳的加密，檢查器服務只有支援使用傳輸層安全性 (TLS) 1.2 和更新版本的通訊。如需有關 .NET 最佳做法在 TLS 方面的指引，請參閱 .NET Framework 的傳輸層安全性 (TLS) 最佳做法。

報表格式

解決方案分析的結果是包含一份或多份標準化 JSON 格式報表的 zip 檔案。報表格式是以稱為靜態分析結果交換格式 (SARIF) 的靜態分析結果為根據。有一些工具可用來檢視 SARIF 文件並與之互動。如需詳細資訊，請參閱網站。此服務所運用的是第二版 OASIS 標準。

另請參閱