Crie APIs personalizadas que você pode chamar de Aplicativos Lógicos do Azure

  • Artigo

Aplica-se a: Aplicativos Lógicos do Azure (Consumo)

Embora os Aplicativos Lógicos do Azure ofereçam centenas de conectores que você pode usar em fluxos de trabalho de aplicativos lógicos, convém chamar APIs, sistemas e serviços que não estão disponíveis como conectores. Você pode criar suas próprias APIs que fornecem ações e gatilhos para usar em fluxos de trabalho. Aqui estão outras razões pelas quais você pode querer criar suas próprias APIs que você pode chamar a partir de fluxos de trabalho:

  • Estenda seus fluxos de trabalho atuais de integração de sistemas e integração de dados.
  • Ajude os clientes a usar seu serviço para gerenciar tarefas profissionais ou pessoais.
  • Expanda o alcance, a capacidade de descoberta e o uso do seu serviço.

Basicamente, conectores são APIs da Web que usam REST para interfaces conectáveis, formato de metadados Swagger para documentação e JSON como formato de troca de dados. Como os conectores são APIs REST que se comunicam por meio de pontos de extremidade HTTP, você pode usar qualquer linguagem para criar conectores, como .NET, Java, Python ou Node.js. Você também pode hospedar suas APIs no Serviço de Aplicativo do Azure, uma oferta de plataforma como serviço (PaaS) que fornece uma das melhores, mais fáceis e escaláveis maneiras de hospedagem de API.

Para que APIs personalizadas funcionem com fluxo de trabalho de aplicativo lógico, sua API pode fornecer ações que executam tarefas específicas em fluxos de trabalho. Sua API também pode atuar como um gatilho que inicia uma execução de fluxo de trabalho quando novos dados ou um evento atendem a uma condição especificada. Este tópico descreve padrões comuns que você pode seguir para criar ações e gatilhos em sua API, com base no comportamento que você deseja que sua API forneça.

Você pode hospedar suas APIs no Serviço de Aplicativo do Azure, uma oferta de plataforma como serviço (PaaS) que fornece hospedagem de API altamente escalável e fácil.

Gorjeta

Embora você possa implantar suas APIs como aplicativos Web, considere implantar suas APIs como aplicativos de API, o que pode facilitar seu trabalho quando você cria, hospeda e consome APIs na nuvem e no local. Você não precisa alterar nenhum código em suas APIs, basta implantar seu código em um aplicativo de API. Por exemplo, saiba como criar aplicativos de API criados com estes idiomas:

Como as APIs personalizadas diferem dos conectores personalizados?

APIs personalizadas e conectores personalizados são APIs da Web que usam REST para interfaces conectáveis, formato de metadados Swagger para documentação e JSON como formato de troca de dados. E como essas APIs e conectores são APIs REST que se comunicam por meio de pontos de extremidade HTTP, você pode usar qualquer linguagem, como .NET, Java, Python ou Node.js, para criar APIs e conectores personalizados.

As APIs personalizadas permitem chamar APIs que não são conectores e fornecem pontos de extremidade que você pode chamar com HTTP + Swagger, Gerenciamento de API do Azure ou Serviços de Aplicativo. Os conectores personalizados funcionam como APIs personalizadas, mas também têm estes atributos:

  • Registrado como recursos do Logic Apps Connector no Azure.
  • Apareça com ícones ao lado de conectores gerenciados pela Microsoft no Designer de Aplicativos Lógicos.
  • Disponível apenas para os autores dos conectores e usuários de recursos do aplicativo lógico que tenham o mesmo locatário do Microsoft Entra e a mesma assinatura do Azure na região onde os aplicativos lógicos são implantados.

Você também pode nomear conectores registrados para certificação Microsoft. Esse processo verifica se os conectores registrados atendem aos critérios de uso público e disponibiliza esses conectores para usuários no Power Automate e no Microsoft Power Apps.

Para obter mais informações, consulte a seguinte documentação:

Ferramentas úteis

