Criar um Conector Personalizado do Batch JSON do Microsoft Graph para o Power Automate
Existem mais de 230 conectores in box para o Microsoft Power Automate. Muitos destes conectores utilizam o Microsoft Graph para comunicar com pontos finais específicos de produtos Microsoft. Além disso, existem outros cenários em que poderemos ter de chamar o Microsoft Graph diretamente a partir do Power Automate através de blocos modulares básicos do serviço, uma vez que não existe nenhum conector que comunique diretamente com o Microsoft Graph para abranger toda a API.
Além de abordar cenários para chamar diretamente o Microsoft Graph, vários pontos finais da Microsoft Graph API apenas suportam permissões delegadas. O conector HTTP no Microsoft Power Automate permite integrações muito flexíveis, incluindo chamar o Microsoft Graph. No entanto, o conector HTTP não tem a capacidade de colocar em cache as credenciais de um utilizador para ativar cenários de permissão delegados específicos. Nestes casos, pode ser criado um conector personalizado para fornecer um wrapper em torno da Microsoft Graph API e permitir o consumo da API com permissões delegadas.
Este laboratório abrange ambos os cenários acima. Em primeiro lugar, irá criar um conector personalizado para permitir integrações com o Microsoft Graph que requerem permissões delegadas. Em segundo lugar, irá utilizar o ponto final do pedido de $batch para fornecer acesso à capacidade total do Microsoft Graph enquanto utiliza as permissões delegadas que exigem que uma aplicação tenha um utilizador com "sessão iniciada" presente.
Observação
Este é um tutorial sobre como criar um conector personalizado para utilização no Microsoft Power Automate e no Azure Logic Apps. Este tutorial pressupõe que leu a descrição geral do conector personalizado para compreender o processo.
Pré-requisitos
Para concluir este exercício nesta publicação, precisará do seguinte:
- Acesso de administrador a um inquilino do Microsoft 365. Se não tiver um inquilino do Microsoft 365, poderá qualificar-se para um através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.
- Acesso ao Microsoft Power Automate com uma licença Premium. Veja FAQ de licenciamento do Power Automate para obter detalhes. Se não tiver uma licença Premium, pode inscrever-se numa avaliação de 90 dias.
Comentários
Forneça comentários sobre este tutorial no repositório do GitHub.
Criar um registro de aplicativo do Azure AD
Neste exercício, irá criar uma nova Aplicação do Azure Active Directory que será utilizada para fornecer as permissões delegadas para o conector personalizado.
Abra um browser e navegue para o centro de administração do Microsoft Entra e inicie sessão com uma conta de Administrador global.
Selecione Microsoft Entra ID no painel de navegação esquerdo, expanda Identidade, expanda Aplicações e, em seguida, selecione Registos de aplicações.
Selecione o item de menu Novo registo na parte superior do painel Registos de Aplicações .
Introduza MS Graph Batch App no campo Nome . Na secção Tipos de conta suportados , selecione Contas em qualquer diretório organizacional. Deixe a secção URI de Redirecionamento em branco e selecione Registar.
No painel Aplicação Do Batch do MS Graph, copie o ID da Aplicação (cliente). Irá precisar disto no próximo exercício.
Selecione a entrada permissões de API na secção Gerir do painel Aplicação do Batch do MS Graph. Selecione Adicionar uma permissão em Permissões de API.
No painel Pedir permissões da API , selecione o Microsoft Graph e, em seguida, selecione Permissões delegadas. Procure e group, em seguida, selecione a permissão Ler e escrever todos os grupos delegados.
Selecione Adicionar permissões na parte inferior do painel.
Selecione a entrada Certificados e segredos na secção Gerir do painel MS Graph Batch App e, em seguida, selecione Novo segredo do cliente. Introduza uma descrição, escolha uma duração e selecione Adicionar.
Copie o valor do novo segredo. Irá precisar disto no próximo exercício.
Importante
Este passo é crítico, uma vez que o segredo não estará acessível depois de fechar este painel. Guarde este segredo num editor de texto para utilizar em exercícios futuros.
Para ativar a gestão de serviços adicionais acessíveis através do Microsoft Graph, incluindo as propriedades do Teams, teria de selecionar âmbitos adicionais e adequados para permitir a gestão de serviços específicos. Por exemplo, para expandir a nossa solução para permitir a criação de blocos de notas do OneNote ou planos do Planner, registos e tarefas, teria de adicionar os âmbitos de permissão necessários para as APIs relevantes.
Criar um conector personalizado
Neste exercício, irá criar um novo conector personalizado que pode ser utilizado no Microsoft Power Automate ou no Azure Logic Apps. O ficheiro de definição OpenAPI é pré-criado com o caminho correto para o ponto final do Microsoft Graph $batch e definições adicionais para ativar a importação simples.
Abra um browser e navegue para o Microsoft Power Automate. Inicie sessão com a sua conta de administrador inquilino do Microsoft 365. Selecione Conectores personalizados no menu do lado esquerdo. Se a opção Conectores personalizados não estiver presente no menu, selecione Mais e, em seguida, Detetar tudo.
Existem duas opções para criar um conector personalizado para o Microsoft Graph:
- Criar do zero
- Importar um ficheiro OpenAPI
Na página Conectores Personalizados , selecione a ligação Novo conector personalizado no canto superior direito e, em seguida, selecione o item Criar do zero no menu pendente.
Introduza MS Graph Batch Connector na caixa de texto Nome do conector . Choose Continue.
Na página Configuração do conector Geral , preencha os campos da seguinte forma.
- Esquema: HTTPS
-
Anfitrião:
graph.microsoft.com -
URL base:
/
Selecione o botão Segurança para continuar.
Na página Segurança , preencha os campos da seguinte forma.
-
Escolha que autenticação é implementada pela sua API:
OAuth 2.0 -
Fornecedor de Identidade:
Azure Active Directory - ID do cliente: o ID da aplicação que criou no exercício anterior
- Segredo do cliente: a chave que criou no exercício anterior
-
URL de início de sessão:
https://login.windows.net -
ID do Inquilino:
common -
URL do Recurso:
https://graph.microsoft.com(sem à direita /) - Âmbito: deixe em branco
Selecione o botão Definição para continuar.
Na página Definição , selecione Nova Ação e preencha os campos da seguinte forma.
-
Resumo:
Batch -
Descrição:
Execute Batch with Delegate Permission -
ID da Operação:
Batch -
Visibilidade:
important
Crie Pedido ao selecionar Importar do Exemplo e preencha os campos da seguinte forma.
-
Verbo:
POST -
URL:
https://graph.microsoft.com/v1.0/$batch - Cabeçalhos: deixe em branco
-
Corpo:
{}
Selecione Importar.
Selecione Criar Conector no canto superior direito.
Após a criação do conector, copie o URL de Redirecionamento gerado a partir do separador Segurança .
Volte à aplicação registada no Portal do Microsoft Entra que criou no exercício anterior. Selecione Autenticação no menu do lado esquerdo. Selecione Adicionar uma plataformae, em seguida, selecione Web. Introduza o URL de redirecionamento copiado do passo anterior nos URIs de Redirecionamento e, em seguida, selecione Configurar.
Autorizar o conector
O passo de configuração final para garantir que o conector está pronto para ser utilizado é autorizar e testar o conector personalizado para criar uma ligação em cache.
Importante
Os passos seguintes requerem que tenha sessão iniciada com privilégios de administrador.
No Microsoft Power Automate, selecioneLigações no menu do lado esquerdo. Se a opção Ligações não estiver presente no menu, selecione Mais. Selecione a ligação Nova ligação .
Localize o conector personalizado e conclua a ligação ao selecioná-lo e, em seguida, selecione Criar. Inicie sessão com a conta do Azure Active Directory do administrador inquilino do Microsoft 365.
Quando lhe forem pedidas as permissões pedidas, verifique o Consentimento em nome da sua organização e, em seguida, selecione Aceitar para autorizar permissões.
Depois de autorizar as permissões, é criada uma ligação no Power Automate.
O conector personalizado está agora configurado e ativado. Pode haver um atraso nas permissões que estão a ser aplicadas e disponíveis, mas o conector está agora configurado.
Testar envio em lote no Explorador do Graph
Antes de criar um Flow para consumir o novo conector, utilize o Microsoft Graph Explorer para descobrir algumas das capacidades e funcionalidades da criação de batches JSON no Microsoft Graph.
Abra o Explorador do Microsoft Graph no seu browser. Inicie sessão com a sua conta de administrador inquilino do Microsoft 365. Procure o Batch a partir das Consultas de exemplo.
Selecione a consulta de exemplo Executar GETs paralelos no menu esquerdo. Selecione o botão Executar Consulta no canto superior direito do ecrã.
A operação de lote de exemplo cria um lote de três pedidos HTTP GET e emite um único HTTP POST para o ponto final do /v1.0/$batch Graph.
{
"requests": [
{
"url": "/me?$select=displayName,jobTitle,userPrincipalName",
"method": "GET",
"id": "1"
},
{
"url": "/me/messages?$filter=importance eq 'high'&$select=from,subject,receivedDateTime,bodyPreview",
"method": "GET",
"id": "2"
},
{
"url": "/me/events",
"method": "GET",
"id": "3"
}
]
}
A resposta devolvida é apresentada abaixo. Tenha em atenção a matriz de respostas devolvidas pelo Microsoft Graph. As respostas aos pedidos em lotes podem aparecer numa ordem diferente da ordem dos pedidos no POST. A id propriedade deve ser utilizada para correlacionar pedidos de lote individuais com respostas em lote específicas.
Observação
A resposta foi truncada para legibilidade.
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
Cada resposta contém uma idpropriedade , status, headerse body . Se a status propriedade de um pedido indicar uma falha, contém body quaisquer informações de erro devolvidas pelo pedido.
Para garantir uma ordem de operações para os pedidos, os pedidos individuais podem ser sequenciados com a propriedade dependsOn .
Além das operações de sequenciação e dependência, a criação de batches JSON assume um caminho base e executa os pedidos a partir de um caminho relativo. Cada elemento de pedido em lote é executado a /v1.0/$batch partir dos pontos finais OR /beta/$batch , conforme especificado. Isto pode ter diferenças significativas, uma vez que o /beta ponto final pode devolver resultados adicionais que podem NÃO ser devolvidos no /v1.0 ponto final.
Por exemplo, execute as duas consultas seguintes no Explorador do Microsoft Graph.
- Consulte o
/v1.0/$batchponto final com o URL/me(copie e cole o pedido abaixo).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Agora, utilize o menu pendente do seletor de versões para alterar para o beta ponto final e faça exatamente o mesmo pedido.
Quais são as diferenças nos resultados devolvidos? Experimente outras consultas para identificar algumas das diferenças.
Além dos diferentes conteúdos de resposta dos /v1.0 pontos finais e /beta , é importante compreender os possíveis erros quando é feito um pedido de lote para o qual o consentimento de permissão não foi concedido. Por exemplo, segue-se um item de pedido em lote para criar um Bloco de Notas do OneNote.
{
"id": 1,
"url": "/groups/65c5ecf9-3311-449c-9904-29a2c76b9a50/onenote/notebooks",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Meeting Notes"
}
}
No entanto, se as permissões para criar Blocos de Notas do OneNote não tiverem sido concedidas, é recebida a seguinte resposta. Tenha em atenção que o código 403 (Forbidden) de estado e a mensagem de erro que indica que o token OAuth fornecido não inclui os âmbitos necessários para concluir a ação pedida.
{
"responses": [
{
"id": "1",
"status": 403,
"headers": {
"Cache-Control": "no-cache"
},
"body": {
"error": {
"code": "40004",
"message": "The OAuth token provided does not have the necessary scopes to complete the request.
Please make sure you are including one or more of the following scopes: Notes.ReadWrite.All,
Notes.Read.All (you provided these scopes: Group.Read.All,Group.ReadWrite.All,User.Read,User.Read.All)",
"innerError": {
"request-id": "92d50317-aa06-4bd7-b908-c85ee4eff0e9",
"date": "2018-10-17T02:01:10"
}
}
}
}
]
}
Cada pedido no seu lote irá devolver um código de estado e resultados ou informações de erro. Tem de processar cada uma das respostas para determinar o êxito ou a falha das operações de lote individuais.
Criar um fluxo
Neste exercício, irá criar um fluxo para utilizar o conector personalizado que criou em exercícios anteriores para criar e configurar um Microsoft Team. O fluxo utilizará o conector personalizado para enviar um pedido POST para criar um Grupo Unificado do Office 365, colocará em pausa durante a conclusão da criação do grupo e, em seguida, enviará um pedido PUT para associar o grupo a um Microsoft Team.
No final, o fluxo terá um aspeto semelhante à imagem seguinte:
Abra o Microsoft Power Automate no seu browser e inicie sessão com a sua conta de administrador inquilino do Office 365.
Selecione Os meus fluxos no painel de navegação esquerdo.
Selecione Novo fluxo e, em seguida, Fluxo de cloud instantânea. Introduza Create Team para Nome do fluxo e, em seguida, selecione Acionar manualmente um fluxo em Escolher como acionar este fluxo. Escolha Criar.
Selecione o item Acionar manualmente um fluxo e, em seguida, selecione Adicionar uma entrada, selecione Texto e introduza Name como título.
Selecione + em Acionar manualmente um item de fluxo e, em seguida, selecione Adicionar uma ação. Escreva Batch na caixa de pesquisa e defina o menu pendente Runtime como Personalizado. Adicione a ação Do Conector do Batch do MS Graph . Escolha as reticências e mude o nome desta ação para Batch POST-groups.
Na lista pendente Parâmetros avançados , selecione corpo. Adicione o seguinte código à caixa de texto Corpo da ação.
{
"requests": [
{
"url": "/groups",
"method": "POST",
"id": 1,
"headers": { "Content-Type": "application/json" },
"body": {
"description": "REPLACE",
"displayName": "REPLACE",
"groupTypes": ["Unified"],
"mailEnabled": true,
"mailNickname": "REPLACE",
"securityEnabled": false
}
}
]
}
Substitua cada REPLACE marcador de posição ao selecionar o Name valor do acionador manual no menu Adicionar conteúdo dinâmico .
Selecione + abaixo do item Batch POST-groups e, em seguida, selecione Adicionar uma ação. Procure delay e adicione uma ação Atraso e configure durante 1 minuto.
Selecione + por baixo do item Atraso e, em seguida, selecione Adicionar uma ação. Adicione a ação Do Conector do Batch do MS Graph . Escolha as reticências e mude o nome desta ação para Batch PUT-team.
Na lista pendente Parâmetros avançados , selecione corpo. Adicione o seguinte código à caixa de texto Corpo da ação.
{
"requests": [
{
"id": 1,
"url": "/groups/REPLACE/team",
"method": "PUT",
"headers": {
"Content-Type": "application/json"
},
"body": {
"memberSettings": {
"allowCreateUpdateChannels": true
},
"messagingSettings": {
"allowUserEditMessages": true,
"allowUserDeleteMessages": true
},
"funSettings": {
"allowGiphy": true,
"giphyContentRating": "strict"
}
}
}
]
}
Selecione o marcador REPLACE de posição e, em seguida, selecione Expressão no painel de conteúdo dinâmico. Adicione a seguinte fórmula à Expressão.
body('Batch_POST-groups').responses[0].body.id
Esta fórmula especifica que queremos utilizar o ID de grupo do resultado da primeira ação.
Selecione Guardar e, em seguida, selecione Testar para executar o fluxo.
Dica
Se receber um erro como The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template', a expressão está incorreta e provavelmente referencia uma ação de fluxo que não consegue encontrar. Certifique-se de que o nome da ação a que está a referenciar corresponde exatamente.
Selecione o botão de opção Ação manual e selecione Testar. Forneça um nome sem espaços e selecione Executar fluxo para criar uma Equipa.
Por fim, selecione Concluído para ver o registo de atividades. Após a conclusão do fluxo, o Seu Grupo e Equipa do Office 365 foram configurados. Selecione os itens de ação do Batch para ver os resultados das chamadas do JSON Batch. A outputs ação Batch PUT-team deve ter um código de estado de 201 para uma associação de Equipa com êxito semelhante à imagem abaixo.
Expandir o fluxo
O Fluxo que criou no exercício anterior utiliza a $batch API para fazer dois pedidos individuais ao Microsoft Graph. Chamar o $batch ponto final desta forma proporciona algum benefício e flexibilidade, mas o verdadeiro poder do $batch ponto final ocorre ao executar vários pedidos para o Microsoft Graph numa única $batch chamada. Neste exercício, irá expandir o exemplo de criação de um Grupo Unificado e associar uma Equipa para incluir a criação de vários Canais predefinidos para a Equipa num único $batch pedido.
Abra o Microsoft Power Automate no seu browser e inicie sessão com a sua conta de administrador inquilino do Microsoft 365. Selecione o Fluxo que criou no passo anterior e selecione Editar.
Selecione Novo passo e escreva Batch na caixa de pesquisa. Adicione a ação Do Conector do Batch do MS Graph . Escolha as reticências e mude o nome desta ação para Batch POST-channels.
Adicione o seguinte código à caixa de texto do corpo da ação.
{
"requests": [
{
"id": 1,
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Marketing Collateral",
"description": "Marketing collateral and documentation."
}
},
{
"id": 2,
"dependsOn": [
"1"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Vendor Contracts",
"description": "Vendor documents, contracts, agreements and schedules."
}
},
{
"id": 3,
"dependsOn": [
"2"
],
"url": "/teams/REPLACE/channels",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "General Client Agreements",
"description": "General Client documents and agreements."
}
}
]
}
Repare que os três pedidos acima estão a utilizar a propriedade dependsOn para especificar uma ordem de sequência e cada um executará um pedido POST para criar um novo canal na nova Equipa.
Selecione cada instância do REPLACE marcador de posição e, em seguida, selecione Expressão no painel de conteúdo dinâmico. Adicione a seguinte fórmula à Expressão.
body('Batch_PUT-team').responses[0].body.id
Selecione Guardar e, em seguida, selecione Testar para executar o Fluxo. Selecione o botão de opção Vou executar a ação do acionador e, em seguida, selecione Guardar & Teste. Introduza um nome de grupo exclusivo no campo Nome sem espaços e selecione Executar fluxo para executar o Fluxo.
Assim que o Fluxo for iniciado, selecione o botão Concluído para ver o registo de atividades. Quando o Fluxo for concluído, o resultado final da ação Batch POST-channels tem uma resposta de Estado HTTP 201 para cada Canal criado.
Navegue para o Microsoft Teams e inicie sessão com a sua conta de administrador inquilino do Microsoft 365. Verifique se a equipa que acabou de criar é apresentada e inclui os três canais criados pelo $batch pedido.
Embora a ação acima Batch POST-channels tenha sido implementada neste tutorial como uma ação separada, as chamadas para criar os canais poderiam ter sido adicionadas como chamadas adicionais na ação Batch PUT-team . Isto teria criado a Equipa e todos os Canais numa única chamada em lote. Experimente sozinho.
Por fim, lembre-se de que as chamadas JSON Batching devolverão um código de estado HTTP para cada pedido. Num processo de produção, poderá querer combinar o pós-processamento dos resultados com uma Apply to each ação e validar que cada resposta individual tem um código de estado 201 ou compensar quaisquer outros códigos de estado recebidos.
Parabéns!
Concluiu o tutorial do Microsoft Graph do Power Automate. Agora que tem um conector personalizado funcional que chama o Microsoft Graph, pode experimentar e adicionar novas funcionalidades. Visite a Descrição Geral do Microsoft Graph para ver todos os dados a que pode aceder com o Microsoft Graph.
Comentários
Forneça comentários sobre este tutorial no repositório do GitHub.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.