แชร์ผ่าน

ใช้ API เว็บของตัวตรวจสอบ Power Apps

  • บทความ

API ตัวตรวจสอบเว็บ Power Apps มีกลไกในการเรียกใช้การตรวจสอบการวิเคราะห์แบบคงที่กับการปรับแต่ง และส่วนขยายให้กับแพลตฟอร์ม Microsoft Dataverse พร้อมใช้งานสำหรับผู้สร้างและผู้พัฒนา สามารถทำการตรวจสอบการวิเคราะห์สภาพสถิตย์จำนวนมากบนโซลูชันของพวกเขา โดยเทียบกับชุดกฎแนวทางปฏิบัติที่ดีที่สุด เพื่อระบุรูปแบบที่เป็นปัญหาเหล่านี้ได้อย่างรวดเร็ว บริการให้ตรรกะสำหรับ คุณสมบัติตัวตรวจสอบโซลูชัน ใน พอร์ทัล ผู้สร้าง Power Apps และรวมไว้เป็นส่วนหนึ่งของระบบอัตโนมัติสำหรับ ส่งโปรแกรมประยุกต์ไปยัง AppSource การโต้ตอบกับบริการโดยตรงในลักษณะนี้จะช่วยให้สามารถวิเคราะห์โซลูชันที่รวมเป็นส่วนหนึ่งภายในองค์กร (รุ่นที่รองรับทั้งหมด) และสภาพแวดล้อมออนไลน์

สำหรับข้อมูลเกี่ยวกับการใช้บริการตัวตรวจสอบจากโค้ด PowerShell โปรดดูที่ ทำงานกับโซลูชันที่ใช้ PowerShell

หมายเหตุ

  • การใช้การตรวจสอบ Power Apps ไม่รับประกันว่าการนำเข้าโซลูชันจะประสบความสำเร็จ การตรวจสอบการวิเคราะห์แบบคงที่ที่ดำเนินการกับโซลูชันไม่ทราบสถานะที่กำหนดค่าของสภาพแวดล้อมปลายทาง และความสำเร็จในการนำเข้าอาจขึ้นอยู่กับโซลูชันหรือการกำหนดค่าอื่น ๆ ในสภาพแวดล้อม

วิธีอื่น

ก่อนอ่านรายละเอียดวิธีการโต้ตอบในระดับต่ำสุดกับ API เว็บ ให้ลองใช้โมดูล PowerShell ของเรา Microsoft.PowerApps.Checker.PowerShell แทน ซึ่งเป็นเครื่องมือที่รองรับอย่างเต็มที่ที่มีอยู่ใน แกลลอรี PowerShell ข้อจำกัดปัจจุบันคือ ต้องใช้ Windows PowerShell หากไม่สามารถปฏิบัติตามข้อกำหนดนี้ได้ การโต้ตอบกับ API โดยตรงเป็นวิธีที่ดีที่สุด

เริ่มต้นใช้งาน

สิ่งสำคัญคือ ต้องทราบว่าการวิเคราะห์โซลูชันอาจส่งผลให้กระบวนการทำงานยาวนาน โดยทั่วไปอาจใช้เวลาหกสิบ (60) วินาทีขึ้นไปถึงห้า (5) นาที ขึ้นอยู่กับปัจจัยหลายประการ เช่น จำนวน ขนาด และความซับซ้อนของการปรับแต่ง และโค้ด โฟลว์การวิเคราะห์เป็นหลายขั้นตอน และเริ่มต้นแบบอะซิงโครนัส โดยเริ่มต้นงานการวิเคราะห์โดยใช้สถานะ API ที่ใช้ในการค้นหา เพื่อให้งานเสร็จสมบูรณ์ โฟลว์ตัวอย่างสำหรับการวิเคราะห์มีดังนี้:

  1. รับโทเค็น OAuth
  2. เรียกใช้อัปโหลด (สำหรับแต่ละไฟล์พร้อมกัน)
  3. เรียกใช้การวิเคราะห์ (เริ่มงานวิเคราะห์)
  4. เรียกใช้สถานะจนกว่าจะเสร็จสิ้น (วนซ้ำพร้อมกับหยุดชั่วคราวระหว่างการเรียกใช้ จนกว่าจะสิ้นสุดการส่งสัญญาณหรือเป็นไปตามเกณฑ์)
  5. ดาวน์โหลดผลลัพธ์จาก SAS URI ที่ให้ไว้

