Sử dụng API web trình kiểm tra Power Apps

Bài viết
10/16/2024

API web trình kiểm tra của Power Apps cung cấp một cơ chế để chạy kiểm tra phân tích tĩnh đối với các tùy chỉnh và tiện ích mở rộng cho nền tảng Microsoft Dataverse. Người tạo và nhà phát triển có thể thực hiện kiểm tra phân tích tĩnh đa dạng trên các giải pháp của họ so với bộ quy tắc phương pháp tốt nhất để nhanh chóng phát hiện các mẫu có vấn đề này. Dịch vụ này cung cấp logic cho tính năng kiểm tra giải pháp trong cổng thông tin người tạo Power Apps và được bao gồm như là một phần của tự động hóa cho đơn đăng ký được gửi đến AppSource. Tương tác trực tiếp với dịch vụ theo cách này cho phép phân tích các giải pháp được đưa vào như một phần của tại chỗ (tất cả các phiên bản được hỗ trợ) và môi trường trực tuyến.

Để biết thông tin về cách sử dụng dịch vụ kiểm tra từ mã PowerShell, hãy tham khảo Làm việc với các giải pháp bằng PowerShell.

Lưu ý

Sử dụng trình kiểm tra Power Apps không đảm bảo rằng quá trình nhập giải pháp sẽ thành công. Việc kiểm tra phân tích tĩnh được thực hiện đối với giải pháp không biết trạng thái được cấu hình của môi trường đích và việc nhập thành công có thể phụ thuộc vào các giải pháp hoặc cấu hình khác trong môi trường.

Cách tiếp cận khác

Trước khi đọc chi tiết về cách tương tác ở cấp độ thấp nhất với API web, hãy cân nhắc sử dụng mô-đun PowerShell của chúng tôi, Microsoft.PowerApps.Checker.PowerShell. Đây là một công cụ được hỗ trợ đầy đủ và có sẵn trong PowerShell Gallery. Hạn chế hiện tại là mô-đun này yêu cầu Windows PowerShell. Nếu không thể đáp ứng được yêu cầu này thì tương tác trực tiếp với API là cách tiếp cận tốt nhất.

Bắt đầu

Điều quan trọng cần lưu ý là quá trình phân tích giải pháp có thể kéo dài. Thông thường, quá trình này có thể mất từ sáu mươi (60) giây đến hơn năm (5) phút tùy thuộc vào nhiều yếu tố như số lượng, kích thước và độ phức tạp của tùy chỉnh và mã. Luồng phân tích có nhiều bước và không đồng bộ bắt đầu bằng việc bắt đầu một công việc phân tích với API trạng thái được sử dụng để truy vấn để hoàn thành công việc. Một luồng ví dụ cho một phân tích như sau:

Nhận một mã thông báo OAuth
Gọi lệnh tải lên (cho mỗi tệp song song)
Gọi lệnh phân tích (bắt đầu công việc phân tích)
Gọi trạng thái cho đến khi kết thúc (lặp lại với một khoảng dừng ở giữa các cuộc gọi cho đến khi kết thúc được báo hiệu hoặc ngưỡng được đáp ứng)
Tải xuống các kết quả từ URI SAS được cung cấp

Một vài biến thể là:

Bao gồm tra cứu các quy tắc hoặc quy tắc như một bước trước. Tuy nhiên, sẽ nhanh hơn một chút để vượt qua ID bộ quy tắc được cấu hình hoặc mã hóa cứng. Bạn nên sử dụng một bộ quy tắc đáp ứng nhu cầu của bạn.
Bạn có thể chọn không sử dụng cơ chế tải lên (xem phần tải lên để biết các giới hạn).

Bạn cần xác định các yêu cầu sau:

Địa lý nào?
Phiên bản nào?
Bộ quy tắc và luật lệ nào?
Mã số người thuê nhà của bạn là gì?

Tham khảo các bài viết sau để biết tài liệu về từng API:

Lấy danh sách các bộ quy tắc
Lấy danh sách các quy tắc
Tải lên một tập tin
Gọi phân tích
Kiểm tra trạng thái phân tích

Xác định khu vực địa lý

Khi bạn tương tác với dịch vụ kiểm tra, các tệp sẽ được lưu trữ tạm thời trong Azure cùng với các báo cáo được tạo. Power Apps Bằng cách sử dụng API cụ thể theo khu vực địa lý, bạn có thể kiểm soát nơi dữ liệu được lưu trữ. Các yêu cầu đến một điểm cuối địa lý được chuyển đến một phiên bản khu vực dựa trên hiệu suất tốt nhất (độ trễ đối với người yêu cầu). Khi một yêu cầu đi vào phiên bản dịch vụ khu vực, tất cả dữ liệu đang xử lý và liên tục vẫn nằm trong khu vực cụ thể đó. Một số phản hồi API trả về URL phiên bản khu vực cho các yêu cầu tiếp theo sau khi công việc phân tích được chuyển đến một khu vực cụ thể. Mỗi khu vực địa lý có thể có phiên bản dịch vụ khác nhau được triển khai tại một thời điểm nhất định. Việc sử dụng các phiên bản dịch vụ khác nhau là do quy trình triển khai an toàn nhiều giai đoạn, đảm bảo khả năng tương thích của phiên bản đầy đủ. Do đó, cùng một vị trí địa lý nên được sử dụng cho mỗi lệnh gọi API trong vòng đời phân tích và có thể giảm tổng thời gian thực thi vì dữ liệu có thể không phải di chuyển quá xa. Sau đây là các khu vực địa lý có sẵn:

Trung tâm dữ liệu Azure	Tên	Vùng địa lý	URI gốc
Công khai	Xem trước	Hoa Kỳ	unitedstatesfirstrelease.api.advisor.powerapps.com
Công khai	Sản xuất	Hoa Kỳ	unitedstates.api.advisor.powerapps.com
Công khai	Sản xuất	Châu Âu	europe.api.advisor.powerapps.com
Công khai	Sản xuất	Châu Á	asia.api.advisor.powerapps.com
Công khai	Sản xuất	Australia	australia.api.advisor.powerapps.com
Công khai	Sản xuất	Nhật Bản	japan.api.advisor.powerapps.com
Công khai	Sản xuất	Ấn Độ	india.api.advisor.powerapps.com
Công khai	Sản xuất	Canada	canada.api.advisor.powerapps.com
Công khai	Sản xuất	Nam Mỹ	southamerica.api.advisor.powerapps.com
Công khai	Sản xuất	Vương quốc Anh	unitedkingdom.api.advisor.powerapps.com
Công khai	Sản xuất	Pháp	france.api.advisor.powerapps.com
Công khai	Sản xuất	Đức	germany.api.advisor.powerapps.com
Công khai	Sản xuất	Các Tiểu vương quốc Ả Rập Thống nhất	unitedarabemirates.api.advisor.powerapps.com
Công cộng	Sản xuất	Thụy Sĩ	switzerland.api.advisor.powerapps.com
Công cộng	Sản xuất	Nam Phi	southafrica.api.advisor.powerapps.com
Công cộng	Sản xuất	Hàn Quốc	korea.api.advisor.powerapps.com
Công cộng	Sản xuất	Na-uy	norway.api.advisor.powerapps.com
Công cộng	Sản xuất	Singapore	singapore.api.advisor.powerapps.com
Công cộng	Sản xuất	Thụy Điển	sweden.api.advisor.powerapps.com
Công cộng	Sản xuất	US Government	gov.api.advisor.powerapps.us
Công khai	Sản xuất	Cơ quan Chính phủ Hoa Kỳ L4	high.api.advisor.powerapps.us
Công khai	Sản xuất	Cơ quan Chính phủ Hoa Kỳ L5 (DOD)	mil.api.advisor.appsplatform.us
Công khai	Sản xuất	Trung Quốc do 21Vianet vận hành	china.api.advisor.powerapps.cn

Lưu ý

Bạn có thể chọn sử dụng khu vực địa lý xem trước để kết hợp các tính năng mới nhất và thay đổi trước đó. Tuy nhiên, lưu ý rằng bản xem trước chỉ sử dụng các vùng Azure Hoa Kỳ.

Tạo phiên bản

Mặc dù không bắt buộc, nhưng bạn nên bao gồm tham số chuỗi truy vấn api-version với phiên bản API mong muốn. Phiên bản API hiện tại là 2.0 cho bộ quy tắc và quy tắc và 1.0 cho tất cả các yêu cầu khác. Ví dụ: bộ quy tắc sau đây là yêu cầu HTTP chỉ định sử dụng phiên bản API 2.0:

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

Nếu không được cung cấp, phiên bản API mới nhất sẽ được sử dụng theo mặc định. Nên sử dụng số phiên bản rõ ràng vì phiên bản sẽ tăng lên nếu có những thay đổi đột ngột. Nếu số phiên bản được chỉ định trong yêu cầu, hỗ trợ tương thích ngược trong các phiên bản (lớn hơn về số lượng) sau này sẽ được duy trì.

Bộ quy tắc và quy tắc

Công cụ kiểm tra Power Apps yêu cầu một danh sách các quy tắc khi chạy. Các quy tắc này có thể được cung cấp dưới dạng các quy tắc riêng lẻ hoặc một nhóm các quy tắc, được gọi là bộ quy tắc. Bộ quy tắc là một cách thuận tiện để chỉ định một nhóm quy tắc thay vì phải chỉ định từng quy tắc riêng lẻ. Ví dụ: tính năng kiểm tra giải pháp sử dụng bộ quy tắc có tên Kiểm tra giải pháp. Khi các quy tắc mới được thêm vào hoặc xóa đi, dịch vụ sẽ tự động bao gồm những thay đổi này mà không yêu cầu ứng dụng sử dụng phải thay đổi bất kỳ điều gì. Nếu bạn yêu cầu danh sách các quy tắc không tự động thay đổi như được mô tả ở trên, thì các quy tắc có thể được chỉ định riêng. Các bộ quy tắc có thể có một hoặc nhiều quy tắc không có giới hạn. Một quy tắc có thể không có hoặc có nhiều bộ quy tắc. Bạn có thể nhận danh sách tất cả các quy tắc bằng cách gọi API như sau: [Geographical URL]/api/ruleset. Điểm cuối này hiện yêu cầu xác thực.