Uma API personalizada funciona melhor com aplicativos lógicos quando a API também tem um documento Swagger que descreve as operações e os parâmetros da API. Muitas bibliotecas, como o Swashbuckle, podem gerar automaticamente o arquivo Swagger para você. Para anotar o arquivo Swagger para nomes de exibição, tipos de propriedade e assim por diante, você também pode usar TRex para que seu arquivo Swagger funcione bem com aplicativos lógicos.

Padrões de ação

Para que os aplicativos lógicos executem tarefas, sua API personalizada deve fornecer ações. Cada operação em sua API é mapeada para uma ação. Uma ação básica é um controlador que aceita solicitações HTTP e retorna respostas HTTP. Assim, por exemplo, um fluxo de trabalho envia uma solicitação HTTP para seu aplicativo Web ou aplicativo de API. Em seguida, seu aplicativo retorna uma resposta HTTP, juntamente com o conteúdo que o fluxo de trabalho pode processar.

Para uma ação padrão, você pode escrever um método de solicitação HTTP em sua API e descrever esse método em um arquivo Swagger. Em seguida, você pode chamar sua API diretamente com uma ação HTTP ou uma ação HTTP + Swagger. Por padrão, as respostas devem ser retornadas dentro do limite de tempo limite da solicitação.

Standard action pattern

Para fazer um fluxo de trabalho aguardar enquanto sua API conclui tarefas de execução mais longa, sua API pode seguir o padrão de sondagem assíncrona ou o padrão de webhook assíncrono descrito neste tópico. Para uma analogia que ajude a visualizar os diferentes comportamentos desses padrões, imagine o processo para pedir um bolo personalizado de uma padaria. O padrão de sondagem reflete o comportamento em que você liga para a padaria a cada 20 minutos para verificar se o bolo está pronto. O padrão webhook reflete o comportamento em que a padaria pede seu número de telefone para que eles possam ligar para você quando o bolo estiver pronto.

Executar tarefas de longa duração com o padrão de ação de sondagem

Para que sua API execute tarefas que podem ser executadas por mais tempo do que o limite de tempo limite da solicitação, você pode usar o padrão de sondagem assíncrona. Esse padrão faz com que sua API funcione em um thread separado, mas mantenha uma conexão ativa com o mecanismo de Aplicativos Lógicos do Azure. Dessa forma, o fluxo de trabalho não expira nem continua com a próxima etapa do fluxo de trabalho antes que sua API termine de funcionar.

Aqui está o padrão geral:

  1. Certifique-se de que o mecanismo sabe que sua API aceitou a solicitação e começou a funcionar.
  2. Quando o mecanismo fizer solicitações subsequentes de status de trabalho, informe o mecanismo quando sua API concluir a tarefa.
  3. Retorne dados relevantes para o mecanismo para que o fluxo de trabalho possa continuar.

Agora aplique a analogia anterior da padaria ao padrão de votação, e imagine que você chama uma padaria e pede um bolo personalizado para entrega. O processo para fazer o bolo leva tempo, e você não quer esperar no telefone enquanto a padaria trabalha no bolo. A padaria confirma o seu pedido e faz com que você ligue a cada 20 minutos para saber o status do bolo. Depois de 20 minutos, você liga para a padaria, mas eles dizem que seu bolo não está feito e que você deve ligar em mais 20 minutos. Este processo de ida e volta continua até que você ligue e a padaria diga que seu pedido está pronto e entregue seu bolo.

Então, vamos mapear esse padrão de sondagem de volta. A padaria representa sua API personalizada, enquanto você, o cliente do bolo, representa o mecanismo de Aplicativos Lógicos do Azure. Quando o mecanismo chama sua API com uma solicitação, sua API confirma a solicitação e responde com o intervalo de tempo em que o mecanismo pode verificar o status do trabalho. O mecanismo continua verificando o status do trabalho até que sua API responda que o trabalho foi concluído e retorna dados para seu aplicativo lógico, que continua o fluxo de trabalho.

Polling action pattern

