Portais PowerApps – Use uma API Web para criar, atualizar e eliminar registos

Até agora (pré-versão 9.3.3.0), os Portais PowerApps e Power Pages só tinham um método para atualizar entidades de volta à base de dados, que era utilizar Formulários de Entidade. Isto tem sido severamente limitado no que pode ser feito com a interface do utilizador, onde as atualizações são necessárias. Tinha de utilizar Formulários de Entidade ou utilizar uma alternativa de trabalho desajeitada de uma entidade oculta formulada pela sua própria IU.

A boa notícia é que com a recente Disponibilidade Geral da API Web para Portais PowerApps, abriu-se todo um universo de possibilidades. Vamos analisar a forma como o utilizamos.

O que pode fazer?

O Portal API Web pode ser usado para criar, atualizar e eliminar registos. Também pode ser usado para associar e dissociar registos – estabelecer consultas ou relações de muitos para muitos

Que tal ler? A partir de 9.4.1.x isto foi possível e pode ser feito utilizando uma filtragem estilo OData v4 (com suporte para um conjunto limitado de operadores). No entanto, as abordagens anteriores que utilizavam Liquid e modelos Web para FetchXml continuam a ser possíveis.

Porquê utilizá-lo?

As páginas web do portal são bastante flexíveis no que pode ser alcançado; os modelos web abriram a possibilidade de reagir aos parâmetros da página, consultar a base de dados, e enviar resultados, seja HTML, JSON ou o que quer que seja, com base na lógica Liquid. Mas quando se trata de reescrever, em muitos casos, são necessárias ações como criar, atualizar e apagar que não estão ligadas a uma forma de entidade, e é aí que entra uma API Web.

Como a utilizo?

Existem três etapas essenciais na utilização do Portal API Web.

• Ativar a tabela (só pode ser uma entidade que armazena dados – contas, contactos, tabelas personalizadas são satisfatórias, mas não uma tabela de configuração do sistema, por exemplo, ler/escrever as tabelas adx_). Isto é feito através da adição de registos de configurações do site para ativar a tabela. Adicionar as seguintes configurações do site para o seu website:

1. Webapi//enabled = true
2. Webapi//fields. Use * para todos os campos ou uma lista com os nomes dos campos separados por vírgula
3. Webapi/error/innererror. Opcional: definir para “true” para mais erros.

Por exemplo:

• Definir permissões para a tabela, ativando as permissões para read/write/delete/append/append to. E para a permissão da tabela, lembre-se de lhes dar uma função na web, tal como Utilizadores Autenticados.
• Escrever código para utilizar a API Web

A Microsoft forneceu de forma útil uma função Wrapper AJAX para facilitar os comandos API Web. Insira-o num modelo web e inclua-o em modelos web onde utilizará a API Web.

Por exemplo, obter o seguinte código num modelo web, chamar-lhe “WebAPIAJAX”. No seu modelo web onde pretende utilizá-lo, utilize {%include WebAPIAJAX %}.

Em alternativa, coloque o código num ficheiro .js, carregue-o como um anexo para um ficheiro Web (nota: terá de desligar as regras de upload nas definições PowerApps para permitir o upload de ficheiros js, embora isto possa ser revertido após o ficheiro ser importado), e depois inclua o ficheiro js no seu modelo web dentro dos tags do script, tal como abaixo. O URL parcial do ficheiro web seria webApiAjax.js.

<script src=”/WebApiAjax.js”></script>

Uma vez que tenha o acima mencionado, a utilização efetiva da WebAPI pode ser conseguida com um comando para webapi.safeAjax, por exemplo.

Tudo parece simples, mas obter o URL e os dados pode ser complicado:

1) O URL usa o nome EntitySet – plural do nome da sua entidade

2) myjson é o objeto JSON que contém os detalhes da entidade para criar, atualizar ou eliminar.

Exemplo simples:

3) No comando safeAjax, utilizar o tipo = POST para criados e associados. É fácil fornecer a mensagem para uma criação básica, mas também se pode combinar a criação de registos de pesquisa e registos indexados (1:N) e a associação, tudo numa única mensagem, conforme abaixo.

DICA: criar uma tabela, mas definir uma pesquisa para um registo existente. No exemplo acima, se o Produto X fosse um registo em mycustomentity, e já existisse, então usaríamos:

DICA: O caso dos parâmetros importa, e normalmente é minúsculo, mas descobri que alguns campos não são todos minúsculos e um campo como o “lookupid” precisava de ser “LookupId”.   Como é que descobriu isso?  Ao usar as definições de metadados ao fazer download (um ficheiro grande) utilizando <my crm>/api/data/v9.1/$metadata e ao pesquisar o NavigationPropertyBinding onde o nome é o nome do campo de pesquisa.

4) Outros tipos:

• PATCH para atualizações
• PUT para atualizar um único valor de propriedade
• DELETE para eliminar um registo e desassociar

5) Para associações N:N, parece-me que não trabalha com uma criação e precisava de um comando POST separado para funcionar. Isto faz sentido, pois normalmente não se pode criar uma relação N:N até que os registos tenham sido criados.

Para o @odata.id parece exigir o caminho completo, assim, para o Portal URI, usei o liquid “https://{{website.adx_primarydomainname}}.