Criar um Conector Personalizado do Lote JSON do Microsoft Graph para o Power Automate
Há mais de 230 conectores fora da caixa para o Microsoft Power Automate. Muitos desses conectores usam o Microsoft Graph para se comunicar com pontos de extremidade específicos de produtos da Microsoft. Além disso, há outros cenários em que talvez seja necessário chamar o Microsoft Graph diretamente do Power Automate usando blocos básicos de construção do serviço, já que não há nenhum conector que se comunique diretamente com o Microsoft Graph para cobrir toda a API.
Além de abordar cenários para chamar o Microsoft Graph diretamente, vários pontos de extremidade do Microsoft API do Graph só dão suporte a permissões delegadas. O conector HTTP no Microsoft Power Automate permite integrações muito flexíveis, inclusive chamando o Microsoft Graph. No entanto, o conector HTTP não tem a capacidade de armazenar as credenciais de um usuário para habilitar cenários específicos de permissão delegada. Nesses casos, um conector personalizado pode ser criado para fornecer um wrapper em torno do microsoft API do Graph e habilitar o consumo da API com permissões delegadas.
Este laboratório aborda os dois cenários acima. Primeiro, você criará um conector personalizado para habilitar integrações com o Microsoft Graph, que exigem permissões delegadas. Em segundo lugar, você usará o ponto de extremidade de solicitação $batch para fornecer acesso à potência total do Microsoft Graph ao usar as permissões delegadas que exigem que um aplicativo tenha um usuário "conectado" presente.
Observação
Este é um tutorial sobre como criar um conector personalizado para uso no Microsoft Power Automate e nos Aplicativos Lógicos do Azure. Este tutorial pressupõe que você tenha lido a visão geral do conector personalizado para entender o processo.
Pré-requisitos
Para concluir este exercício neste post, você precisará do seguinte:
- Acesso do administrador a um locatário do Microsoft 365. Se você não tiver um locatário do Microsoft 365, poderá se qualificar para um por meio do Programa de Desenvolvedores do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
- Acesso ao Microsoft Power Automate.
Comentários
Forneça qualquer comentário sobre este tutorial no repositório GitHub.
Criar um registro de aplicativo do Azure AD
Neste exercício, você criará um novo Aplicativo do Azure Active Directory que será usado para fornecer as permissões delegadas para o conector personalizado.
Abra um navegador e navegue até o centro de administração do Azure Active Directory. Escolha o link do Azure Active Directory no menu de navegação esquerdo e escolha a entrada Registros de aplicativo na seção Gerenciar da folha do Azure Active Directory.
Escolha o item Novo menu de registro na parte superior da folha Registros de Aplicativo .
Insira MS Graph Batch App no campo Nome . Na seção Tipos de conta com suporte , selecione Contas em qualquer diretório organizacional. Deixe a seção URI de redirecionamento em branco e escolha Registrar.
Na folha Aplicativo do Lote do MS Graph , copie a ID do Aplicativo (cliente). Você precisará disso no próximo exercício.
Escolha a entrada de permissões de API na seção Gerenciar da folha Aplicativo do Lote do MS Graph . Escolha Adicionar uma permissão em permissões de API.
Na folha Solicitar permissões de API , escolha o Microsoft Graph e escolha Permissões delegadas. groupPesquise , em seguida, selecione a permissão Delegada Ler e gravar todos os grupos. Escolha Adicionar permissões na parte inferior da folha.
Escolha a entrada Certificados e segredos na seção Gerenciar da folha Aplicativo do Lote do MS Graph e escolha Novo segredo do cliente. Insira uma descrição, escolha uma duração e selecione Adicionar.
Copie o valor do novo segredo. Você precisará disso no próximo exercício.
Importante
Essa etapa é fundamental, pois o segredo não será acessível quando você fechar essa folha. Salve esse segredo em um editor de texto para uso em exercícios futuros.
Para habilitar o gerenciamento de serviços adicionais acessíveis por meio do Microsoft Graph, incluindo propriedades do Teams, você precisaria selecionar escopos adicionais e apropriados para habilitar o gerenciamento de serviços específicos. Por exemplo, para estender nossa solução para permitir a criação de notebooks ou Planner planos, buckets e tarefas necessárias para adicionar os escopos de permissão necessários para as APIs relevantes.
Criar um conector personalizado
Neste exercício, você criará um novo conector personalizado que pode ser usado no Microsoft Power Automate ou nos Aplicativos Lógicos do Azure. O arquivo de definição OpenAPI é predefinido com o caminho correto para o ponto de extremidade do Microsoft Graph $batch e configurações adicionais para habilitar a importação simples.
Abra um navegador e navegue até o Microsoft Power Automate. Entre com sua conta de administrador de locatários do Microsoft 365. Escolha Dados no menu do lado esquerdo e selecione o item Conectores Personalizados no menu suspenso.
Há duas opções para criar um conector personalizado para o Microsoft Graph:
- Criar em branco
- Importar um arquivo OpenAPI
Na página Conectores Personalizados , escolha o novo link do conector personalizado na parte superior direita e selecione o item Criar em branco no menu suspenso.
Insira MS Graph Batch Connector na caixa de texto Nome do Conector . Choose Continue.
Na página geral de configuração do conector, preencha os campos da seguinte maneira.
- Esquema: HTTPS
- Host:
graph.microsoft.com - URL base:
/
Escolha Botão Segurança para continuar.
Na página Segurança , preencha os campos da seguinte maneira.
- Escolha qual autenticação é implementada pela sua API:
OAuth 2.0 - Provedor de Identidade:
Azure Active Directory - ID do cliente: a ID do aplicativo que você criou no exercício anterior
- Segredo do cliente: a chave que você criou no exercício anterior
- Url de logon:
https://login.windows.net - ID do locatário:
common - URL do recurso:
https://graph.microsoft.com(sem trailing /) - Escopo: deixar em branco
Escolha o botão Definição para continuar.
Na página Definição , selecione Nova Ação e preencha os campos da seguinte maneira.
- Resumo:
Batch - Descrição:
Execute Batch with Delegate Permission - ID da operação:
Batch - Visibilidade:
important
Crie Solicitação selecionando Importar de Exemplo e preencha os campos da seguinte maneira.
- Verbo:
POST - URL:
https://graph.microsoft.com/v1.0/$batch - Cabeçalhos: deixe em branco
- Corpo:
{}
Selecione Importar.
Escolha Criar Conector na parte superior direita.
Depois que o conector for criado, copie a URL de Redirecionamento gerada.
Voltar ao aplicativo registrado no Portal do Azure que você criou no exercício anterior. Selecione Autenticação no menu do lado esquerdo. Selecione Adicionar uma plataformae, em seguida, selecione Web. Insira a URL de redirecionamento copiada da etapa anterior nas URIs de Redirecionamento e selecione Configurar.
Autorizar o conector
A etapa final de configuração para garantir que o conector esteja pronto para uso é autorizar e testar o conector personalizado para criar uma conexão armazenada em cache.
Importante
As etapas a seguir exigem que você esteja conectado com privilégios de administrador.
No Microsoft Power Automate, acesse o item menu Dados à esquerda e escolha a página Connections. Escolha o link Nova Conexão .
Encontre o conector personalizado e conclua a conexão selecionando-a e escolhendo Criar. Entre com a conta do Azure Active Directory do administrador de locatários do Microsoft 365.
Quando solicitado para as permissões solicitadas, marcar Consentimento em nome de sua organização e, em seguida, escolha Aceitar para autorizar permissões.
Depois de autorizar as permissões, uma conexão será criada no Power Automate.
O conector personalizado agora está configurado e habilitado. Pode haver um atraso nas permissões que estão sendo aplicadas e disponíveis, mas o conector agora está configurado.
Testar envio em lote no Explorador do Graph
Antes de criar um Flow para consumir o novo conector, use o Microsoft Graph Explorer para descobrir alguns dos recursos e recursos do lote JSON no Microsoft Graph.
Abra a Explorer do Microsoft Graph em seu navegador. Entre com sua conta de administrador de locatários do Microsoft 365. Pesquise o Lote nas consultas de exemplo.
Selecione a consulta de exemplo Executar GETs paralelos no menu esquerdo. Escolha o botão Executar Consulta na parte superior direita da tela.
A operação do lote de exemplo agrupa três solicitações HTTP GET e emite um único POST HTTP para o ponto de extremidade 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 retornada é mostrada abaixo. Observe a matriz de respostas retornadas pelo Microsoft Graph. As respostas às solicitações em lote podem aparecer em uma ordem diferente da ordem das solicitações no POST. A id propriedade deve ser usada para correlacionar solicitações de lote individuais com respostas específicas em lote.
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 uma solicitação indicar uma falha, ela body conterá qualquer informação de erro retornada da solicitação.
Para garantir uma ordem de operações para as solicitações, as solicitações individuais podem ser sequenciadas usando a propriedade dependOn .
Além das operações de sequenciamento e dependência, o lote JSON assume um caminho base e executa as solicitações de um caminho relativo. Cada elemento de solicitação em lote é executado dos /v1.0/$batch pontos de extremidade OR /beta/$batch , conforme especificado. Isso pode ter diferenças significativas, pois o /beta ponto de extremidade pode retornar uma saída adicional que não pode ser retornada no /v1.0 ponto de extremidade.
Por exemplo, execute as duas consultas a seguir no Microsoft Graph Explorer.
- Consulte o
/v1.0/$batchponto de extremidade usando a url/me(copie e cole a solicitação abaixo).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Agora, use a lista suspensa seletor de versão para alterar para o beta ponto de extremidade e faça exatamente a mesma solicitação.
Quais são as diferenças nos resultados retornados? Experimente algumas outras consultas para identificar algumas das diferenças.
Além de diferentes conteúdos de resposta dos /v1.0 pontos de extremidade e /beta , é importante entender os possíveis erros quando uma solicitação em lote é feita para o qual o consentimento da permissão não foi concedido. Por exemplo, o seguinte é um item de solicitação em lote para criar um Notebook 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 notebooks do OneNote não tiverem sido concedidas, a resposta a seguir será recebida. Observe que o código 403 (Forbidden) status e a mensagem de erro que indica que o token OAuth fornecido não inclui os escopos necessários para concluir a ação solicitada.
{
"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 solicitação em seu lote retornará uma status código e resultados ou informações de erro. Você deve processar cada uma das respostas para determinar o êxito ou a falha das operações de lote individuais.
Criar um fluxo
Neste exercício, você criará um fluxo para usar o conector personalizado criado em exercícios anteriores para criar e configurar um Microsoft Team. O fluxo usará o conector personalizado para enviar uma solicitação POST para criar um grupo unificado Office 365, pausará por um atraso enquanto a criação do grupo for concluída e, em seguida, enviará uma solicitação PUT para associar o grupo a uma Equipe da Microsoft.
No final, seu fluxo será semelhante à seguinte imagem:
Abra o Microsoft Power Automate no navegador e entre com sua Office 365 conta de administrador de locatários. Escolha Meus fluxos na navegação à esquerda. Escolha Novo e, em seguida, Instantâneo — em branco. Insira Create Team para Nome do Fluxo e, em seguida, selecione Disparar manualmente um fluxo em Escolher como disparar esse fluxo. Escolha Criar.
Selecione disparar manualmente um item de fluxo e, em seguida, escolha Adicionar uma entrada, selecione Texto e insira Name como o título.
Escolha Nova etapa e digite Batch na caixa de pesquisa. Adicione a ação do Conector do Lote do MS Graph . Escolha as reticências e renomeie esta ação como Batch POST-groups.
Adicione o código a seguir à caixa de texto do 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 espaço reservado selecionando o Name valor no gatilho manual no menu Adicionar conteúdo dinâmico .
Escolha Nova etapa, pesquise delay e adicione uma ação Atraso e configure por 1 minuto.
Escolha Nova etapa e digite Batch na caixa de pesquisa. Adicione a ação do Conector do Lote do MS Graph . Escolha as reticências e renomeie esta ação como Batch PUT-team.
Adicione o código a seguir à caixa de texto do 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 REPLACE espaço reservado e selecione Expressão no painel de conteúdo dinâmico. Adicione a fórmula a seguir à Expressão.
body('Batch_POST-groups').responses[0].body.id
Essa fórmula especifica que queremos usar a ID do grupo do resultado da primeira ação.
Escolha Salvar e escolha Testar para executar o fluxo.
Dica
Se você 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 pode encontrar. Verifique se o nome da ação que você está fazendo referência corresponde exatamente.
Escolha o botão Desativar o rádio de ação de gatilho e escolha Salvar & Teste. Escolha Continuar na caixa de diálogo. Forneça um nome sem espaços e escolha Executar fluxo para criar uma Equipe.
Por fim, escolha o Concluído para ver o log de atividades. Depois que o fluxo for concluído, o grupo de Office 365 e a equipe foram configurados. Selecione os itens de ação Lote para exibir os resultados das chamadas do Lote JSON. A outputs da ação Batch PUT-team deve ter um código status de 201 para uma associação de equipe bem-sucedida semelhante à imagem abaixo.
Estender o fluxo
O Flow criado no exercício anterior usa a $batch API para fazer duas solicitações individuais para o Microsoft Graph. Chamar o $batch ponto de extremidade dessa forma fornece algum benefício e flexibilidade, mas o verdadeiro poder do ponto de $batch extremidade vem ao executar várias solicitações ao Microsoft Graph em uma única $batch chamada. Neste exercício, você estenderá o exemplo de criar um Grupo Unificado e associar uma Equipe para incluir a criação de vários canais padrão para a Equipe em uma única $batch solicitação.
Abra o Microsoft Power Automate no navegador e entre com sua conta de administrador de locatários do Microsoft 365. Selecione o Fluxo que você criou na etapa anterior e escolha Editar.
Escolha Nova etapa e digite Batch na caixa de pesquisa. Adicione a ação do Conector do Lote do MS Graph . Escolha as reticências e renomeie esta ação como Batch POST-channels.
Adicione o código a seguir à 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."
}
}
]
}
Observe que as três solicitações acima estão usando a propriedade dependOn para especificar uma ordem de sequência e cada uma executará uma solicitação POST para criar um novo canal na nova Equipe.
Selecione cada instância do REPLACE espaço reservado e selecione Expressão no painel de conteúdo dinâmico. Adicione a fórmula a seguir à Expressão.
body('Batch_PUT-team').responses[0].body.id
Escolha Salvar e escolha Testar para executar o Fluxo. Selecione o botão de rádio de ação de gatilho e, em seguida, escolha Salvar & Teste. Insira um nome de grupo exclusivo no campo Nome sem espaços e escolha Executar fluxo para executar o Fluxo.
Depois que o Fluxo for iniciado, escolha o botão Concluído para ver o log de atividades. Quando o Fluxo for concluído, a saída final da ação Batch POST-channels terá uma resposta de status HTTP 201 para cada Canal criado.
Navegue até o Microsoft Teams e entre com sua conta de administrador de locatários do Microsoft 365. Verifique se a equipe que você acabou de criar aparece e inclui os três canais criados pela solicitação $batch .
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 . Isso teria criado a Equipe e todos os Canais em uma única chamada em lote. Experimente isso por conta própria.
Por fim, lembre-se de que as chamadas de lote JSON retornarão um código HTTP status para cada solicitação. Em um processo de produção, você pode querer combinar o processamento pós-processamento dos resultados com uma Apply to each ação e validar cada resposta individual tem um código 201 status ou compensar quaisquer outros códigos status recebidos.
Parabéns!
Você concluiu o tutorial do Microsoft Graph do Power Automate. Agora que você tem um conector personalizado funcionando que chama Microsoft Graph, você pode experimentar e adicionar novos recursos. Visite a visão geral do Microsoft Graph para ver todos os dados que você pode acessar com o Microsoft Graph.
Comentários
Forneça qualquer comentário sobre este tutorial no repositório GitHub.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.