Aqui estão as etapas específicas para sua API seguir, descritas da perspetiva da API:

  1. Quando sua API receber uma solicitação HTTP para iniciar o trabalho, retorne imediatamente uma resposta HTTP 202 ACCEPTED com o location cabeçalho descrito posteriormente nesta etapa. Essa resposta permite que o mecanismo de Aplicativos Lógicos do Azure saiba que sua API recebeu a solicitação, aceitou a carga útil da solicitação (entrada de dados) e agora está processando.

    A 202 ACCEPTED resposta deve incluir estes cabeçalhos:

    • Obrigatório: um location cabeçalho que especifica o caminho absoluto para uma URL onde o mecanismo de Aplicativos Lógicos do Azure pode verificar o status do trabalho da sua API

    • Opcional: um retry-after cabeçalho que especifica o número de segundos que o mecanismo deve aguardar antes de verificar o location status do trabalho na URL.

      Por padrão, o mecanismo sonda a location URL após um segundo. Para especificar um intervalo diferente, inclua o cabeçalho e o retry-after número de segundos até a próxima sondagem.

  2. Depois que o tempo especificado passar, o mecanismo de Aplicativos Lógicos do Azure sonda a URL para verificar o status do location trabalho. Sua API deve executar essas verificações e retornar estas respostas:

    • Se o trabalho estiver concluído, retorne uma resposta HTTP 200 OK , juntamente com a carga útil da resposta (entrada para a próxima etapa).

    • Se o trabalho ainda estiver em processamento, retorne outra resposta HTTP 202 ACCEPTED , mas com os mesmos cabeçalhos da resposta original.

Quando sua API segue esse padrão, você não precisa fazer nada na definição do fluxo de trabalho para continuar verificando o status do trabalho. Quando o mecanismo obtém uma resposta HTTP 202 ACCEPTED e um cabeçalho válido location , o mecanismo respeita o padrão assíncrono e verifica o location cabeçalho até que sua API retorne uma resposta diferente de 202.

Gorjeta

Para obter um exemplo de padrão assíncrono, revise este exemplo de resposta assíncrona do controlador no GitHub.

Execute tarefas de longa execução com o padrão de ação webhook

Como alternativa, você pode usar o padrão webhook para tarefas de longa execução e processamento assíncrono. Esse padrão pausa o fluxo de trabalho e aguarda um "retorno de chamada" da API para concluir o processamento antes de continuar o fluxo de trabalho. Este retorno de chamada é um HTTP POST que envia uma mensagem para um URL quando um evento acontece.

Agora aplique a analogia anterior da padaria ao padrão webhook e imagine que você chama uma padaria e pede um bolo personalizado para entrega. O processo para fazer o bolo leva tempo, e você não quer esperar no telefone enquanto a padaria trabalha no bolo. A padaria confirma o seu pedido, mas desta vez, você dá o seu número de telefone para que eles possam ligar para você quando o bolo terminar. Desta vez, a padaria diz-lhe quando a sua encomenda está pronta e entrega o seu bolo.

Quando mapeamos esse padrão de webhook de volta, a padaria representa sua API personalizada, enquanto você, o cliente do bolo, representa o mecanismo de Aplicativos Lógicos do Azure. O mecanismo chama sua API com uma solicitação e inclui uma URL de "retorno de chamada". Quando o trabalho é concluído, sua API usa a URL para notificar o mecanismo e retornar dados para seu aplicativo lógico, que continua o fluxo de trabalho.

Para esse padrão, configure dois pontos de extremidade no controlador: subscribe e ainda unsubscribe

  • subscribe ponto de extremidade: quando a execução atinge a ação da API no fluxo de trabalho, o mecanismo de Aplicativos Lógicos do Azure chama o ponto de subscribe extremidade. Esta etapa faz com que o fluxo de trabalho crie uma URL de retorno de chamada que sua API armazena e, em seguida, aguarde o retorno de chamada de sua API quando o trabalho for concluído. Em seguida, sua API chama de volta com um HTTP POST para a URL e passa qualquer conteúdo retornado e cabeçalhos como entrada para o aplicativo lógico.

  • unsubscribe ponto de extremidade: se a execução do fluxo de trabalho for cancelada, o mecanismo de Aplicativos Lógicos do Azure chamará o ponto de unsubscribe extremidade. Sua API pode então cancelar o registro da URL de retorno de chamada e interromper todos os processos, conforme necessário.

Webhook action pattern

