Creación de un conector personalizado de Batch JSON de Microsoft Graph para Power Automate
Hay más de 230 conectores de fábrica para Microsoft Power Automate. Muchos de estos conectores usan Microsoft Graph para comunicarse con puntos de conexión específicos de productos de Microsoft. Además, hay otros escenarios en los que es posible que debamos llamar a Microsoft Graph directamente desde Power Automate mediante bloques de creación básicos del servicio, ya que no hay ningún conector que se comunique directamente con Microsoft Graph para cubrir toda la API.
Además de abordar escenarios para llamar directamente a Microsoft Graph, varios puntos de conexión de Microsoft Graph API solo admiten permisos delegados. El conector HTTP de Microsoft Power Automate permite integraciones muy flexibles, incluida la llamada a Microsoft Graph. Sin embargo, el conector HTTP carece de la capacidad de almacenar en caché las credenciales de un usuario para habilitar escenarios de permisos delegados específicos. En estos casos, se puede crear un conector personalizado para proporcionar un contenedor alrededor de Microsoft Graph API y habilitar el consumo de la API con permisos delegados.
En este laboratorio se tratan los dos escenarios anteriores. En primer lugar, creará un conector personalizado para habilitar las integraciones con Microsoft Graph que requieren permisos delegados. En segundo lugar, usará el punto de conexión de solicitud de $batch para proporcionar acceso a toda la eficacia de Microsoft Graph mientras usa los permisos delegados que requieren que una aplicación tenga un usuario "iniciado sesión" presente.
Nota:
Este es un tutorial sobre la creación de un conector personalizado para su uso en Microsoft Power Automate y Azure Logic Apps. En este tutorial se supone que ha leído la información general del conector personalizado para comprender el proceso.
Requisitos previos
Para completar este ejercicio en esta publicación necesitará lo siguiente:
- Acceso de administrador a un inquilino de Microsoft 365. Si no tiene un inquilino de Microsoft 365, puede calificar para uno a través del Programa para desarrolladores de Microsoft 365; Para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.
- Acceso a Microsoft Power Automate.
Comentarios
Proporcione comentarios sobre este tutorial en el repositorio de GitHub.
Crear un registro de la aplicación de Azure AD
En este ejercicio, creará una nueva aplicación de Azure Active Directory que se usará para proporcionar los permisos delegados para el conector personalizado.
Abra un explorador y vaya al Centro de administración de Azure Active Directory. Elija el vínculo Azure Active Directory en el menú de navegación izquierdo y, a continuación, elija la entrada Registros de aplicaciones en la sección Administrar de la hoja Azure Active Directory.
Elija el elemento de menú Nuevo registro en la parte superior de la hoja Registros de aplicaciones.
Escriba MS Graph Batch App en el campo Nombre . En la sección Tipos de cuenta admitidos , seleccione Cuentas en cualquier directorio organizativo. Deje en blanco la sección URI de redirección y elija Registrar.
En la hoja Aplicación de Batch de MS Graph, copie el identificador de aplicación (cliente). Necesitará esto en el siguiente ejercicio.
Elija la entrada permisos de API en la sección Administrar de la hoja Aplicación de Batch de MS Graph . Elija Agregar un permiso en Permisos de API.
En la hoja Solicitar permisos de API , elija Microsoft Graph y, a continuación, elija Permisos delegados. Busque groupy, a continuación, seleccione el permiso delegado Leer y escribir todos los grupos . Elija Agregar permisos en la parte inferior de la hoja.
Elija la entrada Certificados y secretos en la sección Administrar de la hoja Aplicación de Batch de MS Graph y, a continuación, elija Nuevo secreto de cliente. Escriba una descripción, elija una duración y seleccione Agregar.
Copie el valor del nuevo secreto. Necesitará esto en el siguiente ejercicio.
Importante
Este paso es fundamental, ya que el secreto no será accesible una vez que cierre esta hoja. Guarde este secreto en un editor de texto para usarlo en los próximos ejercicios.
Para habilitar la administración de servicios adicionales accesibles a través de Microsoft Graph, incluidas las propiedades de Teams, tendría que seleccionar ámbitos adicionales y adecuados para habilitar la administración de servicios específicos. Por ejemplo, para ampliar nuestra solución para habilitar la creación de blocs de notas de OneNote o planes de Planner, cubos y tareas, tendría que agregar los ámbitos de permisos necesarios para las API pertinentes.
Crear un conector personalizado
En este ejercicio, creará un nuevo conector personalizado que se puede usar en Microsoft Power Automate o en Azure Logic Apps. El archivo de definición de OpenAPI se ha creado previamente con la ruta de acceso correcta para el punto de conexión de Microsoft Graph $batch y una configuración adicional para habilitar la importación sencilla.
Abra un explorador y vaya a Microsoft Power Automate. Inicie sesión con su cuenta de administrador de inquilinos de Microsoft 365. Elija Datos en el menú izquierdo y seleccione el elemento Conectores personalizados en el menú desplegable.
Hay dos opciones para crear un conector personalizado para Microsoft Graph:
- Crear desde cero
- Importación de un archivo OpenAPI
En la página Conectores personalizados , elija el vínculo Nuevo conector personalizado en la parte superior derecha y, a continuación, seleccione el elemento Crear desde en blanco en el menú desplegable.
Escriba MS Graph Batch Connector en el cuadro de texto Nombre del conector . Choose Continue.
En la página General de configuración del conector, rellene los campos como se indica a continuación.
- Esquema: HTTPS
- Host:
graph.microsoft.com - Dirección URL base:
/
Elija el botón Seguridad para continuar.
En la página Seguridad , rellene los campos como se indica a continuación.
- Elija qué autenticación implementa la API:
OAuth 2.0 - Proveedor de identidades:
Azure Active Directory - Id. de cliente: el identificador de aplicación que creó en el ejercicio anterior.
- Secreto de cliente: la clave que creó en el ejercicio anterior
- Dirección URL de inicio de sesión:
https://login.windows.net - Identificador de inquilino:
common - Dirección URL del recurso:
https://graph.microsoft.com(sin final /) - Ámbito: deje en blanco
Elija el botón Definición para continuar.
En la página Definición , seleccione Nueva acción y rellene los campos como se indica a continuación.
- Resumen:
Batch - Descripción:
Execute Batch with Delegate Permission - Identificador de operación:
Batch - Visibilidad:
important
Para crear solicitud , seleccione Importar desde ejemplo y rellene los campos como se indica a continuación.
- Verbo:
POST - URL:
https://graph.microsoft.com/v1.0/$batch - Encabezados: deje en blanco
- Cuerpo:
{}
Seleccione Importar.
Elija Crear conector en la parte superior derecha.
Una vez creado el conector, copie la dirección URL de redireccionamiento generada.
Volver a la aplicación registrada en Azure Portal que creó en el ejercicio anterior. Seleccione Autenticación en el menú de la izquierda. Seleccione Agregar una plataformay, a continuación, seleccione web. Escriba la dirección URL de redireccionamiento copiada del paso anterior en los URI de redireccionamiento y, a continuación, seleccione Configurar.
Autorizar el conector
El paso de configuración final para asegurarse de que el conector está listo para su uso es autorizar y probar el conector personalizado para crear una conexión almacenada en caché.
Importante
Los pasos siguientes requieren que haya iniciado sesión con privilegios de administrador.
En Microsoft Power Automate, vaya al elemento de menú Datos de la izquierda y elija la página Connections. Elija el vínculo Nueva conexión .
Busque el conector personalizado y complete la conexión seleccionándolo y, a continuación, elija Crear. Inicie sesión con la cuenta de Azure Active Directory del administrador de inquilinos de Microsoft 365.
Cuando se le soliciten los permisos solicitados, compruebe Consentimiento en nombre de su organización y, a continuación, elija Aceptar para autorizar permisos.
Después de autorizar los permisos, se crea una conexión en Power Automate.
El conector personalizado ahora está configurado y habilitado. Puede haber un retraso en la aplicación de permisos y disponible, pero el conector ya está configurado.
Probar el procesamiento por lotes en el Probador de Graph
Antes de crear un flujo para consumir el nuevo conector, use el Explorador de Microsoft Graph para detectar algunas de las funcionalidades y características del procesamiento por lotes JSON en Microsoft Graph.
Abra el Explorador de Microsoft Graph en el explorador. Inicie sesión con su cuenta de administrador de inquilinos de Microsoft 365. Busque Batch en las consultas de ejemplo.
Seleccione la consulta de ejemplo Realizar gets paralelos en el menú de la izquierda. Elija el botón Ejecutar consulta en la parte superior derecha de la pantalla.
La operación por lotes de ejemplo procesa por lotes tres solicitudes HTTP GET y emite un único HTTP POST al punto de conexión de /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"
}
]
}
La respuesta devuelta se muestra a continuación. Tenga en cuenta la matriz de respuestas devuelta por Microsoft Graph. Las respuestas a las solicitudes por lotes pueden aparecer en un orden diferente al de las solicitudes en POST. La id propiedad debe usarse para correlacionar solicitudes por lotes individuales con respuestas por lotes específicas.
Nota:
La respuesta se ha truncado para mejorar la legibilidad.
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {...},
"body": {...}
},
{
"id": "3",
"status": 200,
"headers": {...},
"body": {...}
}
{
"id": "2",
"status": 200,
"headers": {...},
"body": {...}
}
]
}
Cada respuesta contiene una idpropiedad , status, headersy body . Si la status propiedad de una solicitud indica un error, contiene toda la body información de error devuelta por la solicitud.
Para garantizar un orden de operaciones para las solicitudes, las solicitudes individuales se pueden secuenciar mediante la propiedad dependsOn .
Además de las operaciones de secuenciación y dependencia, el procesamiento por lotes JSON asume una ruta de acceso base y ejecuta las solicitudes desde una ruta de acceso relativa. Cada elemento de solicitud por lotes se ejecuta desde los /v1.0/$batch puntos de conexión OR /beta/$batch según lo especificado. Esto puede tener diferencias significativas, ya que el /beta punto de conexión puede devolver una salida adicional que no se puede devolver en el /v1.0 punto de conexión.
Por ejemplo, ejecute las dos consultas siguientes en el Explorador de Microsoft Graph.
- Consulte el
/v1.0/$batchpunto de conexión mediante la dirección URL/me(copie y pegue la solicitud siguiente).
{
"requests": [
{
"id": 1,
"url": "/me",
"method": "GET"
}
]
}
Ahora, use la lista desplegable del selector de versiones para cambiar al beta punto de conexión y realizar exactamente la misma solicitud.
¿Cuáles son las diferencias en los resultados devueltos? Pruebe con otras consultas para identificar algunas de las diferencias.
Además del contenido de respuesta diferente de los /v1.0 puntos de conexión y /beta , es importante comprender los posibles errores cuando se realiza una solicitud por lotes para la que no se ha concedido el consentimiento de permisos. Por ejemplo, el siguiente es un elemento de solicitud por lotes para crear un bloc de notas de OneNote.
{
"id": 1,
"url": "/groups/65c5ecf9-3311-449c-9904-29a2c76b9a50/onenote/notebooks",
"headers": {
"Content-Type": "application/json"
},
"method": "POST",
"body": {
"displayName": "Meeting Notes"
}
}
Sin embargo, si no se han concedido los permisos para crear cuadernos de OneNote, se recibe la siguiente respuesta. Tenga en cuenta el código 403 (Forbidden) de estado y el mensaje de error que indica que el token de OAuth proporcionado no incluye los ámbitos necesarios para completar la acción 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 solicitud del lote devolverá un código de estado y resultados o información de error. Debe procesar cada una de las respuestas para determinar el éxito o el error de las operaciones por lotes individuales.
Crear un flujo
En este ejercicio, creará un flujo para usar el conector personalizado que creó en ejercicios anteriores para crear y configurar un equipo de Microsoft. El flujo usará el conector personalizado para enviar una solicitud POST para crear una Office 365 grupo unificado, se pausará durante un retraso mientras se complete la creación del grupo y, a continuación, enviará una solicitud PUT para asociar el grupo a un equipo de Microsoft.
Al final, el flujo será similar a la siguiente imagen:
Abra Microsoft Power Automate en el explorador e inicie sesión con su cuenta de administrador de inquilinos de Office 365. Elija Mis flujos en el panel de navegación izquierdo. Elija Nuevo y, a continuación, Instantánea, en blanco. Escriba Create Team en Nombre de flujo y, a continuación, seleccione Desencadenar manualmente un flujo en Elegir cómo desencadenar este flujo. Elija Crear.
Seleccione el elemento Desencadenador manual de un flujo, elija Agregar una entrada, texto y escriba Name como título.
Elija Nuevo paso y escriba Batch en el cuadro de búsqueda. Agregue la acción Conector de MS Graph Batch . Elija los puntos suspensivos y cambie el nombre de esta acción a Batch POST-groups.
Agregue el código siguiente al cuadro de texto del cuerpo de la acción.
{
"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
}
}
]
}
Reemplace cada REPLACE marcador de posición seleccionando el Name valor del desencadenador manual en el menú Agregar contenido dinámico .
Elija Nuevo paso, busque delay y agregue una acción Retraso y configúrelo durante 1 minuto.
Elija Nuevo paso y escriba Batch en el cuadro de búsqueda. Agregue la acción Conector de MS Graph Batch . Elija los puntos suspensivos y cambie el nombre de esta acción a Batch PUT-team.
Agregue el código siguiente al cuadro de texto del cuerpo de la acción.
{
"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"
}
}
}
]
}
Seleccione el REPLACE marcador de posición y, a continuación, seleccione Expresión en el panel de contenido dinámico. Agregue la fórmula siguiente a expression.
body('Batch_POST-groups').responses[0].body.id
Esta fórmula especifica que queremos usar el identificador de grupo del resultado de la primera acción.
Elija Guardar y luego Probar para ejecutar el flujo.
Sugerencia
Si recibe un error como The template validation failed: 'The action(s) 'Batch_POST-groups' referenced by 'inputs' in action 'Batch_2' are not defined in the template', la expresión es incorrecta y probablemente hace referencia a una acción de flujo que no encuentra. Asegúrese de que el nombre de la acción al que hace referencia coincide exactamente.
Elija el botón de radio I'll perform the trigger action (Realizaré la acción del desencadenador ) y elija Save & Test (Guardar & prueba). Elija Continuar en el cuadro de diálogo. Proporcione un nombre sin espacios y elija Ejecutar flujo para crear un equipo.
Por último, elija Listo para ver el registro de actividad. Una vez completado el flujo, se han configurado el grupo y el equipo de Office 365. Seleccione los elementos de acción batch para ver los resultados de las llamadas de Batch JSON. de outputs la Batch PUT-team acción debe tener un código de estado de 201 para una asociación de equipo correcta similar a la imagen siguiente.
Extensión del flujo
El flujo que creó en el ejercicio anterior usa la $batch API para realizar dos solicitudes individuales a Microsoft Graph. Llamar al $batch punto de conexión de esta manera proporciona cierta ventaja y flexibilidad, pero la verdadera eficacia del punto de $batch conexión se produce al ejecutar varias solicitudes a Microsoft Graph en una sola $batch llamada. En este ejercicio, ampliará el ejemplo de creación de un grupo unificado y asociación de un equipo para incluir la creación de varios canales predeterminados para el equipo en una sola $batch solicitud.
Abra Microsoft Power Automate en el explorador e inicie sesión con su cuenta de administrador de inquilinos de Microsoft 365. Seleccione el flujo que creó en el paso anterior y elija Editar.
Elija Nuevo paso y escriba Batch en el cuadro de búsqueda. Agregue la acción Conector de MS Graph Batch . Elija los puntos suspensivos y cambie el nombre de esta acción a Batch POST-channels.
Agregue el código siguiente al cuadro de texto del cuerpo de la acción.
{
"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 las tres solicitudes anteriores usan la propiedad dependsOn para especificar un orden de secuencia y cada una ejecutará una solicitud POST para crear un nuevo canal en el nuevo equipo.
Seleccione cada instancia del REPLACE marcador de posición y, a continuación, seleccione Expresión en el panel de contenido dinámico. Agregue la fórmula siguiente a expression.
body('Batch_PUT-team').responses[0].body.id
Elija Guardar y luego Probar para ejecutar el flujo. Seleccione el botón de radio Realizaré la acción del desencadenador y, a continuación, elija Guardar & prueba. Escriba un nombre de grupo único en el campo Nombre sin espacios y elija Ejecutar flujo para ejecutar el flujo.
Una vez que se inicie flow, elija el botón Listo para ver el registro de actividad. Cuando el flujo se completa, la salida final de la Batch POST-channels acción tiene una respuesta de estado HTTP 201 para cada canal creado.
Vaya a Microsoft Teams e inicie sesión con su cuenta de administrador de inquilinos de Microsoft 365. Compruebe que el equipo que acaba de crear aparezca e incluya los tres canales creados por la $batch solicitud.
Aunque la acción anterior Batch POST-channels se implementó en este tutorial como una acción independiente, las llamadas para crear los canales podrían haberse agregado como llamadas adicionales en la Batch PUT-team acción. Esto habría creado el equipo y todos los canales en una sola llamada por lotes. Pruébelo por su cuenta.
Por último, recuerde que las llamadas por lotes JSON devolverán un código de estado HTTP para cada solicitud. En un proceso de producción, es posible que desee combinar el procesamiento posterior de los resultados con una Apply to each acción y validar que cada respuesta individual tenga un código de estado 201 o compensar cualquier otro código de estado recibido.
¡Enhorabuena!
Ha completado el tutorial de Microsoft Graph de Power Automate. Ahora que tiene un conector personalizado que funciona que llama a Microsoft Graph, puede experimentar y agregar nuevas características. Visite información general de Microsoft Graph para ver todos los datos a los que puede acceder con Microsoft Graph.
Comentarios
Proporcione comentarios sobre este tutorial en el repositorio de GitHub.
¿Tiene algún problema con esta sección? Si es así, envíenos sus comentarios para que podamos mejorarla.