Power Apps 검사기 웹 API 사용

아티클
05/01/2024

Power Apps 검사기 웹 API는 Microsoft Dataverse 플랫폼의 사용자 지정 및 확장에 대한 정적 분석 검사를 실행하는 메커니즘을 제공합니다. 제작자와 개발자는 모범 사례 규칙 세트에 따라 솔루션에 대한 풍부한 정적 분석 검사를 수행하여 이러한 문제 패턴을 신속하게 식별할 수 있습니다. 이 서비스는 Power Apps 제작자 포털의 솔루션 검사기 기능에 대한 논리를 제공하며 AppSource에 제출된 응용 프로그램의 자동화의 일부로 포함됩니다. 이러한 방식으로 서비스와 직접 상호 작용하면 온-프레미스(모든 지원되는 버전) 및 온라인 환경의 일부로 포함된 솔루션을 분석할 수 있습니다.

PowerShell 코드에서 검사기 서비스를 사용하는 방법에 대한 자세한 내용은 PowerShell을 사용하여 솔루션 작업을 참조하십시오.

참고

Power Apps 검사기는 솔루션 가져오기의 성공을 보장하지 않습니다. 솔루션에 대해 수행된 정적 분석 검사는 대상 환경의 구성된 상태를 알지 못하며 가져오기 성공 여부는 환경의 다른 솔루션이나 구성에 따라 달라질 수 있습니다.

대체 접근법

웹 API를 사용하여 가장 낮은 수준에서 상호작용하는 방법에 대한 세부 사항을 읽기 전에, 대신 PowerShell 모듈인 Microsoft.PowerApps.Checker.PowerShell을 사용하는 것을 고려하세요. PowerShell 갤러리에서 사용할 수 있는 완전히 지원되는 도구입니다. 현재 제한 사항은 Windows PowerShell이 필요하다는 것입니다. 이 요구 사항을 충족하지 못하면 API와 직접 상호 작용하는 것이 가장 좋습니다.

시작하기

솔루션 분석으로 인해 프로세스가 오래 실행될 수 있습니다. 숫자, 크기 및 사용자 지정 및 코드의 복잡성과 같은 다양한 요인에 따라 일반적으로 육십(60)초에서 오(5)분 이상이 소요될 수 있습니다. 분석 플로우는 작업 완료를 조회하는 데 사용되는 상태 API로 분석 작업을 시작하는 것으로 시작하여 다단계 및 비동기식입니다. 분석을 위한 예제 흐름은 다음과 같습니다.

OAuth 토큰을 얻으세요
통화 업로드(각 파일에 대해 병렬로)
통화 분석(분석 작업 시작)
완료될 때까지의 통화 상태(종료가 신호되거나 임계값이 충족될 때까지 통화 사이에 일시 정지된 루프)
제공된 SAS URI에서 결과 다운로드

몇 가지 변형:

사전 설정으로 규칙 세트 또는 규칙 조회를 포함합니다. 그러나 구성되거나 하드 코딩된 규칙 세트 ID를 전달하는 것이 약간 더 빠릅니다. 필요에 맞는 규칙 세트를 사용하는 것이 좋습니다.
업로드 메커니즘을 사용하지 않도록 선택할 수 있습니다(제한 사항은 업로드 참조).

다음 요구 사항을 결정해야 합니다.

어떤 지역인가요?
어떤 버전인가요?
어떤 규칙과 규칙을 말하나요?
세입자 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
공공 사업	생산	영국	southamerica.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
일반	생산	US 정부 기관용	gov.api.advisor.powerapps.us
공공 사업	생산	미국 정부 L4	high.api.advisor.powerapps.us
공공 사업	생산	미국 정부 L5(DOD)	mil.api.advisor.appsplatform.us
공공 사업	생산	중국 21Vianet이 운영함	china.api.advisor.powerapps.cn

노트

미리 보기 지리를 사용하여 최신 기능과 변경 사항을 이전에 통합하도록 선택할 수 있습니다. 그러나 미리 보기는 미국 Azure 지역만 사용합니다.

버전 관리

필수는 아니지만 api-version 쿼리 문자열 매개 변수를 원하는 API 버전과 함께 포함하는 것이 좋습니다. 현재 API 버전은 규칙 세트 및 규칙의 경우 2.0이고 기타 모든 요청의 경우 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 인증 규칙 세트에는 솔루션 검사기 규칙 세트의 일부인 규칙과 상점에 고품질 애플리케이션만 공개되도록 하는 다른 규칙이 포함됩니다. 일부 AppSource 인증 규칙은 오탐지 경향이 있으며 문제를 해결하기 위해 추가 주의가 필요할 수 있습니다.

테넌트 ID 찾기

토큰이 필요한 API와 상호 작용하려면 테넌트의 ID가 필요합니다. 테넌트 ID를 얻는 방법에 대한 자세한 내용은 이 문서를 참조하십시오. PowerShell 명령을 사용하여 테넌트 ID를 검색할 수도 있습니다. 다음 예제는 AzureAD 모듈의 cmdlet을 적용합니다.

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

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

테넌트 ID는 Get-AzureADTenantDetail에서 반환된 «ObjectId 속성의 값입니다. Cmdlet 출력에서 Connect-AzureAD cmdlet을 사용하여 로그인한 후에도 표시될 수 있습니다. 이 경우 이름은 TenantId입니다.

인증 및 권한 부여

규칙과 규칙 세트를 쿼리하는 데는 OAuth 토큰이 필요하지 않지만 다른 모든 API에는 토큰이 필요합니다. API는 토큰이 필요한 API를 호출하여 권한 부여 발견을 지원합니다. 응답은 WWW-Authenticate 헤더, 권한 부여 URI 및 리소스 ID를 가진 승인되지 않은 HTTP 상태 코드 401입니다. x-ms-tenant-id 헤더에 테넌트 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();

전체 작업 코드는 웹 API QuickStart 샘플을 참조하세요.

토큰을 획득한 후에는 요청 수명 주기의 후속 호출에 동일한 토큰을 제공하는 것이 좋습니다. 그러나 더 많은 요청이 있을 경우 보안상의 이유로 새 토큰을 획득해야 할 수도 있습니다.

전송 보안

동급 최고의 암호화를 위해 검사기 서비스는 TLS(Transport Layer Security) 1.2 이상을 사용하는 통신만 지원합니다. TLS와 관련된 .NET 모범 사례에 대한 지침은 .NET Framework를 사용한 TLS(Transport Layer Security) 모범 사례를 참조하십시오.

보고서 형식

솔루션 분석의 결과는 표준화된 JSON 형식의 하나 이상의 보고서를 포함하는 zip 파일입니다. 보고서 형식은 정적 분석 결과 교환 형식(SARIF)이라고 하는 정적 분석 결과를 기반으로 합니다. SARIF 문서를 보고 상호 작용할 수 있는 도구가 있습니다. 자세한 내용은 웹 사이트를 참조하십시오. 이 서비스는 OASIS 표준의 버전 2를 사용합니다.

참조 항목