Utilizar a API Web do verificador do Power Apps

Artigo
02/07/2024

A API Web do verificador do Power Apps fornece um mecanismo para executar verificações de análise estática em personalizações e extensões na plataforma do Microsoft Dataverse. Está disponível para os criadores e programadores para executar verificações de análise estática avançada em soluções de um conjunto de regras de melhores práticas para identificar rapidamente os padrões problemáticos. O serviço fornece a lógica para a funcionalidade do verificador de soluções no portal do fabricante do Power Apps, e é incluído como parte da automatização para as aplicações submetidas ao AppSource. A interação direta com o serviço desta forma permite a análise das soluções que estão incluídas como parte dos ambientes no local (todas as versões suportada) e online.

Para obter informações sobre como utilizar o serviço de verificação a partir do código do PowerShell, consulte Trabalhar com soluções utilizando o PowerShell.

Nota

A utilização do verificador do Power Apps não garante que uma importação da solução seja bem sucedida. As verificações de análise estáticas realizadas contra a solução desconhecem o estado configurado do ambiente de destino e o sucesso das importações pode depender de outras soluções ou configurações no ambiente.

Abordagens alternativas

Antes de ler os detalhes sobre como interagir no nível mais baixo com as API Web, considere usar o nosso módulo PowerShell, Microsoft.PowerApps.Checker.PowerShell. É uma ferramenta totalmente suportada que está disponível na Galeria do PowerShell. Na restrição atual, exige o Windows PowerShell. Se não conseguir cumprir este requisito, a interação direta com as API deve ser a melhor abordagem.

Começar

É importante notar que uma análise das soluções pode resultar num longo processo de execução. Normalmente, pode demorar de sessenta (60) segundos até cinco (5) minutos, dependendo de vários fatores, como o número, o tamanho e a complexidade das personalizações e do código. O fluxo de análise é um processo que envolve vários passos e assíncrono que começa com o início de uma tarefa de análise com a API de estado a ser utilizada para consultar a conclusão das tarefas. Segue-se um fluxo de exemplo para análise:

Obter um token de OAuth
Carregamento de chamadas (para cada ficheiros em paralelo)
Análise de chamadas (inicia a tarefa de análise)
Estado da chamada até ser terminada (ciclo com uma pausa entre chamadas até o fim ser assinalado ou serem cumpridos os limiares)
Transferir os resultados a partir do URI de SAS fornecido

Algumas variações:

Inclua uma pesquisa do conjunto de regras ou regras como passo prévio. No entanto, seria ligeiramente mais rápido transmitir num ID de conjunto de regras configurado ou codificado. Recomenda-se que utilize um conjunto de regras que satisfaça as suas necessidades.
Pode optar por não utilizar o mecanismo de carregamento (consulte a carga para conhecer as limitações).

Terá de determinar os seguintes requisitos:

Qual a geografia?
Qual a versão?
Quais os conjuntos de regras e regras?
Qual o seu ID de inquilino?

Consulte os seguintes artigos para ver a documentação sobre as API individuais:

Obter a lista de conjuntos de regras
Obter a lista de regras
Carregar um ficheiro
Invocar análise
Verificar o estado da análise

Determinar uma geografia

Quando interage com o serviço de verificação do Power Apps, os ficheiros são armazenados temporariamente no Azure, juntamente com os relatórios que são gerados. Ao utilizar uma API específica da geografia, poderá controlar onde os dados são armazenados. Os pedidos para um ponto final de geografia são encaminhados para um caso regional baseado no melhor desempenho (latência ao solicitador). Uma vez que um pedido entra numa instância de serviço regional, todos os dados de tratamento e persistência permanecem nessa região. Algumas respostas da API devolvem URL de instância regional para pedidos subsequentes assim que uma tarefa de análise seja encaminhada para uma região específica. Cada geografia pode ter uma versão diferente do serviço implementado num determinado momento. A utilização de versões de serviço diferentes deve-se ao processo de implementação segura em várias fases, que assegura a total compatibilidade entre versões. Assim, 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 global, uma vez que os dados podem não ter que viajar tão longe sobre o fio. Estão disponíveis as seguintes geografias:

Datacenter do Azure	Nome	Geografia	URI Base
Pública	Pré-visualizar	Estados Unidos	unitedstatesfirstrelease.api.advisor.powerapps.com
Pública	Produção	Estados Unidos	unitedstates.api.advisor.powerapps.com
Pública	Produção	Europa	europe.api.advisor.powerapps.com
Pública	Produção	Ásia	asia.api.advisor.powerapps.com
Pública	Produção	Austrália	australia.api.advisor.powerapps.com
Pública	Produção	Japão	japan.api.advisor.powerapps.com
Pública	Produção	Índia	india.api.advisor.powerapps.com
Pública	Produção	Canadá	canada.api.advisor.powerapps.com
Pública	Produção	América do Sul	southamerica.api.advisor.powerapps.com
Pública	Produção	Reino Unido	unitedkingdom.api.advisor.powerapps.com
Pública	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	Singapura	singapore.api.advisor.powerapps.com
Pública	Produção	Administração Pública dos EUA	gov.api.advisor.powerapps.us
Pública	Produção	US Government L4	high.api.advisor.powerapps.us
Pública	Produção	US Government L5 (DOD)	mil.api.advisor.appsplatform.us
Pública	Produção	China operado por 21Vianet	china.api.advisor.powerapps.cn

