Usar a API Web do verificador do Power Apps

Artigo
05/01/2024

O verificador do Power Apps API Web fornece um mecanismo para executar verificações de análise estática em relação a personalizações e extensões da plataforma Microsoft Dataverse. Ele está disponível para que criadores e desenvolvedores executem verificações de análise estática detalhadas em suas soluções em relação a um conjunto de regras de práticas recomendadas para identificar rapidamente padrões problemáticos. O serviço fornece a lógica para o recurso do verificador de solução no portal do criador do Power Apps e está incluído como parte da automação para aplicativos enviados para o AppSource. Interagir com o serviço diretamente desta forma permite a análise das soluções incluídas como parte de ambientes locais (todas as versões compatíveis) e online.

Para obter informações sobre o uso do serviço do verificador do código do PowerShell, consulte Trabalhar com soluções usando o PowerShell.

Observação

O uso do verificador do Power Apps não garante que a importação de uma solução será bem-sucedida. As verificações de análise estática realizadas com a solução não conhecem o estado configurado do ambiente de destino e o sucesso da importação pode depender de outras soluções ou configurações no ambiente.

Abordagens alternativas

Antes de ler os detalhes de como interagir no nível mais baixo com as APIs Web, use o módulo do PowerShell, Microsoft.PowerApps.Checker.PowerShell, em vez disso. É uma ferramenta com suporte total e está disponível na Galeria do PowerShell. De acordo com a atual restrição, é necessário ter o Windows PowerShell. Caso não seja possível atender a esse requisito, a interação direta com as APIs provavelmente será a melhor abordagem.

Introdução

É importante observar que uma análise da solução pode resultar em um processo de execução prolongada. Normalmente, pode levar de sessenta (60) segundos até mais de cinco (5) minutos, dependendo de vários fatores, como número, tamanho e complexidade das personalizações e códigos. O fluxo da análise tem várias etapas e é assíncrono, começando com um trabalho de análise com a API de status sendo usada para consultar a conclusão do trabalho. Um fluxo de exemplo para uma análise é o seguinte:

Obter um token OAuth
Upload de chamada (para cada arquivo em paralelo)
Análise de chamada (inicia o trabalho de análise)
Status da chamada até a conclusão (loop com uma pausa entre chamadas até a conclusão ser sinalizada ou os limites serem atingidos)
Fazer download do(s) resultado(s) do URI de SAS fornecido

Algumas variações são:

Inclua uma pesquisa do conjunto de regras ou das regras como uma pré-etapa. No entanto, seria um pouco mais rápido transmitir uma ID de conjunto de regras configurada ou codificada. Recomendamos usar um conjunto de regras que atenda às suas necessidades.
Você pode optar por não usar o mecanismo de upload (consulte o upload para obter limitações).

Você precisará determinar os seguintes requisitos:

Qual geografia?
Qual versão?
Quais conjuntos de regras e quais regras?
Qual é a ID do locatário?

Consulte os seguintes artigos para obter a documentação sobre as APIs individuais:

Recuperar a lista de conjuntos de regras
Recuperar a lista de regras
Carregar um arquivo
Invocar análise
Verificar o status da análise

Determinar uma geografia

Ao interagir com o serviço do verificador do Power Apps, os arquivos são armazenados temporariamente no Azure com os relatórios gerados. Ao usar uma API específica para a geografia, é possível controlar onde os dados são armazenados. As solicitações para um ponto de extremidade geográfico são encaminhadas a uma instância regional com base no melhor desempenho (latência para o solicitante). Depois que uma solicitação entra em uma instância de serviço regional, todos os dados de processamento e persistentes permanecem nessa região específica. Algumas respostas da API retornarão URLs de instância regional para solicitações subsequentes, uma vez que um trabalho de análise é roteado para uma região específica. Cada geografia pode ter uma versão diferente do serviço implantado em qualquer ponto no tempo. O uso de diferentes versões de serviço se deve ao processo de implantação segura em vários estágios, que garante a total compatibilidade da versão. Portanto, a mesma geografia deve ser usada para cada chamada de API no ciclo de vida da análise e pode reduzir o tempo de execução geral, já que os dados não precisam percorrer distâncias tão grandes na rede. Veja a seguir as geografias disponíveis:

Data center do Azure	Nome	Geografia	URI base
Setor Público	Versão preliminar	Estados Unidos	unitedstatesfirstrelease.api.advisor.powerapps.com
Setor Público	Produção	Estados Unidos	unitedstates.api.advisor.powerapps.com
Setor Público	Produção	Europa	europe.api.advisor.powerapps.com
Setor Público	Produção	Ásia	asia.api.advisor.powerapps.com
Setor Público	Produção	Austrália	australia.api.advisor.powerapps.com
Setor Público	Produção	Japão	japan.api.advisor.powerapps.com
Setor Público	Produção	Índia	india.api.advisor.powerapps.com
Setor Público	Produção	Canadá	canada.api.advisor.powerapps.com
Setor Público	Produção	América do Sul	southamerica.api.advisor.powerapps.com
Setor Público	Produção	Reino Unido	unitedkingdom.api.advisor.powerapps.com
Setor Público	Produção	França	france.api.advisor.powerapps.com
Pública	Produção	Alemanha	germany.api.advisor.powerapps.com
Pública	Produção	Emirados Árabes Unidos	unitedarabemirates.api.advisor.powerapps.com
Pública	Produção	Suíça	switzerland.api.advisor.powerapps.com
Pública	Produção	África do Sul	southafrica.api.advisor.powerapps.com
Pública	Produção	Coreia do Sul	korea.api.advisor.powerapps.com
Pública	Produção	Noruega	norway.api.advisor.powerapps.com
Pública	Produção	Cidade de Singapura	singapore.api.advisor.powerapps.com
Pública	Produção	Suécia	sweden.api.advisor.powerapps.com
Pública	Produção	US Government	gov.api.advisor.powerapps.us
Setor Público	Produção	Governo dos EUA L4	high.api.advisor.powerapps.us
Setor Público	Produção	Governo dos EUA L5 (DOD)	mil.api.advisor.appsplatform.us
Setor Público	Produção	China operado pela 21Vianet	china.api.advisor.powerapps.cn

