Compartilhar via

Integrar o Power Automate a sites e aplicativos

  • Artigo

Insira o Power Automate em seu aplicativo ou site usando widgets de fluxo para oferecer aos seus usuários uma maneira simples de automatizar suas tarefas pessoais ou profissionais.

Os widgets de fluxo são iframes localizados em um documento de host. Este documento aponta para uma página no designer do Power Automate. Esses widgets integram a funcionalidade específica do Power Automate no aplicativo de terceiros.

Os widgets podem ser simples. Por exemplo, um widget que renderiza uma lista de modelos sem nenhuma comunicação entre o host e o iframe. Os widgets também podem ser complexos. Por exemplo, um widget que provisiona um fluxo da nuvem de um modelo e, em seguida, dispara o fluxo por meio de uma comunicação bidirecional entre o host e o widget.

Pré-requisitos

  • Uma Conta Microsoft ou
  • Uma conta corporativa ou de estudante

Usar o widget não autenticado

Para usar o widget de modelos não autenticados, insira-o diretamente ao aplicativo host usando um iframe. Você não precisa do SDK (Software Development Kit) do JS (JavaScript) nem de um token de acesso.

Mostrar modelos de cenários

Para iniciar, adicione este código para mostrar os modelos do Power Automate em seu site:

<iframe src="https://flow.microsoft.com/{locale}/widgets/templates/?q={search term}
&pagesize={number of templates}&destination={destination}&category={category}"></iframe>
Parâmetro Descrição
locale O código de região e o idioma de quatro letras para o modo de exibição do modelo. Por exemplo, en-us representa inglês americano e de-de representa o alemão.
search term O termo de pesquisa para os modelos que você quer mostrar na exibição. Por exemplo, pesquise por SharePoint para mostrar modelos do SharePoint.
number of templates O número de modelos que você quer mostrar na exibição.
destination A página que é aberta quando os usuários selecionam o modelo. Insira details para mostrar os detalhes sobre o modelo ou insira new para abrir o designer do Power Automate.
category Filtros para a categoria de modelo fornecida.
parameters.{name} Contexto adicional para passar para o fluxo.

Se o parâmetro de destino for new, o designer do Power Automate será aberto quando os usuários selecionarem um modelo. Os usuários podem criar um fluxo remetente no designer. Confira a próxima seção se desejar ter a experiência completa do widget.

Passando parâmetros adicionais para o modelo de fluxo

Se o usuário estiver em um contexto específico em seu site ou aplicativo, passe esse contexto para o fluxo. Por exemplo, um usuário pode abrir um modelo para Quando um item é criado enquanto olha para uma certa lista em SharePoint. Siga estas etapas para passar a ID da lista como um parâmetro ao fluxo:

  1. Defina o parâmetro no modelo de fluxo antes de publicá-lo. Um parâmetro tem aparência @{parameters('parameter_name')}.
  2. Passe o parâmetro na cadeia de consulta do atributo src do iframe. Por exemplo, adicione &parameters.listName={the name of the list} se você tiver um parâmetro chamado listName.

Exemplo completo

Para mostrar os quatro melhores modelos do SharePoint em alemão e iniciar o usuário com myCoolList, use este código:

<iframe src="https://flow.microsoft.com/de-de/widgets/templates/?q=sharepoint%20&pagesize=4&destination=details&parameters.listName=myCoolList"></iframe>

Usar os widgets de fluxo autenticados

A tabela a seguir mostra a lista de widgets do Power Automate compatíveis com a experiência completa dentro do widget que usa o token de acesso de autenticação do usuário. Será necessário usar o SDK do JS (Kit do Desenvolvedor de Software do Javascript) do Power Automate para inserir os widgets e fornecer o token de acesso de usuário necessário.

Tipo de widget Recurso com suporte
flows Mostra uma lista de fluxos em uma guia para fluxos pessoais e compartilhados. Edite um fluxo existente ou crie um fluxo com base em um modelo ou em branco.
flowCreation Cria um fluxo da nuvem com base em uma ID de modelo fornecida pelo aplicativo host.
runtime Dispara um fluxo de gatilho híbrido ou manual fornecido pelo aplicativo host.
approvalCenter Insere solicitações de aprovação e aprovações enviadas.
templates Mostra uma lista de modelos. O usuário escolhe uma para criar um novo fluxo.

