Sử dụng API web trình kiểm tra Power Apps
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 qua chi tiết về cách tương tác ở mức thấp nhất với API web, thay vào đó 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 đủ có sẵn trong Thư viện PowerShell. 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 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à việc phân tích giải pháp có thể dẫn đến một quá trình kéo dài. Thông thường, có thể mất sáu mươi (60) giây đến tối đa năm (5) phút tùy thuộc vào nhiều yếu tố khác nhau, chẳng hạn như số lượng, kích thước và độ phức tạp của các 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ã 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:
- Khu vực địa lý nào?
- Phiên bản nào?
- Những bộ quy tắc và quy tắc nào?
- ID đối tượng thuê của bạn là gì?
Hãy tham khảo các bài viết sau để biết tài liệu về từng API:
Truy xuất danh sách các bộ quy tắc
Truy xuất danh sách các quy tắc
Tải tệp lên
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ụ người kiểm tra Power Apps , 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. 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 nhất định 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ó một phiên bản dịch vụ khác nhau được triển khai tại bất kỳ thời điểm nào. 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 | Pháp | france.api.advisor.powerapps.com |
| Công khai | Sản xuất | Đức | germany.api.advisor.powerapps.com |
| Công khai | Sản xuất | Các Tiểu vương quốc Ả Rập Thống nhất | unitedarabemirates.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Thụy Sĩ | switzerland.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Nam Phi | southafrica.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Hàn Quốc | korea.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Na-uy | norway.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Singapore | singapore.api.advisor.powerapps.com |
| Công cộng | Sản xuất | Thụy Điển | sweden.api.advisor.powerapps.com |
| Công cộng | Sả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 đưa tham số chuỗi truy vấn phiên bản api vào phiên bản API mong muốn. Phiên bản API hiện tại là 2.0 cho các 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 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. Bạn 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 đưa ra các thay đổi vi phạm. 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 hoặc xóa, 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 bất kỳ thay đổi nào. 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 trình 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. Ứng dụng được phát hành trên AppSource được yêu cầu phải đáp ứng một tiêu chuẩn chất lượng cao. Bộ quy tắc chứng nhận AppSource chứa các quy tắc nằm trong 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. Một số AppSource quy tắc chứng nhận dễ xảy ra kết quả dương tính giả hơn và có thể cần được chú ý nhiều hơn để giải quyết.
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 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 OAuth nhưng tất cả các API khác đều yêu cầu mã thông báo. 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 người kiểm tra để biết thêm thông tin. Sau đây là 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/"
Sau khi có thông tin này, bạn có thể chọn sử dụng Thư viện xác thực Microsoft (MSAL) hoặc một số cơ chế khác để lấy mã thông báo. Sau đây là 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 API Web Mẫu bắt đầu nhanh.
Sau khi nhận được mã thông báo, bạn nên cung cấp mã thông báo tương tự cho các cuộc 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ể đảm bảo có được mã thông báo mới vì lý do bảo mật.
An ninh vận tải
Để mã hóa tốt nhất, dịch vụ kiểm tra chỉ hỗ trợ liên lạc bằng cách sử dụng Bảo mật lớp vận chuyển (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ụ sử dụng phiên bản hai của tiêu chuẩn OASIS.
Xem thêm
Truy xuất danh sách các bộ quy tắc
Truy xuất danh sách các quy tắc
Tải tệp lên
Gọi phân tích
Kiểm tra trạng thái phân tích
Phản hồi
Sắp ra mắt: Trong năm 2024, chúng tôi sẽ dần gỡ bỏ Sự cố với GitHub dưới dạng cơ chế phản hồi cho nội dung và thay thế bằng hệ thống phản hồi mới. Để biết thêm thông tin, hãy xem: https://aka.ms/ContentUserFeedback.
Gửi và xem ý kiến phản hồi dành cho