Exercício: criar uma API personalizada

  • 15 minutos

Neste exercício, você criará uma API personalizada do Dataverse para executar lógica personalizada. Em seguida, você usará a API personalizada de uma etapa em um fluxo do Power Automate.

Importante

Use um ambiente de teste com o Microsoft Dataverse provisionado. Se não tiver um, você poderá criar uma conta no plano da comunidade.

Tarefa 1: Criar o projeto de API personalizada

  1. Baixe e instale a Power Platform CLI.

  2. Execute o arquivo powerapps-cli para iniciar a instalação.

  3. Use o assistente de configuração para concluir a configuração e selecione Concluir.

  4. Abra o Prompt de Comando.

  5. Execute o comando abaixo para criar uma nova pasta chamada CustomAPILab.

    md CustomAPILab

  6. Altere o diretório para a pasta que você criou.

    cd CustomAPILab

  7. Agora você deve estar na pasta CustomAPIlAB. Execute o comando abaixo para inicializar uma nova biblioteca de classes de plug-in do Dataverse.

    pac plugin init

  8. A criação da biblioteca de classes de plug-in do Dataverse deve ser bem-sucedida.

    Captura de tela mostrando a biblioteca de classes de plug-in criada.

  9. Execute o comando abaixo para abrir o projeto no Visual Studio Code.

    start CustomAPILab.csproj

  10. O projeto deve ser aberto no Visual Studio.

  11. Clique com o botão direito no arquivo Plugin1.cs e renomeie-o como MatchPlugin.cs.

  12. Selecione Sim para renomear uma caixa de diálogo de arquivo.

  13. Clique com o botão direito do mouse no Projeto CustomAPILab e selecione Gerenciar Pacotes do NuGet.

  14. Pesquise System.Text.RegularExpressions e selecione Instalar.

    Captura de tela mostrando o pacote do NuGet sendo instalado.

  15. Abra o arquivo MatchPlugin.cs.

  16. Adicione a instrução a seguir.

    using System.Text.RegularExpressions;

  17. Adicione as linhas a seguir no método ExecuteDataversePlugin e após a linha de contexto var. Essas linhas obtêm o valor dos parâmetros de entrada passados na invocação da API personalizada.

    string input = (string)context.InputParameters["StringIn"];

    string pattern = (string)context.InputParameters["Pattern"];

  18. Depois, adicione a linha a seguir para obter o serviço de rastreamento.

    ITracingService tracingService = (ITracingService)localPluginContext.ServiceProvider.GetService(typeof(ITracingService));

  19. Adicione a linha abaixo para gravar o valor de entrada no rastreamento.

    tracingService.Trace("Provided input: " + input);

  20. Adicione a linha a seguir após chamar o método Regex.Match.

    var result = Regex.Match(input, pattern);

  21. Grave o resultado a ser rastreado.

    tracingService.Trace("Matching result: " + result.Success);

  22. Finalmente, adicione a linha a seguir para definir o parâmetro de saída Matched.

    context.OutputParameters["Matched"] = result.Success;

  23. Agora o método execute deve ter a aparência a seguir.

    Captura de tela mostrando o método de execução do plug-in.

  24. Selecione Criar > Criar Solução.

  25. O projeto deve ser criado com êxito.

Tarefa 2: Registrar o plug-in da API personalizada

  1. Abra o prompt de comando e execute o comando abaixo para iniciar a Plugin Registration Tool.

    pac tool prt

  2. Selecione + Criar Nova Conexão.

  3. Selecione Office 365, insira suas credenciais e selecione Logon.

  4. Selecione o ambiente correto.

  5. Escolha Registrar | Registrar Novo Assembly.

    Captura de tela mostrando o clique em Registrar Novo Assembly.

  6. Selecione ... e navegue até a pasta CustomAPILab\bin\Debug\net462.

  7. Selecione CustomAPILab.dll.

  8. Selecione OK.

    Captura de tela mostrando a caixa de diálogo de registro de novo assembly com o plug-in selecionado.

  9. Selecione Registrar Plug-ins Selecionados.

  10. Selecione OK na mensagem de êxito. Seu plug-in está pronto para se conectar à API personalizada que criaremos na próxima tarefa.