Use o SDK do Fluxo autenticado para permitir que os usuários criem e gerenciem fluxos diretamente do seu site ou do aplicativo (em vez de navegar até o Power Automate). Será necessário conectar o usuário com sua Conta Microsoft ou com o Azure Active Directory para usar o SDK autenticado.

Note

Não há como ocultar a marca do Power Automate ao usar widgets.

Arquitetura do widget

Os widgets do Power Automate funcionam por meio da inserção de um iframe que referencia o Power Automate em um aplicativo host. O host fornece o token de acesso exigido pelo widget do Power Automate. O SDK do JD do Power Automate permite que o aplicativo host inicialize e gerencie o ciclo de vida do widget.

Diagrama da arquitetura de widget do Power Automate.

Detalhes do SDK do JS

A equipe do Power Automate fornece o SDK do JS para facilitar a integração de widgets do Flow em aplicativos de terceiros. O SDK do JS de fluxo está disponível como um link público no serviço de fluxo e permite que o aplicativo host processe eventos do widget e interaja com o aplicativo de fluxo enviando ações para o widget. Eventos e ações do widget são específicos para o tipo de widget.

Inicialização do widget

A referência do SDK do JS do Fluxo precisa ser adicionada ao aplicativo host antes de inicializar o widget.

<script src="https://flow.microsoft.com/Content/msflowsdk-1.1.js"></script>

Crie uma instância de SDK do JS passando o hostName opcional e os valores de localidade em um objeto JSON.

var sdk = new MsFlowSdk({
    hostName:'https://flow.microsoft.com',
    locale:'en-US'
});
Nome Obrigatório/Opcional Descrição
hostName Opcional Nome do host do Power Automate, por exemplo, https://flow.microsoft.com
locale Opcional Localidade do cliente para o widget (o padrão é en-Us se não especificado)

Após a criação da instância do SDK do JS, será possível inicializar e inserir um widget do Power Automate em um elemento pai no aplicativo host. Para fazer isso, adicione um div HTML:

<div id="flowDiv" class="flowContainer"></div>

Em seguida, inicialize o widget do Power Automate com o método renderWidget() do SDK do JS . Forneça o tipo de widget e as configurações correspondentes.

var widget = sdk.renderWidget('<widgettype>', {
        container: 'flowDiv',
        flowsSettings: {},
        templatesSettings: {},
        approvalCenterSettings: {},
        widgetStyleSettings: {}
});

Veja um estilo de exemplo para o contêiner que você pode modificar para corresponder às dimensões do aplicativo host.

<head>
    <style>
        .flowContainer iframe {
            width: 400px;
            height: 1000px;
            border: none;
            overflow: hidden;
    }
    </style>
</head>

Estes são os parâmetros para renderWidget():

Parâmetro Obrigatório/Opcional Descrição
container Obrigatória ID de um elemento DIV na página do host em que o widget será inserido.
environmentId Opcional Os widgets precisam de um ID do ambiente. Se você não fornecer um ID, um ambiente padrão será usado.
flowsSettings Opcional Objeto de configurações do Power Automate
templatesSettings Opcional Objeto de configurações do modelo
approvalCenterSettings Opcional Objeto de configurações de aprovação

Tokens de acesso

Após a execução do renderWidget() do SDK do JS, o SDK do JS inicializará um iframe que aponta para a URL do widget do Power Automate. Essa URL contém todas as configurações nos parâmetros da cadeia de caracteres de consulta. O aplicativo host precisa obter um token de acesso do Power Automate para o usuário (token JWT do Azure Active Directory com o público-alvo https://service.flow.microsoft.com) antes de inicializar o widget. O widget gera um evento GET_ACCESS_TOKEN para solicitar um token de acesso do host. O host precisa manipular o evento e passar o token para o widget:

widget.listen("GET_ACCESS_TOKEN", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
        token:  '<accesstokenFromHost>'
    });
});

