Criar um conector personalizado de lote do Microsoft Graph JSON para automatização de energia
Há mais de 230 conectores de caixa de entrada para o Microsoft Power Automate. Muitos desses conectores usam o microsoft Graph para se comunicar com pontos de extremidade específicos dos produtos Microsoft. Além disso, há outros cenários em que talvez seja necessário chamar o Microsoft Graph diretamente do Power Automate usando blocos de construção básicos do serviço, já que não há nenhum conector que se comunique diretamente com o microsoft Graph para abranger toda a API.
Além dos cenários de endereçamento para chamar o Microsoft Graph diretamente, alguns pontos de extremidade da API Graph Microsoft só 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 cache das 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 da API do Microsoft Graph e habilitar o consumo da API com permissões delegadas.
Este laboratório abrange ambos os 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 "in-locar" presente.
Observação
Este é um tutorial sobre a criação de um conector personalizado para uso no Microsoft Power Automate e Aplicativos Lógicos do Azure. Este tutorial supõe que você leu a visão geral do conector personalizado para entender o processo.
Pré-requisitos
Para concluir esse exercício nesta postagem, você precisará do seguinte:
- Acesso de administrador a uma Office 365 local. Se você não tiver um, visite o programa de desenvolvedor Microsoft 365 para se inscrever em um locatário de desenvolvedor GRATUITO.
- 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 Azure Active Directory que será usado para fornecer as permissões delegadas para o conector personalizado.
Abra um navegador e navegue até Azure Active Directory admin center. Escolha o Azure Active Directory no menu de navegação à esquerda e escolha a entrada Registros de aplicativo na seção Gerenciar da Azure Active Directory.
Escolha o item de menu Novo registro na parte superior da folha Registros de Aplicativos.
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 Redirecionar URI em branco e escolha Registrar.
Na folha MS Graph Aplicativo em Lote, 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 MS Graph Batch App. Escolha Adicionar uma permissão em permissões de API.
Na folha Solicitar permissões de API, escolha o Microsoft Graph, em seguida, escolha Permissões delegadas. groupPesquise , selecione a permissão Ler e gravar todos os grupos delegados. Escolha Adicionar permissões na parte inferior da folha.
Escolha a entrada Certificados e segredos na seção Gerenciar da folha MS Graph Batch App e escolha Novo segredo do cliente. Insira forever a Descrição e selecione Nunca em Expira. Escolha Adicionar.
Copie o valor do novo segredo. Você precisará disso no próximo exercício.
Importante
Esta etapa é fundamental, pois o segredo não será acessível depois que você fechar essa folha. Salve esse segredo em um editor de texto para uso nos próximos exercícios.
Para habilitar o gerenciamento de serviços adicionais acessíveis por meio do microsoft Graph, incluindo Teams propriedades, você precisaria selecionar escopos adicionais e apropriados para habilitar o gerenciamento de serviços específicos. Por exemplo, para estender nossa solução para habilitar a criação de blocos de anotações OneNote ou planos do Planner, buckets e tarefas necessários 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 no Aplicativos Lógicos do Azure. O arquivo de definição OpenAPI é pré-construído com o caminho correto para o ponto de extremidade do Microsoft Graph e configurações adicionais para $batch habilitar a importação simples.
Há duas opções para criar um conector personalizado para o Microsoft Graph:
- Criar em branco
- Importar um arquivo OpenAPI
Opção 1: Criar conector personalizado a partir de modelo em branco
Abra um navegador e navegue até Microsoft Power Automate. Entre com sua conta Office 365 administrador de locatários. Escolha Dados no menu do lado esquerdo e selecione o item Conectores Personalizados no menu suspenso.
Na página Conectores Personalizados, escolha o link Novo 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 Configuração geral do conector, preencha os campos da seguinte maneira.
- Esquema: HTTPS
- Host:
graph.microsoft.com - URL base:
/
Escolha o botão Segurança para continuar.
Na página Segurança, preencha os campos da seguinte forma.
- Escolha qual autenticação é implementada pela 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 /) - 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 forma.
- 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 forma.
- Verbo:
POST - URL:
https://graph.microsoft.com/v1.0/$batch - Headers: Deixar em branco
- Corpo:
{}
Selecione Importar.
Escolha Criar Conector no canto superior direito. Depois que o conector tiver sido criado, copie a URL de Redirecionamento gerada da página Segurança.
Volte para o aplicativo registrado no Portal do Azure que você criou no exercício anterior. Selecione Autenticação no menu do lado esquerdo. Selecione Adicionar uma plataforma e, em seguida, selecione Web. Insira a URL de redirecionamento copiada da etapa anterior nas URIs de redirecionamento e selecione Configurar.
Opção 2: Criar conector personalizado importando arquivo OpenAPI
Usando um editor de texto, crie um novo arquivo vazio chamado MSGraph-Delegate-Batch.swagger.json e adicione o código a seguir.
{
"swagger": "2.0",
"info": {
"title": "MS Graph Batch Connector",
"description": "",
"version": "1.0"
},
"host": "graph.microsoft.com",
"basePath": "/",
"schemes": [
"https"
],
"consumes": [],
"produces": [],
"paths": {
"/v1.0/$batch": {
"post": {
"responses": {
"default": {
"description": "default",
"schema": {}
}
},
"summary": "Batch",
"description": "Execute Batch with Delegate Permission",
"operationId": "Batch",
"x-ms-visibility": "important",
"parameters": [
{
"name": "body",
"in": "body",
"required": false,
"schema": {
"type": "object",
"properties": {}
}
}
]
}
}
},
"definitions": {},
"parameters": {},
"responses": {},
"securityDefinitions": {
"oauth2_auth": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
"tokenUrl": "https://login.windows.net/common/oauth2/authorize",
"scopes": {}
}
},
"security": [
{
"oauth2_auth": []
}
],
"tags": []
}
Abra um navegador e navegue até Microsoft Power Automate. Entre com sua conta Office 365 administrador de locatários. Escolha Dados no menu do lado esquerdo e selecione o item Conectores Personalizados no menu suspenso.
Na página Conectores Personalizados, escolha o link Novo conector personalizado na parte superior direita e selecione Importar um item de arquivo OpenAPI no menu suspenso.
Insira MS Graph Batch Connector na caixa de texto Nome do conector. Escolha o ícone da pasta para carregar o arquivo OpenAPI. Navegue até MSGraph-Delegate-Batch.swagger.json o arquivo criado. Escolha Continuar para carregar o arquivo OpenAPI.
Na página de configuração do conector, escolha o link Segurança no menu de navegação. Preencha os campos da seguinte forma.
- Escolha qual autenticação é implementada pela 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 /) - Escopo: Deixar em branco
Escolha Criar Conector no canto superior direito. Depois que o conector tiver sido criado, copie a URL de Redirecionamento gerada.
Volte para o aplicativo registrado no Portal do Azure que você criou no exercício anterior. Selecione Autenticação no menu do lado esquerdo. Selecione Adicionar uma plataforma e, 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 em cache.
Importante
As etapas a seguir exigem que você está conectado com privilégios de administrador.
No Microsoft Power Automate, vá para o item de menu Dados à esquerda e escolha a página Conexões. Escolha o link Nova Conexão.
Encontre seu conector personalizado e conclua a conexão clicando no botão mais. Entre com a conta Office 365 do administrador Azure Active Directory de locatários.
Quando solicitado para as permissões solicitadas, verifique Consent em nome da sua organização e escolha Aceitar para autorizar permissões.
Depois de autorizar as permissões, uma conexão é criada 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 o Microsoft Graph Explorer no navegador. Entre com sua conta Office 365 administrador de locatários. Pesquise batch nas consultas de exemplo.
Selecione a consulta de exemplo Executar GETs paralelos no menu esquerdo. Escolha o botão Executar Consulta no canto superior direito da tela.
A operação em lotes de exemplo faz três solicitações HTTP GET e emite um único HTTP POST para o /v1.0/$batch Graph ponto de extremidade.
{
"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 pela 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 em lotes individuais com respostas específicas em lotes.
Observação
A resposta foi truncada para capacidade de leitura.
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
Cada resposta contém id uma propriedade , , e status headers body . Se a propriedade de uma solicitação indicar uma falha, a contém todas as informações status body de erro retornadas da solicitação.
Para garantir uma ordem de operações para as solicitações, solicitações individuais podem ser sequenciadas usando a propriedade dependsOn.
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 lotes é executado dos pontos /v1.0/$batch de extremidade OR conforme /beta/$batch especificado. Isso pode ter diferenças significativas, pois o ponto de extremidade pode retornar uma saída /beta adicional que pode não ser retornada no ponto de /v1.0 extremidade.
Por exemplo, execute as duas consultas a seguir no Microsoft Graph Explorer.
- Consultar o
/v1.0/$batchponto de extremidade usando a url/me(copiar e colar solicitação abaixo).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Agora use o drop-down do seletor de versão para alterar para o ponto beta de extremidade e faça exatamente a mesma solicitação.
Quais são as diferenças nos resultados retornados? Tente outras consultas para identificar algumas das diferenças.
Além do conteúdo de resposta diferente dos pontos de extremidade e, é importante entender os possíveis erros quando uma solicitação em lote é feita para o qual o consentimento de permissão não foi /v1.0 /beta concedido. Por exemplo, o seguinte é um item de solicitação em lote para criar um bloco OneNote Bloco de Anotações.
{
"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 OneNote blocos de anotações não foram concedidas, a resposta a seguir será recebida. Observe que o código de status e a mensagem de erro que indica que o token OAuth fornecido não inclui os escopos necessários para concluir 403 (Forbidden) 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á um código de status e resultados ou informações de erro. Você deve processar cada uma das respostas para determinar o sucesso ou a falha das operações individuais em lotes.
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 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 seu navegador e entre com sua conta Office 365 administrador de locatários. Escolha Meus fluxos na navegação à esquerda. Escolha Novo, e, em seguida, Instantâneo-- em branco. Digite Create Team para Flow nome, em seguida, selecione Disparar manualmente um fluxo em Escolher como disparar esse fluxo. Escolha Criar.
Selecione o gatilho manualmente de um item de fluxo, escolha Adicionar uma entrada, selecione Texto e insira como Name o título.
Escolha Nova etapa e digite na caixa de Batch pesquisa. Adicione a ação MS Graph Batch Connector. Escolha a reellipse e renomeie essa ação para 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 Name o valor no gatilho manual no menu Adicionar conteúdo dinâmico.
Escolha Nova etapa, pesquise e adicione uma ação delay Atraso e configure por 1 minuto.
Escolha Nova etapa e digite na caixa de Batch pesquisa. Adicione a ação MS Graph Batch Connector. Escolha a reellipse e renomeie essa ação para 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 seguinte fórmula à expressão.
body('Batch_POST-groups').responses[0].body.id
Essa fórmula especifica que queremos usar a ID do grupo a partir do resultado da primeira ação.
Escolha Salvar e, em seguida, escolha Testar para executar o fluxo.
Dica
Se você receber um erro como , a expressão está incorreta e The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template' provavelmente faz referência a uma ação de fluxo que não consegue encontrar. Verifique se o nome da ação que você está fazendo referência corresponde exatamente.
Escolha o botão de opção 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 Done para ver o log de atividades. Depois que o fluxo for concluído, Office 365 grupo e equipe serão configurados. Selecione os itens de ação Batch para exibir os resultados das chamadas JSON Batch. A outputs ação deve ter um código de status 201 para uma associação de equipe bem-sucedida Batch PUT-team semelhante à imagem abaixo.
Estender o fluxo
A Flow criada no exercício anterior usa a API para fazer duas solicitações individuais para o $batch Microsoft Graph. Chamar o ponto de extremidade dessa forma fornece algum benefício e flexibilidade, mas o verdadeiro poder do ponto de extremidade vem ao executar várias solicitações para a Microsoft Graph em uma $batch $batch única $batch chamada. Neste exercício, você estenderá o exemplo de criação de um Grupo Unificado e da associação de 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 seu navegador e entre com sua conta Office 365 administrador de locatários. Selecione a Flow que você criou na etapa anterior e escolha Editar.
Escolha Nova etapa e digite na caixa de Batch pesquisa. Adicione a ação MS Graph Batch Connector. Escolha a reellipse e renomeie essa ação para 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 dependsOn 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 seguinte fórmula à expressão.
body('Batch_PUT-team').responses[0].body.id
Escolha Salvar e, em seguida, escolha Testar para executar o Flow. Selecione o botão de botão de opção 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 Flow.
Depois que o Flow iniciar, escolha o botão Feito para ver o log de atividades. Quando a Flow for concluída, a saída final da ação terá uma resposta Batch POST-channels de Status HTTP 201 para cada Canal criado.
Navegue até Microsoft Teams e entre com sua conta Office 365 administrador de locatários. Verifique se a equipe que você acabou de criar aparece e inclui os três canais criados pela $batch solicitação.
Embora a ação acima tenha sido implementada neste tutorial como uma ação separada, as chamadas para criar os canais poderiam ter sido adicionadas como chamadas adicionais Batch POST-channels na Batch PUT-team ação. Isso teria criado a Equipe e todos os Canais em uma única chamada em lotes. Experimente isso por conta própria.
Por fim, lembre-se de que as chamadas JSON Batching retornarão um código de status HTTP para cada solicitação. Em um processo de produção, você pode combinar o pós-processamento dos resultados com uma ação e validar cada resposta individual tem um código de status 201 ou compensar quaisquer outros códigos de Apply to each status recebidos.
Parabéns!
Você concluiu o tutorial Power Automate microsoft Graph. Agora que você tem um conector personalizado que chama a 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.