รูปแบบต่างๆ ได้แก่ :

  • รวมการค้นหาของชุดกฎ หรือกฎเป็นขั้นตอนล่วงหน้า อย่างไรก็ตาม อาจจะเร็วกว่าเล็กน้อยในการส่งผ่านรหัสชุดกฎที่กำหนดค่าหรือแบบเข้ารหัส ขอแนะนำให้คุณใช้ชุดกฎที่ตรงกับความต้องการของคุณ
  • คุณสามารถเลือกที่จะไม่ใช้กลไกการอัปโหลด (ดูข้อจำกัดการอัปโหลด)

คุณจะต้องตรวจสอบข้อกำหนดต่อไปนี้:

ดูที่บทความต่อไปนี้สำหรับเอกสารเกี่ยวกับ 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
สาธารณะ การใช้งานจริง US Government L4 high.api.advisor.powerapps.us
สาธารณะ การใช้งานจริง US Government L5 (DOD) mil.api.advisor.appsplatform.us
สาธารณะ การใช้งานจริง จีนดําเนินการโดย 21Vianet china.api.advisor.powerapps.cn

หมายเหตุ

คุณอาจเลือกที่จะใช้ภูมิศาสตร์ตัวอย่างเพื่อรวมคุณสมบัติล่าสุดและการเปลี่ยนแปลงก่อนหน้านี้ อย่างไรก็ตาม โปรดทราบว่าภาพตัวอย่างใช้ภูมิภาค Azure ของสหรัฐอเมริกาเท่านั้น

การกำหนดรุ่น

แม้ว่าจะไม่จำเป็นก็ตาม ขอแนะนำให้รวมพารามิเตอร์สตริงข้อความการสอบถามรุ่น API กับรุ่น API ที่ต้องการ API เวอร์ชันปัจจุบันคือ 2.0 สำหรับชุดกฎและกฎ และ 1.0 สำหรับคำขออื่นๆ ทั้งหมด ตัวอย่างเช่น ชุดกฎต่อไปนี้เป็นการร้องขอทาง HTTP ที่ระบุให้ใช้เวอร์ชัน API 2.0:

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

หากไม่ได้ระบุไว้ API เวอร์ชันล่าสุดจะถูกใช้เป็นค่าเริ่มต้น แนะนำให้ใช้หมายเลขเวอร์ชันที่ชัดเจน เนื่องจากเวอร์ชันจะเพิ่มขึ้น หากมีการแนะนำให้ใช้การเปลี่ยนแปลงแบบแยกย่อย หากระบุหมายเลขรุ่นในคำขอ การรองรับความเข้ากันได้แบบย้อนหลังในภายหลัง (มากกว่าตัวเลข) จะได้รับการดูแล

ชุดกฎและกฎ

ตัวตรวจสอบ Power Apps ต้องการรายการของกฎเมื่อเรียกใช้ กฎเหล่านี้สามารถจัดทำในรูปแบบของกฎส่วนบุคคลหรือการจัดกลุ่มของกฎที่เรียกว่า ชุดกฎ ชุดกฎ เป็นวิธีที่สะดวกในการระบุกลุ่มของกฎแทนที่จะต้องระบุแต่ละกฎ ตัวอย่างเช่น คุณสมบัติตัวตรวจสอบโซลูชันใช้ชื่อชุดกฎ ตัวตรวจสอบโซลูชัน เนื่องจากมีการเพิ่มหรือลบกฎใหม่ การบริการรวมการเปลี่ยนแปลงเหล่านี้โดยอัตโนมัติ โดยไม่ต้องมีการเปลี่ยนแปลงใด ๆ หากคุณต้องการให้รายการของกฎไม่เปลี่ยนแปลงโดยอัตโนมัติตามที่อธิบายไว้ข้างต้น คุณสามารถระบุกฎได้ทีละรายการ ชุดกฎสามารถมีกฎอย่างน้อยหนึ่งกฎโดยไม่จำกัด กฎไม่สามารถอยู่ในชุดกฎหรือชุดกฎหลายชุด คุณสามารถรับรายชื่อของชุดกฎทั้งหมดได้โดยการเรียก API ดังต่อไปนี้:[Geographical URL]/api/ruleset ตำแหน่งข้อมูลนี้ต้องการการรับรองความถูกต้อง

ชุดกฎตัวตรวจสอบโซลูชัน

ชุดกฎของตัวตรวจสอบโซลูชันประกอบด้วยชุดของกฎที่มีผลกระทบซึ่งมีโอกาสจำกัดสำหรับผลบวกเท็จ หากใช้การวิเคราะห์กับโซลูชันที่มีอยู่ แนะนำให้คุณเริ่มต้นด้วยชุดกฎนี้ นี่คือชุดกฎที่ใช้โดย คุณลักษณะตัวตรวจสอบโซลูชัน