Atualmente, o designer de fluxo de trabalho não suporta a descoberta de pontos de extremidade de webhook por meio do Swagger. Portanto, para esse padrão, você precisa adicionar uma ação Webhook e especificar a URL, os cabeçalhos e o corpo da sua solicitação. Consulte também Ações e gatilhos do fluxo de trabalho. Para obter um exemplo de padrão de webhook, revise este exemplo de gatilho de webhook no GitHub.

Aqui estão algumas outras dicas e notas:

  • Para passar a URL de retorno de chamada, você pode usar a @listCallbackUrl() função de fluxo de trabalho em qualquer um dos campos anteriores, conforme necessário.

  • Se você possui o recurso do aplicativo lógico e o serviço inscrito, não é necessário chamar o unsubscribe ponto de extremidade depois que a URL de retorno de chamada for chamada. Caso contrário, o tempo de execução dos Aplicativos Lógicos do Azure precisa chamar o unsubscribe ponto de extremidade para sinalizar que não são esperadas mais chamadas e permitir a limpeza de recursos no lado do servidor.

Padrões de gatilho

Sua API personalizada pode atuar como um gatilho que inicia uma execução de fluxo de trabalho quando novos dados ou um evento atendem a uma condição especificada. Esse gatilho pode verificar regularmente ou esperar e ouvir novos dados ou eventos no seu ponto de extremidade de serviço. Se novos dados ou um evento atender à condição especificada, o gatilho será acionado e iniciará o aplicativo lógico, que está ouvindo esse gatilho. Para iniciar aplicativos lógicos dessa maneira, sua API pode seguir o gatilho de sondagem ou o padrão de gatilho de webhook. Esses padrões são semelhantes aos seus homólogos para ações de sondagem e ações de webhook. Além disso, saiba mais sobre a medição de uso para gatilhos.

Verifique novos dados ou eventos regularmente com o padrão de gatilho de sondagem

Um gatilho de sondagem age de forma muito semelhante à ação de sondagem descrita anteriormente neste tópico. O mecanismo de Aplicativos Lógicos do Azure chama e verifica periodicamente o ponto de extremidade do gatilho em busca de novos dados ou eventos. Se o mecanismo encontrar novos dados ou um evento que atenda à sua condição especificada, o gatilho será acionado. Em seguida, o mecanismo cria uma instância de fluxo de trabalho que processa os dados como entrada.

Polling trigger pattern

Nota

Cada solicitação de sondagem conta como uma execução de ação, mesmo quando nenhuma instância de fluxo de trabalho é criada. Para evitar o processamento dos mesmos dados várias vezes, o gatilho deve limpar os dados que já foram lidos e passados para o aplicativo lógico.

Aqui estão etapas específicas para um gatilho de sondagem, descritas da perspetiva da API:

Encontrou novos dados ou eventos? Resposta da API
Encontrado Retorne um status HTTP 200 OK com a carga útil de resposta (entrada para a próxima etapa).
Essa resposta cria uma instância de fluxo de trabalho e inicia o fluxo de trabalho.
Não encontrado Retornar um status HTTP 202 ACCEPTED com um cabeçalho e um locationretry-after cabeçalho.
Para gatilhos, o location cabeçalho também deve conter um parâmetro de consulta, que geralmente é um triggerState "carimbo de data/hora". Sua API pode usar esse identificador para controlar a última vez que o fluxo de trabalho foi acionado.

Por exemplo, para verificar periodicamente se há novos arquivos no serviço, você pode criar um gatilho de sondagem com estes comportamentos:

O pedido inclui triggerState? Resposta da API
Não Retornar um status HTTP 202 ACCEPTED mais um location cabeçalho com triggerState definido para a hora atual e o retry-after intervalo para 15 segundos.
Sim Verifique o seu serviço para arquivos adicionados após o DateTime para triggerState.
Número de ficheiros encontrados Resposta da API
Ficheiro único Retorne um status HTTP 200 OK e a carga útil do conteúdo, atualize triggerState para o arquivo retornado e defina retry-after o DateTime intervalo para 15 segundos.
Vários arquivos Retorne um arquivo de cada vez e um status HTTP 200 OK , atualize triggerStatee defina o retry-after intervalo como 0 segundos.
Essas etapas permitem que o mecanismo saiba que mais dados estão disponíveis e que o mecanismo deve solicitar imediatamente os dados da URL no location cabeçalho.
Sem ficheiros Retorne um status HTTP 202 ACCEPTED , não altere triggerStatee defina o retry-after intervalo para 15 segundos.