O aplicativo host é responsável por manter o token e por passá-lo com uma data de expiração válida para o widget quando solicitado. Se o widget for aberto por períodos maiores, o host deverá verificar se o token expirou e atualizá-lo, se necessário, antes de passá-lo para o widget.

Detectando se o widget está pronto

Após a inicialização bem-sucedida, o widget gerará um evento para notificar que o widget está pronto. O host pode escutar o evento WIDGET_READY e executar qualquer código de host adicional.

widget.listen("WIDGET_READY", function() {
    console.log("The flow widget is now ready.");
    // other host code on widget ready
});

Configurações do widget

FlowsSettings

FlowsSettings pode ser usado para personalizar a funcionalidade do widget do Power Automate.

flowsSettings?: {
    createFromBlankTemplateId?: string;
    flowsFilter?: string;sc
    tab?: string;
};
Parâmetro Obrigatório/Opcional Descrição
createFromBlankTemplateId Obrigatória Use a GUID do modelo quando o usuário selecionar o botão Criar de um modelo em branco no widget de Fluxo
flowsFilter Opcional O widget do Power Automate aplica o filtro fornecido ao listar fluxos. Por exemplo, mostre fluxos que referenciam um site específico do SharePoint.
flowsFilter: "operations/any(operation: operation/sharepoint.site eq 'https://microsoft.sharepoint.com/teams/ProcessSimple' )"
tab Opcional Padroniza a guia ativa a ser mostrada no widget de Power Automate.
Por exemplo,
tab:'sharedFlows' exibe a guia Equipe
e tab:'myFlows' exibe a guia Meus fluxos.

TemplatesSettings

Isso se aplica a todos os widgets que permitem que você crie fluxos com base em um modelo, incluindo widgets de Fluxos, FlowCreation e de Modelos.

templatesSettings?: {
    defaultParams?: any;
    destination?: string;
    pageSize?: number;
    searchTerm?: string;
    templateCategory?: string;
    useServerSideProvisioning?: boolean;
    enableDietDesigner?: boolean;
};
Parâmetro Obrigatório/Opcional Descrição
defaultParams Opcional Os parâmetros de tempo de design a serem usados ao criar um fluxo da nuvem com base em um modelo, por exemplo:
defaultParams: {'parameters.sharepoint.site': 'https://microsoft.sharepoint.com/teams/ProcessSimple', 'parameters.sharepoint.list': 'b3a5baa8-fe94-44ca-a6f0-270d9f821668' }
destination Opcional Os valores válidos são “novo” ou “detalhes”. Quando definidos como “detalhes”, uma página de detalhes é mostrada ao criar um fluxo da nuvem com base em um modelo.
pageSize Opcional Número de modelos a ser exibido. Tamanho padrão = 6
searchTerm Opcional Exibir modelos que correspondem ao termo de pesquisa fornecido
templateCategory Opcional Exibir modelos em uma categoria específica

ApprovalCenterSettings

Aplica-se a widgets ApprovalCenter.

approvalCenterSettings?: {
   approvalsFilter?: string;
   tab?: string;but
   showSimpleEmptyPage? boolean;
   hideLink?: boolean
};
Parâmetro Obrigatório/Opcional Descrição
hideLink Opcional Quando definido como true, o widget oculta os links de aprovações recebidas e enviadas
approvalsFilter Opcional O widget de aprovação aplicará o filtro de aprovação especificado ao listar as aprovações, por exemplo: O widget de aprovação aplicará o filtro de aprovação especificado ao listar as aprovações, por exemplo:
approvalsFilter: 'properties/itemlink eq \'https://microsoft.sharepoint.com/teams/ProcessSimple/_layouts/15/listform.aspx?PageType=4&ListId=737e30a6-5bc4-4e9c-bcdc-d34c5c57d938&ID=3&ContentTypeID=0x010010B708969A9C16408696FD23801531C6\''