ชุดกฎการรับรองของ AppSource

เมื่อเผยแพร่โปรแกรมประยุกต์บน AppSource คุณจะต้องรับรองโปรแกรมประยุกต์ของคุณ โปรแกรมประยุกต์เผยแพร่บน AppSource จะต้องมีมาตรฐานคุณภาพสูง ชุดกฎการรับรอง AppSource ประกอบด้วยกฎที่เป็นส่วนหนึ่งของชุดกฎการตรวจสอบโซลูชัน รวมถึงกฎอื่นๆ เพื่อให้แน่ใจว่ามีการเผยแพร่เฉพาะแอปพลิเคชันคุณภาพสูงในร้านค้า บางส่วนของกฎการรับรอง AppSource มีแนวโน้มที่จะเกิดผลบวกเท็จ และอาจต้องการความสนใจเพิ่มเติมเพื่อแก้ไข

ค้นหารหัสผู้เช่าของคุณ

จำเป็นต้องใช้รหัสของผู้เช่าของคุณเพื่อโต้ตอบกับ API ที่ต้องใช้โทเค็น อ้างถึง บทความนี้ สำหรับรายละเอียดเกี่ยวกับวิธีรับรหัสผู้เช่า คุณยังสามารถใช้คำสั่ง PowerShell เพื่อดึงข้อมูลรหัสผู้เช่า ตัวอย่างต่อไปนี้ใช้ cmdlet ใน โมดูล AzureAD

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

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

รหัสผู้เช่าคือ ค่าของคุณสมบัติ ObjectId ที่ส่งคืนจาก Get-AzureADTenantDetail คุณอาจเห็นหลังจากลงชื่อเข้าใช้โดยใช้ Connect-AzureAD cmdlet ในเอาต์พุต cmdlet ในกรณีนี้ จะตั้งชื่อเป็น TenantId

การอนุญาตและการรับรองความถูกต้อง

การค้นหากฎและชุดกฎไม่จำเป็นต้องมีโทเค็น OAuth แต่ API อื่น ๆ ทั้งหมดต้องใช้โทเค็น API สนับสนุนการค้นพบการอนุญาตโดยการเรียก API ใดๆ ที่ต้องใช้โทเค็น การตอบสนองเป็นรหัสสถานะ HTTP ที่ไม่ได้รับอนุญาต 401 ซึ่งมีส่วนหัว WWW-Authenticate URI การให้สิทธิ์และรหัสทรัพยากร คุณควรระบุรหัสผู้เช่าในส่วนหัว 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 Authentication Library (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 ตัวอย่างเริ่มต้นใช้งานด่วน

เมื่อคุณได้รับโทเค็นแล้ว ขอแนะนำให้คุณจัดทำโทเค็นแบบเดียวกันกับการโทรที่ตามมาในรอบการร้องขอ อย่างไรก็ตาม การร้องขอเพิ่มเติมอาจรับประกันว่าจะได้รับโทเค็นใหม่ด้วยเหตุผลด้านความปลอดภัย

ความปลอดภัยการขนส่ง

เพื่อการเข้ารหัสที่ดีที่สุดในระดับ บริการตรวจสอบรองรับการสื่อสารโดยใช้ Transport Layer Security (TLS) 1.2 ขึ้นไป สำหรับคำแนะนำเกี่ยวกับแนวปฏิบัติที่ดีที่สุดของ .NET เกี่ยวกับ TLS โปรดอ้างถึง แนวทางปฏิบัติที่ดีที่สุดของ Transport Layer Security (TLS) ด้วย .NET Framework

รูปแบบรายงาน

ผลลัพธ์ของการวิเคราะห์โซลูชันคือไฟล์ zip ที่มีหนึ่งรายงานขึ้นไปในรูปแบบ JSON มาตรฐาน รูปแบบรายงานขึ้นอยู่กับผลการวิเคราะห์แบบคงที่ที่อ้างถึงรูปแบบการแลกเปลี่ยนผลการวิเคราะห์แบบคงที่ (SARIF) มีเครื่องมือสำหรับดูและโต้ตอบกับเอกสาร SARIF อ้างอิงถึง เว็บไซต์ นี้สำหรับรายละเอียด บริการใช้จากเวอร์ชันสองของ มาตรฐาน OASIS

ดูเพิ่มเติม

เรียกใช้ชุดรายการของข้อกำหนด
เรียกใช้รายการของข้อกำหนด
อัปโหลดแฟ้ม
เรียกใช้การวิเคราะห์
ตรวจสอบสถานะการวิเคราะห์