Nota

Pode optar por utilizar a geografia de pré-visualização para incorporar mais cedo as funcionalidades e alterações mais recentes. No entanto, note que a pré-visualização utiliza apenas as regiões do Azure nos Estados Unidos.

Controlo de Versão

Embora não seja obrigatório, recomenda-se incluir o parâmetro da cadeia de consulta da Versão da API com a versão de API pretendida. A versão atual da API é 2.0 para conjuntos de regras e regras e 1.0 para todos os outros pedidos. Por exemplo, o conjunto de regras seguinte é um pedido HTTP que especifica a utilização da versão 2.0 da API:

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

Se não for fornecido, por predefinição é utilizada a versão de API mais recente. Recomenda-se utilizar um número de versão explícito porque a versão é incrementada se forem introduzidas alterações interruptivas. Se o número de versão for especificado num pedido, será mantido suporte de retrocompatibilidade nas versões posteriores (numericamente superiores).

Conjuntos de regras e regras

O verificador do Power Apps necessita de uma lista de regras durante a execução. Estas regras podem ser fornecidas sob a forma de regras individuais ou de agrupamento de regras, referidas como conjunto de regras. Um conjunto de regras é uma forma prática de especificar um grupo de regras, em vez de ter de especificar cada regra individualmente. Por exemplo, a funcionalidade do verificador de soluções utiliza um conjunto de regras denominado Verificador de Soluções. À medida que são adicionadas ou removidas novas regras, o serviço inclui estas alterações automaticamente sem exigir qualquer alteração pela aplicação consumidora. Se exigir que a lista de regras não se altere 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 não estar em nenhum conjunto de regras ou em vários. Pode obter uma lista de todos os conjuntos de regras ao chamar a API da seguinte forma: [Geographical URL]/api/ruleset. Este ponto final necessita agora de autenticação.

Conjunto de regras do verificador de soluções

O conjunto de regras do verificador de soluções contém um conjunto de regras de grande impacto com hipóteses limitadas de gerar falsos positivos. Se estiver a executar análises em relação a uma solução existente, recomenda-se que comece com este conjunto de regras. Este conjunto de regras é utilizado pela funcionalidade do verificador de soluções.

Conjunto de regras de certificação do AppSource

Ao publicar aplicações no AppSource, tem de certificar a sua aplicação. As aplicações publicadas no AppSource são necessárias para cumprir um padrão de alta qualidade. O conjunto de regras da certificação do AppSource contém as regras que fazem parte do conjunto de regras do verificador de soluções, bem como outras regras para assegurar que só as aplicações de alta qualidade são publicadas na loja. Algumas regras de certificação do AppSource são mais propensas a falsos positivos e podem exigir mais atenção para a sua resolução.

Localizar o ID do inquilino

O ID do seu inquilino é necessária para interagir com as APIs que exigem um token. Consulte to este artigo para obter detalhes sobre como obter o ID do inquilino. Também pode utilizar os comandos do PowerShell para obter o ID do inquilino. O exemplo seguinte aplica os cmdlets ao módulo do AzureAD.

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

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

O ID do inquilino é o valor da propriedade ObjectId que é devolvido por Get-AzureADTenantDetail. Também pode vê-lo depois de iniciar sessão através do cmdlet Connect-AzureAD na saída do cmdlet. Neste caso, será denominado TenantId.

Autenticação e autorização

A consulta de regras e conjunto de regras não exige um token de OAuth, mas todas as outras API exigem o token. As APIs suportam a deteção da autorizações ao chamarem qualquer uma das APIs que exigem um token. A resposta é um código de estado HTTP não autorizado de 401 com um cabeçalho WWW-Authenticate, o URL de autorização e o ID do recurso. Também deve fornecer o seu ID de inquilino no cabeçalho x-ms-tenant-id. Consulte Autenticação e autorização do Verificador do Power Apps para obter mais informações. Segue-se um exemplo do cabeçalho de resposta devolvido por um pedido de API:

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

Quando tiver estas informações, pode optar por utilizar a Biblioteca de Autenticação da Microsoft (MSAL) ou algum outro mecanismo para adquirir o token. Segue-se um exemplo sobre como isto pode ser feito através de C# e da bibliotec 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 o código de trabalho integral, consulte o a API Web Amostra de início rápido.

Depois de adquirir o token, é aconselhável que forneça o mesmo token às chamadas subsequentes no ciclo de vida do pedido. No entanto, mais pedidos podem garantir a aquisição de um novo token por razões de segurança.

Segurança de transporte

Para obter a melhor encriptação da sua classe, o serviço do verificador suporta apenas as comunicações com Transport Layer Security (TLS) 1.2 e superiores. Para obter orientações sobre as melhores práticas do .NET com o TLS, consulte Melhores práticas do Transport Layer Security (TLS) com o .NET Framework.

Formato de relatório

O resultado da análise das soluções é um ficheiro zip que contém um ou mais relatórios num formato JSON padronizado. O formato do relatório baseia-se em resultados de análise estática referidos como Static Analysis Results Interchange Format (SARIF). Estão disponíveis ferramentas para ver e interagir com documentos SARIF. Consulte este Web site para obter detalhes. O serviço usa a versão dois do padrão OASIS.

Consulte também