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 posterior 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 uma correspondência de subcadeia de caracteres 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 um uso de Promise<IOperationResult<void>>valor retornado.
  • Operações que retornam um uso Promise<IOperationResult<T>>de valor escalar.
  • 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 associada, a tabela de associação.
<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