Tarefa 3: Criar a API personalizada

  1. Navegue até o Power Apps maker portal e verifique se você está no ambiente correto.

  2. Selecione Soluções na navegação à esquerda.

  3. Selecione + Nova Solução.

  4. Insira Custom API Lab em Nome de Exibição.

  5. Selecione Editor Padrão de CDS na lista suspensa Editor.

  6. Selecione Criar. Isso cria uma solução personalizada que conterá nossos componentes.

  7. Selecione + Novo | Mais | Outro | API Personalizada

  8. Insira as seguintes informações:

    • Nome Exclusivo: contoso_match

    • Nome: Corresponder

    • Nome de Exibição: Corresponder

    • Descrição: Corresponder a uma cadeia de caracteres

    • Tipo de Associação: Global

  9. Em Tipo de Plug-in, selecione o ícone de pesquisa e localize seu plugin.

    Captura de tela mostrando a caixa de diálogo da API personalizada com os campos preenchidos.

  10. Selecione Salvar e Fechar.

  11. Selecione Concluído.

  12. Selecione +Novo | Mais | Outros | Parâmetro de Solicitação de API Personalizada.

  13. Para API Personalizada, selecione o ícone Pesquisar e, depois, Corresponder (sua API Personalizada).

  14. Insira StringIn em Nome Exclusivo, Nome, Nome de Exibição e Descrição para simplificar.

  15. Selecione Cadeia de Caracteres para Tipo.

  16. Selecione Salvar e Fechar.

  17. Selecione Concluído.

  18. Repita as etapas 13-17 e adicione outro Parâmetro de Solicitação de API Personalizada chamado Padrão.

  19. Selecione Novo | Mais | Outro | Propriedade de Resposta de API Personalizada.

  20. Para API Personalizada, selecione o ícone Pesquisar e, depois, Corresponder (sua API Personalizada).

  21. Insira Correspondente em Nome Exclusivo, Nome, Nome de Exibição e Descrição para simplificar.

  22. Selecione Booliano para Tipo.

  23. Selecione Salvar e Fechar.

  24. A lista de componentes da solução deve ter a aparência a seguir.

    Captura de tela mostrando os componentes da solução após a criação de todos os parâmetros de resposta e solicitação e a API.

Tarefa 4: Usar a API personalizada do Power Automate

  1. Na solução, selecione + Novo | Automação | Fluxo da Nuvem | Instantâneo.

    Captura de tela mostrando o botão Criar fluxo da nuvem instantâneo.

  2. Insira Correspondência de cadeia de caracteres para o nome do fluxo, selecione o gatilho Disparar manualmente um fluxo e, depois, Criar.

  3. Selecione o botão + Nova Etapa.

  4. Pesquise a execução e escolha Executar uma ação não associada.

    Captura de tela mostrando a seleção da ação realizada e não associada.

  5. Na lista Nome da Ação, localize e selecione contoso_match.

  6. Insira qualquer endereço de email válido em StringIn.

  7. Insira a Expressão regular a seguir em Padrão. Esse é um padrão de email simples. Outros exemplos estão disponíveis.

    ^\w+@[a-zA-Z_]+?\.[a-zA-Z]{2,3}$

  8. O fluxo deve ser semelhante ao exemplo a seguir.

    Captura de tela mostrando o fluxo com o gatilho e a etapa de ação não associada de desempenho.

  9. Selecione Salvar.

  10. Após a conclusão do salvamento, selecione Testar.

  11. Selecione Manualmente e, depois, Testar.

  12. Selecione Executar fluxo.

  13. Selecione Concluído.

  14. Depois que o fluxo for concluído, selecione Executar uma ação não associada para expandir e ver os resultados.

    Captura de tela mostrando os resultados da execução do fluxo.

Agora você concluiu a criação de uma ação personalizada e o uso dela em um fluxo do Power Automate. A ação de API personalizada contoso_match agora também está disponível para ser chamada diretamente usando a API da plataforma.