Bộ quy tắc kiểm tra giải pháp

Bộ quy tắc kiểm tra giải pháp chứa một tập hợp các quy tắc có tác động hạn chế kết quả dương tính giả. Nếu chạy phân tích dựa trên giải pháp hiện có, bạn nên bắt đầu với bộ quy tắc này. Bộ quy tắc này được sử dụng bởi tính năng kiểm tra giải pháp.

Bộ quy tắc chứng nhận AppSource

Khi phát hành ứng dụng trên AppSource, ứng dụng của bạn phải được chứng nhận. Các ứng dụng được công bố trên AppSource phải đáp ứng tiêu chuẩn chất lượng cao. Bộ quy tắc chứng nhận bao gồm các quy tắc là một phần của bộ quy tắc kiểm tra giải pháp, cùng với các quy tắc khác để đảm bảo chỉ những ứng dụng chất lượng cao mới được xuất bản trên cửa hàng. AppSource Một số quy tắc chứng nhận dễ đưa ra kết quả dương tính giả và có thể cần được chú ý nhiều hơn để giải quyết. AppSource

Tìm ID đối tượng thuê của bạn

ID đối tượng thuê của bạn là cần thiết để tương tác với các API yêu cầu mã thông báo. Tham khảo bài viết này để biết chi tiết về cách lấy ID đối tượng thuê. Bạn cũng có thể sử dụng các lệnh PowerShell để lấy ID đối tượng thuê. Ví dụ sau đây áp dụng các lệnh ghép ngắn trong mô-đun AzureAD.

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

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

ID đối tượng thuê là giá trị của thuộc tính ObjectId được trả lại từ Get-AzureADTenantDetail. Bạn cũng có thể thấy giá trị đó sau khi đăng nhập bằng lệnh ghép ngắn Connect-AzureAD trong đầu ra lệnh ghép ngắn. Trong trường hợp này, nó sẽ được đặt tên là TenantId.

Xác thực và ủy quyền

Việc truy vấn các quy tắc và bộ quy tắc không yêu cầu mã thông báo, nhưng tất cả các API khác đều yêu cầu mã thông báo. OAuth Các API hỗ trợ phát hiện ủy quyền bằng cách gọi bất kỳ API nào yêu cầu mã thông báo. Phản hồi là mã trạng thái HTTP trái phép 401 với tiêu đề WWW-Authenticate, URI ủy quyền và ID tài nguyên. Bạn cũng nên cung cấp ID đối tượng thuê của mình trong tiêu đề x-ms-tenant-id. Tham khảo Power Apps Xác thực và ủy quyền của trình kiểm tra để biết thêm thông tin. Sau đây là một ví dụ về tiêu đề phản hồi được trả về từ yêu cầu API:

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

Khi đã có thông tin này, bạn có thể chọn sử dụng Microsoft Thư viện xác thực (MSAL) hoặc một số cơ chế khác để lấy mã thông báo. Sau đây là một ví dụ về cách thực hiện việc này bằng C# và thư viện 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();

Để biết mã hoạt động đầy đủ, hãy xem mẫu QuickStart của Web API.

Sau khi đã có được mã thông báo, bạn nên cung cấp cùng một mã thông báo cho các lần gọi tiếp theo trong vòng đời yêu cầu. Tuy nhiên, nhiều yêu cầu hơn có thể cần phải có mã thông báo mới vì lý do bảo mật.

An ninh vận tải

Để có mã hóa tốt nhất, dịch vụ kiểm tra chỉ hỗ trợ liên lạc bằng Giao thức bảo mật Transport tầng (TLS) 1.2 trở lên. Để được hướng dẫn về biện pháp thực hành .NET tốt nhất vềTLS, hãy tham khảo Các biện pháp thực hành tốt nhất về Bảo mật lớp vận chuyển (TLS) với .NET Framework.

Định dạng báo cáo

Kết quả của phân tích giải pháp là một tệp zip chứa một hoặc nhiều báo cáo theo định dạng JSON được chuẩn hóa. Định dạng báo cáo dựa trên kết quả phân tích tĩnh được gọi là Định dạng trao đổi kết quả phân tích tĩnh (SARIF). Có các công cụ có sẵn để xem và tương tác với các tài liệu SARIF. Tham khảo tranng web này để biết chi tiết. Dịch vụ này sử dụng phiên bản thứ hai của tiêu chuẩn OASIS.

Xem thêm