Gorjeta

Para obter um exemplo de padrão de gatilho de sondagem, revise este exemplo de controlador de gatilho de sondagem no GitHub.

Aguarde e ouça novos dados ou eventos com o padrão de gatilho webhook

Um gatilho de webhook é um gatilho de push que aguarda e escuta novos dados ou eventos em seu ponto de extremidade de serviço. Se novos dados ou um evento atender à condição especificada, o gatilho será acionado e criará uma instância de fluxo de trabalho, que processará os dados como entrada. Os gatilhos do Webhook agem de forma muito semelhante às ações do webhook descritas anteriormente neste tópico e são configurados com subscribe e unsubscribe pontos de extremidade.

  • subscribe ponto de extremidade: quando você adiciona e salva um gatilho de webhook em seu aplicativo lógico, o mecanismo de Aplicativos Lógicos do Azure chama o ponto de subscribe extremidade. Esta etapa faz com que o fluxo de trabalho crie uma URL de retorno de chamada que sua API armazena. Quando há novos dados ou um evento que atende à condição especificada, sua API chama de volta com um HTTP POST para a URL. A carga útil do conteúdo e os cabeçalhos passam como entrada para o aplicativo lógico.

  • unsubscribe ponto de extremidade: se o gatilho do webhook ou todo o recurso do aplicativo lógico for excluído, o mecanismo de Aplicativos Lógicos do Azure chamará o ponto de unsubscribe extremidade. Sua API pode então cancelar o registro da URL de retorno de chamada e interromper todos os processos, conforme necessário.

Webhook trigger pattern

Atualmente, o designer de fluxo de trabalho não suporta a descoberta de pontos de extremidade de webhook por meio do Swagger. Portanto, para esse padrão, você precisa adicionar um gatilho Webhook e especificar a URL, cabeçalhos e corpo para sua solicitação. Consulte também o gatilho HTTPWebhook. Para obter um exemplo de padrão de webhook, revise este exemplo de controlador de gatilho de webhook no GitHub.

Aqui estão algumas outras dicas e notas:

  • Para passar a URL de retorno de chamada, você pode usar a @listCallbackUrl() função de fluxo de trabalho em qualquer um dos campos anteriores, conforme necessário.

  • Para evitar o processamento dos mesmos dados várias vezes, o gatilho deve limpar os dados que já foram lidos e passados para o aplicativo lógico.

  • Se você possui o recurso do aplicativo lógico e o serviço inscrito, não é necessário chamar o unsubscribe ponto de extremidade depois que a URL de retorno de chamada for chamada. Caso contrário, o tempo de execução dos Aplicativos Lógicos precisa chamar o unsubscribe ponto de extremidade para sinalizar que não são esperadas mais chamadas e permitir a limpeza de recursos no lado do servidor.

Melhore a segurança de chamadas para suas APIs a partir de aplicativos lógicos

Depois de criar suas APIs personalizadas, configure a autenticação para suas APIs para que você possa chamá-las com segurança a partir de aplicativos lógicos. Saiba como melhorar a segurança de chamadas para APIs personalizadas a partir de aplicativos lógicos.

Implante e chame suas APIs

Depois de configurar a autenticação, configure a implantação para suas APIs. Saiba como implantar e chamar APIs personalizadas de aplicativos lógicos.

Publicar APIs personalizadas no Azure

Para disponibilizar suas APIs personalizadas para outros usuários dos Aplicativos Lógicos do Azure, você deve adicionar segurança e registrá-los como conectores dos Aplicativos Lógicos do Azure. Para obter mais informações, veja Descrição geral dos conectores personalizados.

Para disponibilizar suas APIs personalizadas para todos os usuários em Aplicativos Lógicos, Power Automatizate e Microsoft Power Apps, você deve adicionar segurança, registrar suas APIs como conectores de Aplicativos Lógicos do Azure e nomear seus conectores para o programa Microsoft Azure Certified.

Obter suporte

Próximos passos