Nota

Você pode optar por usar a geografia de visualização para incorporar os recursos mais recentes e as alterações antes. No entanto, observe que a visualização usa somente as regiões do Azure nos Estados Unidos.

Controle de versão

Embora não seja obrigatório, recomenda-se incluir o parâmetro da string de consulta da versão da API na versão da API desejada. A versão atual da API é 2.0 para conjuntos de regras e regras e 1.0 para todas as outras solicitações. Por exemplo, o conjunto de regras a seguir é uma solicitação HTTP especificando o uso da versão de API 2.0:

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

Caso ela não seja fornecida, a versão de API será usada por padrão. Recomendamos o número de versão explícito, pois a versão será incrementada caso alterações interruptivas sejam introduzidas. Se o número de versão for especificado em uma solicitação, o suporte à compatibilidade com versões anteriores (numericamente maiores) será mantido.

Conjuntos de regras e regras

O verificador do Power Apps requer uma lista de regras quando executado. Essas regras podem ser fornecidas na forma de regras individuais ou em um agrupamento de regras, conhecido como conjunto de regras. Um conjunto de regras é uma forma conveniente de especificar um grupo de regras, em vez de especificar cada uma delas individualmente. Por exemplo, o recurso do verificador da solução usa um conjunto de regras chamado de Verificador da Solução. Conforme novas regras são adicionadas ou removidas, o serviço inclui essas alterações automaticamente sem exigir alterações pelo aplicativo de consumo. Se você exigir que a lista de regras não seja alterada automaticamente, conforme descrito acima, as regras poderão ser especificadas individualmente. Os conjuntos de regras podem ter uma ou mais regras sem limite. Uma regra pode estar em nenhum ou em vários conjuntos de regras. Você pode obter uma lista de todos os conjuntos de regras chamando a API da seguinte maneira: [Geographical URL]/api/ruleset. Este ponto de extremidade requer autenticação.

Conjunto de regras do verificador da solução

O conjunto de regras do verificador da solução contém um conjunto de regras impactantes com chances limitadas para falsos positivos. Se estiver executando uma análise em uma solução existente, recomendamos iniciar com este conjunto de regras. Este conjunto de regras é usado pelo recurso do verificador da solução.

Conjunto de regras de certificação do AppSource

Ao publicar aplicativos no AppSource, é necessário certificar o aplicativo. Os aplicativos publicados no AppSource devem atender a um alto padrão de qualidade. O conjunto de regras de certificação do AppSource contém as regras que fazem parte do conjunto de regras do verificador da solução, mais outras regras adicionais para garantir que somente aplicativos de alta qualidade sejam publicados na loja. Algumas das regras de certificação do AppSource são mais propensas a falsos positivos e podem exigir mais atenção para serem resolvidas.

Encontre a ID do locatário

A ID do seu locatário é necessária par interagir com as APIs que exigem um token. Consulte este artigo para ver detalhes sobre como obter a ID de locatário. Você também pode usar comandos do PowerShell para recuperar a ID do locatário. O exemplo a seguir aplica cmdlets no módulo do AzureAD.

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

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

A ID do locatário é o valor da propriedade ObjectId retornada de Get-AzureADTenantDetail. Também é possível vê-la após fazer logon usando o cmdlet Connect-AzureAD na saída do cmdlet. Neste caso, será chamada de TenantId.

Autenticação e autorização

A consulta de regras e conjuntos de regras não exige um token OAuth, mas todas as demais APIs exigem o token. As APIs oferecem suporte à descoberta de autorização chamando todas as APIs que exigem um token. A resposta é um código de status HTTP de 401 com um cabeçalho WWW-Authenticate, o URI de autorização e a ID do recurso. Você também deve fornecer a ID do locatário no cabeçalho x-ms-tenant-id. Consulte Autenticação e autorização do verificador do Power Apps para obter mais informações. A seguir está um exemplo do cabeçalho de reposta retornado de uma solicitação de API:

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

Após obter essas informações, você pode optar por usar a Biblioteca de Autenticação da Microsoft (MSAL) ou outro mecanismo para obter o token. Veja um exemplo de como isso pode ser feito usando C# e a biblioteca 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();

Para obter o código funcional completo, consulte a API da Web Exemplo do Início rápido.

Depois de adquirir o token, recomendamos fornecer o mesmo token em chamadas subsequentes no ciclo de vida da solicitação. No entanto, mais solicitações podem garantir um novo token por motivos de segurança.

Segurança de transporte

Para a melhor criptografia, o serviço do verificador oferece suporte a somente comunicações que usam o Transport Layer Security (TLS) 1.2 e superior. Para obter orientações sobre as práticas recomendadas do .NET para TLS, consulte as Práticas recomendadas do Transport Layer Security (TLS) com o .NET Framework.

Formatar relatório

O resultado da análise da solução é um arquivo zip que contém um ou mais relatórios em um formato JSON padronizado. O formato do relatório é baseado em resultados de análise estática, chamados de SARIF (Static Analysis Results Interchange Format). Existem ferramentas disponíveis para visualizar e interagir com documentos SARIF. Consulte este site para obter detalhes. O serviço usa a versão dois do padrão OASIS.

Confira também