approvalsFilter: 'properties/itemlinkencoded eq \'{Your base64 encoded item link url} \''
tab Opcional Guia ativa padrão a ser mostrada no widget de Fluxo.
Valores válidos: “receivedApprovals”, “sentApprovals”
showSimpleEmptyPage Opcional Mostra uma página vazia quando não há aprovações
hideInfoPaneCloseButton Opcional Oculta o botão Fechar do painel de informações (ou o host já tem um botão Fechar)

Eventos de widget

O widget do Power Automate dá suporte a eventos que permitem que o host escute eventos de ciclo de vida do widget. O widget do Power Automate dá suporte a dois tipos de eventos: eventos de notificação unidirecionais (por exemplo, Widget_Ready) e eventos gerados do widget para efetuar fetch dos dados do host (Get_Access_Token). O host precisa usar o método widget.listen() para escutar eventos específicos gerados do widget.

Uso

widget.listen("<WIDGET_EVENT>", function() {
    console.log("The flow widget raised event");
});

Eventos com suporte pelo tipo de widget

Evento de widget Detalhes
WIDGET_READY Widget carregado com sucesso
WIDGET_RENDERED Widget carregado e a renderização de interface do usuário está concluída
GET_ACCESS_TOKEN Solicitação de widget para inserir token de acesso de usuário
GET_STRINGS Permite que o host substitua um conjunto de cadeias de caracteres de interface do usuário mostrado no widget

Widget de runtime

Evento de widget Detalhes Dados
RUN_FLOW_STARTED Disparados e a execução de fluxo foi iniciada
RUN_FLOW_COMPLETED Execução de fluxo disparada com êxito
RUN_FLOW_DONE_BUTTON_CLICKED O usuário selecionou o botão Concluído na execução de fluxo
RUN_FLOW_CANCEL_BUTTON_CLICKED O usuário selecionou o botão Cancelar na execução de fluxo
FLOW_CREATION_SUCCEEDED O fluxo foi criado com êxito { flowUrl: string, flowId: string, fromTemplate: string }
WIDGET_CLOSE Acionado quando o host deveria fechar o widget

Widget de criação de fluxo

Evento de widget Detalhes Dados
FLOW_CREATION_FAILED Falha na criação do fluxo
WIDGET_CLOSE Acionado quando o host deveria fechar o widget
TEMPLATE_LOAD_FAILED Falha no carregamento do modelo
FLOW_CREATION_SUCCEEDED O fluxo foi criado com êxito { flowUrl: string, flowId: string,fromTemplate?: string }

Widget de aprovação

Evento de widget Detalhes
RECEIVED_APPROVAL_STATUS_CHANGED Status de aprovação recebida alterado
SENT_APPROVAL_STATUS_CHANGED Status de aprovação enviada alterado

O evento GET_STRINGS permite que você personalize o texto para alguns dos elementos de interface do usuário mostrados no widget. As cadeias de caracteres a seguir podem ser personalizadas:

Chave da cadeia de caracteres Usar no widget
FLOW_CREATION_CREATE_BUTTON Texto exibido no botão Criar fluxo no widget de criação de fluxo e de runtime
FLOW_CREATION_CUSTOM_FLOW_NAME O valor inicial a ser usado para o nome do fluxo no widget de criação de fluxo. Usado somente quando a configuração allowCustomFlowName está habilitada.
FLOW_CREATION_HEADER Cabeçalho a ser usado ao criar um fluxo da nuvem no widget de criação de fluxo e de runtime
INVOKE_FLOW_HEADER Cabeçalho a ser usado ao invocar um fluxo da nuvem no widget de runtime
INVOKE_FLOW_RUN_FLOW_BUTTON Texto exibido no botão usado para invocar/executar um fluxo da nuvem no widget de runtime

Exemplo

Chame widgetDoneCallback passando um objeto JSON com pares de chave-valor de chave de cadeia de caracteres e o texto para substituir o valor padrão.

widget.listen("GET_STRINGS", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
         "FLOW_CREATION_HEADER": "<string override would go here>",
        "INVOKE_FLOW_RUN_FLOW_BUTTON":  "<string override would go here>"
    });
});

Ações de widget

O host usa ações de widget para enviar uma mensagem ou uma ação específica ao widget. O widget SDK do JS fornece o método notify() para enviar uma mensagem ou um conteúdo JSON para o widget. Cada ação do widget é compatível com uma assinatura de conteúdo específica.

