Adicionar uma ação ou função do Dataverse ao seu aplicativo de código

Este artigo mostra como descobrir e adicionar ações e funções do Dataverse a um aplicativo de código Power Apps usando a CLI Power Apps.

Pré-requisitos

  • Um aplicativo de código Power Apps inicializado com pa app init
  • @microsoft/power-apps versão 1.1.1 ou mais recente em seu package.json
  • Acesso ao ambiente do Dataverse que contém a operação que você deseja usar

A CLI solicitará que você entre se ainda não estiver autenticado.

Etapa 1: Localizar operações disponíveis

Use pa app find-dataverse-api para pesquisar operações por nome no ambiente configurado para seu aplicativo de código:

pa app find-dataverse-api --search "WhoAmI"

A saída lista as operações correspondentes e inclui o tipo de operação, parâmetros, tabela de associação e tipo de retorno.

====================================================================================================
Dataverse Operations
====================================================================================================

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Essa função e o tipo de retorno estão documentados aqui:

Você também pode pesquisar ações. Por exemplo:

pa app find-dataverse-api --search "AddToQueue"

====================================================================================================
Dataverse Operations
====================================================================================================

  AddToQueue  (Action)
  Bound to: mscrm.queue
  Parameters:
    - Target: mscrm.crmbaseentity
    - SourceQueue?: mscrm.queue
    - QueueItemProperties?: mscrm.queueitem
  Returns: mscrm.AddToQueueResponse

----------------------------------------------------------------------------------------------------
Total: 1 operation(s)
====================================================================================================

Esta ação, os tipos de parâmetro e os tipos retornados estão documentados aqui:

A pesquisa usa correspondência de substring que não diferencia maiúsculas de minúsculas no nome da operação. Para retornar JSON para cenários de script ou de agente de codificação, inclua --json:

pa app find-dataverse-api --search "WhoAmI" --json

Etapa 2: Adicionar a operação

Depois de encontrar o nome da operação, adicione-o ao aplicativo:

pa app add dataverse-api --api-name WhoAmI

O comando:

  1. Obtém a definição de operação do ponto de extremidade do Dataverse$metadata.
  2. Grava o esquema de operação em <schemaPath>/dataverse/<ApiName>.Schema.json.
  3. Salva esquemas para tabelas do Dataverse referenciadas pela operação.
  4. Atualiza power.config.json.
  5. Regenera dataSourcesInfo.ts.
  6. Gera modelos TypeScript e uma classe de serviço em <codeGenPath>/generated/.

Quando você adiciona a operação, a CLI retorna uma confirmação:

Dataverse API 'WhoAmI' added successfully.

Etapa 3: Usar o serviço gerado

O comando gera uma <ApiName>Service classe para a operação. Depois de adicionar WhoAmI, importe seu serviço:

import { WhoAmIService } from './generated/services/WhoAmIService';

Chame o método gerado:

const result = await WhoAmIService.WhoAmI();
// result.value contains BusinessUnitId, UserId, and OrganizationId.

Para uma ação associada , como AddToQueue, o primeiro argumento é a ID do registro em que a ação opera:

import { AddToQueueService } from './generated/services/AddToQueueService';

const result = await AddToQueueService.AddToQueue(
  queueId,
  target,
  sourceQueue,
  queueItemProperties
);

Os tipos de parâmetro e retorno são baseados no esquema do Dataverse:

  • Os parâmetros GUID usam o string tipo.
  • Parâmetros de pesquisa que fazem referência a uma tabela do Dataverse usam Record<string, unknown>.
  • Operações sem valor de retorno usam Promise<IOperationResult<void>>.
  • Operações que retornam um valor escalar usam Promise<IOperationResult<T>>.
  • Operações que retornam um tipo complexo ou uma tabela usam Promise<IOperationResult<Record<string, unknown>>>.

Atualizar uma operação

Execute pa app add dataverse-api novamente com o mesmo nome de operação para obter a definição mais recente:

pa app add dataverse-api --api-name WhoAmI

O comando substitui o esquema de operação, regenera dataSourcesInfo.ts, remove entradas de configuração duplicadas e preserva os arquivos de esquema de tabela referenciados existentes.

Arquivos criados ou atualizados

Arquivo Troco
<schemaPath>/dataverse/<ApiName>.Schema.json Cria ou substitui o esquema de operação.
<schemaPath>/dataverse/<TableName>.Schema.json Cria esquemas para tabelas referenciadas se elas ainda não existirem.
<schemaPath>/appschemas/dataSourcesInfo.ts Regenera as informações da fonte de dados.
power.config.json Adiciona a referência do Dataverse e, para uma operação vinculada, a tabela de vínculo.
<codeGenPath>/generated/models/<TableName>Model.ts Gera modelos para tabelas referenciadas.
<codeGenPath>/generated/services/<ApiName>Service.ts Gera a classe de serviço para a operação.

Solucionando problemas

Nenhuma operação encontrada

A pesquisa corresponde apenas ao nome da operação. Tente um termo de pesquisa mais curto ou diferente. Inclua --json para inspecionar a resposta.

Os arquivos gerados estão desatualizados

Execute pa app add dataverse-api novamente com o mesmo nome de operação. Se você renomeou ou removeu a operação e arquivos gerados obsoletos permanecerem, exclua esses arquivos antes de regenerar a operação.

  • Last updated on