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

Este guia mostra como descobrir e adicionar operações do Dataverse (ações e funções) a um aplicativo de código Power Apps usando os comandos find-dataverse-api e add-dataverse-api CLI.

Pré-requisitos

• Um aplicativo de código Power Apps inicializado com npx power-apps init
• @microsoft/power-apps versão 1.1.1 ou posterior em seu package.json
• Sessão autenticada da CLI (solicita npx power-apps se necessário)
• Acesso ao ambiente do Dataverse que contém a operação que você deseja usar

Etapa 1: Descobrir operações disponíveis

Use find-dataverse-api para pesquisar operações em seu ambiente pelo nome:

npx power-apps find-dataverse-api --search "WhoAmI"

A saída lista operações correspondentes com seu tipo (Ação ou Função), parâmetros, entidade de associação (se houver) e tipo de retorno:

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

  WhoAmI  (Function)
  Returns: mscrm.WhoAmIResponse

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

Você também pode pesquisar ações. Por exemplo, para localizar a ação AddToQueue :

npx power-apps 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)
====================================================================================================

Para obter o JSON bruto (útil para scripts e para agentes de codificação), adicione --json:

npx power-apps find-dataverse-api --search "WhoAmI" --json

A pesquisa é uma correspondência de subcadeia de caracteres que não diferencia maiúsculas de minúsculas no nome da operação.

Etapa 2: Adicionar a operação ao seu aplicativo

Depois de encontrar o nome da operação, execute o seguinte comando:

npx power-apps add-dataverse-api --api-name WhoAmI
# or using the short alias:
npx power-apps add-dataverse-api -n WhoAmI

O comando:

1. Busca a definição de operação do Dataverse do seu ambiente $metadata.
2. Grava um arquivo de esquema em <schemaPath>/dataverse/WhoAmI.Schema.json.
3. Salva arquivos de esquema para todas as entidades do Dataverse referenciadas pelos parâmetros da operação ou tipo de retorno (ignora se eles já existem).
4. Atualizações power.config.json:
   • Adiciona databaseReferences["default.cds"] se ainda não estiver presente.
   • Para operações associadas, adiciona a entidade de associação a dataSources , se ainda não estiver presente.
5. Regenera dataSourcesInfo.ts para incluir a nova operação.
6. Gera um modelo TypeScript e uma classe de serviço em <codeGenPath>/generated/.

Sobre o sucesso, você verá:

Dataverse API 'WhoAmI' added successfully.
Hint: Run 'npx power-apps run' to test locally, or 'npx power-apps push' to deploy.

Etapa 3: Usar o serviço gerado no código do aplicativo

O comando gera uma classe dedicada <ApiName>Service para a operação. Por exemplo, depois de adicionar WhoAmI, importe WhoAmIService do diretório de serviços gerado:

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

O serviço expõe um método estático tipado com nome igual ao da operação. Por exemplo:

const result = await WhoAmIService.WhoAmI();
// result.value contains: { BusinessUnitId: string, UserId: string, OrganizationId: string }

Para uma ação vinculada, como AddToQueue, o primeiro argumento é sempre o GUID do registro no qual operar:

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

const result = await AddToQueueService.AddToQueue(
  queueId,    // string (GUID of the destination queue)
  target,     // Record<string, unknown> (the activity to add)
  sourceQueue,         // Record<string, unknown> | undefined
  queueItemProperties  // Record<string, unknown> | undefined
);
// result.value contains: { QueueItemId: string }

Os tipos de parâmetro e de retorno são do esquema do Dataverse.

• Os parâmetros GUID são tipados como string.
• Parâmetros de pesquisa que fazem referência a uma entidade do Dataverse são digitado como Record<string, unknown>.
• Operações sem valor de retorno produzem Promise<IOperationResult<void>>.
• Operações que retornam um escalar (por exemplo, boolean, number) produzem Promise<IOperationResult<T>> com o tipo TypeScript correspondente.
• Operações que retornam um tipo complexo ou uma entidade produzem Promise<IOperationResult<Record<string, unknown>>>.

Repetir a mesma operação

Executar add-dataverse-api novamente com o mesmo --api-name é seguro e idempotente:

• O comando substitui o arquivo de esquema com a definição mais recente do Dataverse.
• Ele regenera dataSourcesInfo.ts.
• Ele remove entradas duplicadas em power.config.json - ele não adiciona duplicatas.
• Ele não substitui arquivos de esquema de entidade que já existem.

Use este comando para obter alterações na assinatura de uma operação após uma atualização no ambiente.

Arquivos criados ou modificados

O add-dataverse-api comando cria ou atualiza os seguintes arquivos em seu projeto:

Operações vinculadas versus não vinculadas

As operações vinculadas têm como escopo um registro de entidade específico. O método gerado sempre usa um id: string parâmetro como seu primeiro argumento, que é o GUID do registro no qual operar.

As operações desassociadas são de todo o ambiente e não exigem uma ID de registro. Seus métodos assumem apenas os parâmetros declarados.

Ambos os tipos são adicionados com o mesmo comando– a CLI detecta o tipo de operação automaticamente.

Solução de problemas

"Nenhuma operação encontrada" – a pesquisa é baseada em subcadeia de caracteres e não diferencia maiúsculas de minúsculas, mas corresponde apenas ao nome da operação. Tente um termo mais curto ou diferente. Use --json para confirmar a resposta bruta.

Arquivos gerados obsoletos – se você renomeou ou removeu uma operação e os arquivos gerados antigos permanecem, exclua-os manualmente e execute add-dataverse-api novamente para regenerar.

pac code add-data-source ignora a ação ou a função— os arquivos de esquema gerados por add-dataverse-api usam um tipo Microsoft.PowerApps/dataverseOperation que não é reconhecido pela CLI pac. Se algum arquivo de esquema de operação estiver presente na pasta de esquema do Dataverse, pac code add-data-source ignore-os com:

Skipping unsupported Dataverse operation schema '...AddRecurrence.Schema.json':

Esse comportamento significa que a CLI do PAC não dá suporte ao tipo de esquema Microsoft.PowerApps/dataverseOperation, e, portanto, ao invés de falhar, ignora os arquivos associados. A CLI do PAC ainda dá suporte a outros arquivos de esquema que representam fontes de dados ou conectores de entidade do Dataverse e você pode adicioná-los usando pac code add-data-source.

Artigos relacionados

Use ações da API Web
Usar funções de API Web