Uso

widget.notify('<WIDGET_ACTION>', parameterMatchingParameterInterface)
    .then(result => console.log(result))
    .catch(error => console.log(error))

Exemplo

Invocar um fluxo da nuvem enviando o comando a seguir para um widget de runtime

widget.notify('triggerFlow', { flowName: flowName, implicitData:implicitData });

Widget de runtime

Ação de widget Detalhes Interface de parâmetro
triggerFlow Dispara uma execução de fluxo da nuvem { flowName: string, implicitData?: string }
triggerFlowByTemplate Dispara uma execução de fluxo da nuvem por modelo { templateId: string, implicitData?: string, designTimeParameters?: Record<string, any> }
getTriggerSchema Obtém o esquema de gatilho para um fluxo da nuvem { flowName: string, }
closeWidget Cancela qualquer atividade pendente e gera um evento WIDGET_CLOSE

Widget de criação de fluxo

Ação de widget Detalhes Interface de parâmetro
createFlowFromTemplate Cria um fluxo da nuvem para o modelo selecionado { templateName: string, designTimeParameters?: Record<string, any> }
createFlowFromTemplateDefinition Cria um fluxo da nuvem para a definição de modelo selecionada { templateDefinition: string }
closeWidget Cancela qualquer atividade pendente e gera um evento WIDGET_CLOSE

Widget de aprovação

Ação de widget Detalhes Interface de parâmetro
closeInfoPane Fecha o painel de informações que exibe os detalhes da aprovação N/D

Configurando seu aplicativo cliente

Será necessário configurar seu aplicativo cliente com Escopos de serviço de fluxo (permissões delegadas). Se o aplicativo do AAD Azure Active Directory usado para integração de widget usar um fluxo de autorização de “concessão de código”, o aplicativo AAD precisará ser reconfigurado com permissões delegadas compatíveis com o Power Automate. Isso oferece permissões delegadas que permitem ao aplicativo:

  • Gerenciar aprovações
  • Ler aprovações
  • Ler atividades
  • Gerenciar fluxos
  • Ler fluxos

