Usar directivas de conversión de datos
Las plantillas de directivas se pueden utilizar para convertir datos de una estructura a otra. Este proceso se realiza comúnmente para simplificar la tarea del fabricante de usar un conector personalizado para proporcionar datos para las acciones o trabajar con los datos de respuesta de los resultados de la acción. Por ejemplo, la API puede proporcionar una lista separada por comas de los usuarios que tienen acceso al registro. Convertir esa lista en una matriz facilitaría el uso de la lista en una aplicación o flujo. Actualmente, las siguientes plantillas de directivas admiten la conversión de estructuras de datos:
Conversión de una matriz en un objeto
Conversión de un objeto en una matriz
Conversión de una cadena delimitada en una matriz de objetos
Cada directiva se puede ejecutar para la solicitud (datos de entrada) o la respuesta (datos de salida) de una o más acciones. Cuando ejecuta una directiva en la solicitud, está dando forma a los datos que proporciona el fabricante para determinar cómo quiere verlos la API. Por ejemplo, el conector de Microsoft Planner usa la matriz Convert para un objeto en su acción Actualizar detalles de la tarea. Esta acción permite al usuario proporcionar una serie de vínculos de referencia externos y luego asociarlos con la tarea. Al permitir que el fabricante los especifique como una matriz, a los usuarios se les presenta una interfaz fácil de usar que les permite agregar múltiples vínculos seleccionando Agregar nuevo elemento.
Si usa la característica de inspección en el paso de acción, puede ver cómo se estructuran los datos y se presentarán a la API si las plantillas de directiva del conector no realizaron ninguna transformación.
Si consulta la documentación de la API de Microsoft Planner para esta operación, verá que quiere los datos estructurados como en el siguiente ejemplo.
Para convertir lo que proporcionó la acción de flujo en lo que espera la API, el conector se configura en varias plantillas de directiva para transformar los datos. Las plantillas de directiva se utilizan de la siguiente manera:
Establecer propiedad: para configurar el campo previewPriority como "!"
Establecer propiedad: para configurar la expresión @odata.type
Convertir matriz en objeto: para remodelar la matriz e incluir el tipo y el alias como propiedades
La directiva Convertir matriz en objeto se parecería al siguiente ejemplo.
Las plantillas de directiva que se ejecutan en la respuesta le permiten remodelar la salida de la API. Por ejemplo, la respuesta de Facturación de Contoso de la acción Obtener factura incluye una lista de etiquetas separadas por punto y coma como parte del objeto de factura. Los datos que se devuelven de la API se parecen a los de la siguiente captura de pantalla.
Para las aplicaciones y los flujos, es más difícil trabajar con una cadena con varios valores que con una matriz. Para mejorar la usabilidad, puede utilizar la plantilla de directiva Convertir cadena delimitada en la respuesta. En el siguiente ejemplo se muestra la plantilla de directiva que configuraría.
Esta acción tendría como resultado la adición de una nueva matriz llamada taglist a la respuesta, como se muestra en la siguiente imagen.
Ahora que ha explorado algunos ejemplos de plantillas de directiva en uso, puede revisar algunos detalles clave de configuración. El parámetro Ejecutar directiva en decide si la directiva se aplica a la solicitud o a la respuesta. Si necesita ambas, deberá configurar dos plantillas de directiva.
Cada plantilla de directiva de conversión tiene un objeto de destino o un parámetro de colección. Este factor proporciona el punto de partida de dónde la lógica de la directiva obtendrá los datos para transformar. El punto de partida más común es utilizar la expresión @body(), que apunta al cuerpo de la solicitud o respuesta. En el siguiente ejemplo, la expresión @body() es un objeto y tiene una propiedad llamada tags.
Alternativamente, si la respuesta fuese un objeto con una propiedad llamada invoices que es una matriz de objetos de factura, cada uno con la propiedad tags, la configuración sería similar a la de la siguiente imagen.
Mientras configura las directivas, asegúrese de aplicarlas solo a las acciones con datos de solicitud/respuesta que coincidan con estas configuraciones. Por ejemplo, la acción Obtener factura, que devuelve un único objeto de factura, necesitaría aplicar plantillas de directiva diferentes a las de la acción Mostrar factura, que devuelve una matriz de objetos de factura. Si está agregando plantillas de directiva a un conector existente con todas las acciones habilitadas, asegúrese de probar todas las acciones y desencadenadores para asegurarse de que funcionen con la nueva directiva.
Una vez que haya configurado las plantillas de directivas de respuesta, asegúrese de volver a importar los datos de ejemplo en la respuesta a la acción. Este paso es necesario para que las aplicaciones y los flujos puedan tener visibilidad de los datos transformados.
Si la configuración de una plantilla de directiva crea un error, normalmente lo verá en el comprobador como estado HTTP 500 o no podrá realizar ningún procesamiento. Si bien no es posible deshabilitar una directiva, puede eliminar una acción de la lista de operaciones para permitir que las pruebas identifiquen si la directiva está causando problemas. La siguiente imagen muestra solo dos operaciones seleccionadas.
Las plantillas de directiva de conversión ofrecen un enfoque centrado en la configuración para transformar los datos hacia y desde la API subyacente. Se pueden utilizar para facilitar el uso de las acciones del conector.