Sigas estas etapas para selecionar uma ou mais permissões delegadas:

  1. Acessar https://portal.azure.com
  2. Selecione Azure Active Directory.
  3. Selecione Registros de aplicativo em Gerenciar.
  4. Insira o aplicativo de terceiros a ser configurado para Escopos de serviço de fluxo.
  5. Selecione Configurações. Captura de tela localizando o ícone de configurações do aplicativo.
  6. Selecione Permissões necessárias em Acesso à API/
  7. Selecione Adicionar.
  8. Escolha Selecionar uma API. Captura de tela localizando as permissões necessárias, adição e seleção de uma API.
  9. Procure o serviço do Power Automate e selecione-o. Observação: antes de ver o serviço do Power Automate, seu locatário precisa ter pelo menos um usuário do AAD conectado ao portal do fluxo (https://flow.microsoft.com)
  10. Escolha os escopos de fluxo necessários para seu aplicativo e, em seguida, selecione Salvar. Captura de tela mostrando as permissões delegadas.

Agora o aplicativo obterá um token de Serviço de fluxo que contém as permissões delegadas na declaração 'scp' no token JWT.

Aplicativo de exemplo inserindo widgets de fluxo

Um SPA (Aplicativo de Página Única) JavaScript de exemplo é fornecido na seção de recursos para você poder experimentar a inserção de widgets de fluxo em uma página de host. O uso do aplicativo de exemplo requer o registro de um aplicativo AAD com fluxo de concessão implícita habilitado.

Registrando um aplicativo AAD

  1. Entre no Portal do Azure.
  2. No painel de navegação esquerdo, selecione Azure Active Directory e, em seguida, selecione Registros de aplicativo (Versão prévia) > Novo registro.
  3. Quando a página Registrar um aplicativo for exibida, insira um nome para seu aplicativo.
  4. Em Tipos de conta com suporte, selecione Contas em qualquer diretório organizacional.
  5. Na seção URL de redirecionamento, selecione a plataforma da Web e defina o valor para a URL o aplicativo' com base em seu servidor Web. Configure esse valor como http://localhost:30662/ para executar o aplicativo de exemplo.
  6. Selecione Registrar.
  7. Na página Visão geral do aplicativo, anote o valor da ID do aplicativo (cliente).
  8. O exemplo requer que o fluxo de concessão implícita esteja habilitado. No painel de navegação esquerdo do aplicativo registrado, selecione Autenticação.
  9. Em Configurações avançadas, em Concessão implícita, marque as caixas de seleção Tokens de ID e Tokens de acesso. Os tokens de ID e de acesso são necessários, pois o aplicativo precisa conectar os usuários e chamar a API do fluxo.
  10. Selecione Salvar.

Executando o exemplo

  1. Baixe o exemplo e copie-o para uma pasta local em seu dispositivo.
  2. Abra o arquivo index.html na pasta FlowSDKSample e modifique o applicationConfig para atualizar o clientID para a ID do aplicativo registrada anteriormente. Captura de tela do arquivo index.html localizando a ID do cliente.
  3. O aplicativo de exemplo é configurado para usar os escopos de fluxo Flows.Read.All e Flow.Manage.All. É possível configurar escopos adicionais atualizando a propriedade flowScopes no objeto applicationConfig.
  4. Execute estes comandos para instalar a dependência e execute o aplicativo de exemplo:

    > npm install > node server.js

  5. Abra o navegador e, em seguida, insira http://localhost:30662
  6. Selecione o botão Entrar para se autenticar no AAD e adquirir um token de acesso de fluxo da nuvem.
  7. A caixa de texto Token de acesso contém o token de acesso. Captura de tela mostrando a caixa do token de acesso contendo um token de acesso.
  8. Selecione Carregar widget de fluxos ou Carregar widget de modelos para inserir os widgets correspondentes. Captura de tela mostrando botões para inserir o widget Carregar Fluxos ou o widget Carregar Modelos.

Link de download do aplicativo de exemplo.

Recursos

Páginas de teste do widget

Descubra mais sobre a integração e as configurações do widget:

Localidades de widget com suporte

Se a localidade inicializada não estiver listada, o padrão do fluxo será a localidade com suporte mais próxima.

Localidade Language
bg-bg Búlgaro (Bulgária)
ca-es Catalão (Catalunha)
cs-cz Tcheco (República Tcheca)
da-dk Dinamarquês (Dinamarca)
de-de Alemão (Alemanha)
el-gr Grego (Grécia)
en-Us Inglês (Estados Unidos)
es-es Espanhol (Castelhano)
et-ee Estoniano (Estônia)
eu-es Basco (Basco)
fi-fi Finlandês (Finlândia)
fr-fr Francês (França)
gl-es Galego (Galícia)
hi-HU Húngaro (Hungria)
hi-in Híndi (Índia)
hr-hr Croata (Croácia)
id-Id Indonésio (Indonésia)
it-It Italiano (Itália)
jp-Jp Japonês (Japão)
kk-kz Cazaque (Cazaquistão)
ko-kr Coreano (Coreia)
lt-LT Lituano (Lituânia)
lv-lv Letão (Letônia)
ms-my Malaio (Malásia)
nb-no Norueguês (Bokmål)
nl-nl Holandês (Países Baixos)
pl-pl Polonês (Polônia)
pt-br Português (Brasil)
pt-pt Português (Portugal)
ro-ro Romeno (Romênia)
ru-ru Russo (Rússia)
sk-sk Eslovaco (Eslováquia)
sl-si Esloveno (Eslovênia)
sr-cyrl-rs Sérvio (Cirílico, Sérvia)
sr-latn-rs Sérvio (Latino, Sérvia)
sv-se Sueco (Suécia)
th-th Tailandês (Tailândia)
tr-tr Turco (Turquia)
uk-ua Ucraniano (Ucrânia)
vi-vn Vietnamita (Vietnã)

O uso do SDK de incorporação do Power Automate é coberto pelos Termos de Licença para Software Microsoft.

Note

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).