Explorar las opciones de configuración de los conectores personalizados
En esta unidad se continúan explicando los conceptos básicos de los conectores personalizados, y se analizan en profundidad algunas opciones de configuración disponibles.
Nombres de conectores e información general
Una de las primeras decisiones que tendrá que tomar es la del nombre del conector. El nombre debe ser único y aclarar qué es el conector para el consumidor. Tiene un límite de 30 caracteres, pero puede dar más detalles en el campo Descripción. El campo Color de fondo del icono también puede ayudar a identificar visualmente el conector. Estos campos son importantes, porque muestran cuándo el usuario está seleccionando el conector que debe usar, y las señales visuales ayudan al usuario a trabajar de manera más eficiente. Si planea enviar su conector para certificación, asegúrese de revisar los requisitos más estrictos en las Instrucciones sobre cómo enviar su conector a Microsoft.
Nombres de acciones y desencadenadores
Una vez que un usuario se ha limitado a su conector, seleccionará una acción o desencadenador para usar desde el conector. Los campos Id. de operación, Resumen y Descripción ayudan a describir cada acción y desencadenador. El id. de operación se usa internamente, debe ser único y no puede contener espacios. La combinación de letras mayúsculas y minúsculas (grafía Camel), como en GetInvoice, ayudará a simplificar la capacidad de leer la identificación al buscar el marcado de la definición. La falta de espacios en los nombres puede ser difícil para los creadores que usan lectores de pantalla, pero usar esta grafía ayuda a que las definiciones sean más accesibles para ellos.
El campo Resumen es importante porque aparece en la lista de acciones y se desencadena cuando se selecciona el que desea utilizar. Le recomendamos que sea lo suficientemente descriptivo para que pueda saber qué hace la acción o el desencadenador. Por ejemplo, la descripción de la acción GetInvoice podría ser Obtener una factura específica por id.. Con frecuencia, los creadores encontrarán la acción mediante una búsqueda, por lo que tener nombres descriptivos puede ayudarles a encontrar la acción correcta rápidamente.
La siguiente imagen muestra dónde se utilizan los elementos de resumen y descripción cuando selecciona una acción o desencadenador.
Una vez que haya seleccionado una acción o desencadenador, podrá ver elementos de resumen y descripción en cada tarjeta de acción en el diseñador.
Observe que, en las imágenes anteriores, los patrones de nomenclatura son incoherentes, ya que algunos nombres tienen espacios en el resumen y otros no. Puede corregir ese error actualizando los campos en el portal o, si es propietario de la API, puede pedirle al desarrollador que actualice lo que proporciona en la definición de OpenAPI que importa. Tenga en cuenta que, si realiza cambios manualmente en el portal y luego vuelve a importar la definición de OpenAPI, sobrescribirá sus cambios.
Visibilidad de la acción
Puede configurar la opción Visibilidad de una acción para influir en cómo se mostrará la acción en la experiencia del creador.
Ninguna: esta opción es la predeterminada. La acción se mostrará normalmente.
Avanzada: la acción estará disponible pero no priorizada.
Interna: la acción quedará oculta.
Importante: la acción tendrá prioridad y se mostrará primero.
Por ejemplo, si importa una definición de Open API con 10 acciones y no desea que los usuarios vean/utilicen dos de ellas inicialmente, puede seleccionar la opción interna para ocultarlas. Este enfoque es una forma útil de gestionar las operaciones que se utilizan para admitir metadatos de conectores dinámicos. También puede permitirle ocultar las acciones inicialmente y luego hacerlas visibles más tarde cuando los usuarios las soliciten. Ocultar las acciones mantendría la lista visible para los usuarios lo más mínima posible.
Las acciones que se seleccionan como importantes se muestran primero. El usuario debe seleccionar el conector para mostrar las seleccionadas como ninguna o avanzada. Este enfoque se utiliza mejor cuando tiene numerosas acciones y muchas no se utilizan con frecuencia.
Solicitud
La solicitud define qué parámetros/datos se pasarán a la operación cuando la acción invoque la operación en la API. Cuando importa una definición de OpenAPI, configurará la consulta de solicitud, los encabezados y el cuerpo. También puede importar manualmente desde el ejemplo.
La siguiente imagen muestra un ejemplo de cómo se ve la pantalla cuando se mira la definición.
Esta configuración es importante porque se traduce en lo que ve el usuario cuando usa la acción.
Al editar cada uno de los parámetros o al hacer que el desarrollador de la API proporcione más detalles, puede mejorar la experiencia del usuario cuando utiliza la acción. Al seleccionar los puntos suspensivos (...) en cada parámetro, se mostrará la siguiente pantalla de edición.
Los campos y opciones que debe revisar y cambiar son los siguientes:
Nombre: no lo cambie; este campo debe coincidir con lo que espera la API.
Resumen: haga que este campo sea fácil de usar; por ejemplo, fechaFinal sería Fecha hasta.
Descripción: este campo contiene una oración que describe el parámetro. Se utilizará como texto de marcador de posición para el campo.
Valor predeterminado: este campo es un valor predeterminado opcional, pero debe proporcionarse si configura la visibilidad como interna y hace que el parámetro sea obligatorio.
Es obligatorio: asegúrese de configurar esta opción si la API requiere un valor. Esta opción habilita un asterisco rojo visual al lado del campo.
Visibilidad: este parámetro funciona como la opción de visibilidad en la acción descrita anteriormente. Si tiene parámetros que no se utilizan con frecuencia, seleccione la opción avanzada.
Tipo y formato: asegúrese de que estos campos sean apropiados, porque el parámetro que importa desde ejemplos asume que no siempre son correctos.
Tipo de lista desplegable: utilice este parámetro para configurar una lista de valores estática o dinámica para ayudar a que la selección del usuario sea más fácil y predecible.
En la siguiente imagen se muestra un ejemplo de cómo se vería la pantalla después de corregir el parámetro Fecha desde.
Respuesta
La respuesta define lo que espera recibir de la API. A diferencia de la solicitud, que solo tiene una definición, puede tener diferentes respuestas según el estado de HTTP. Por ejemplo, si su llamada a la API genera un error, el cuerpo contendrá los detalles del error en lugar de lo que devuelva su API. También puede tener una respuesta predeterminada, que es una respuesta general si no hay una disponible para un estado HTTP específico.
Al seleccionar una de las respuestas, se revelarán los detalles y, de manera similar al proceso de una solicitud, se pueden editar estos elementos para facilitar su consumo.
Los elementos de la respuesta corresponden a lo que se muestra en el panel Contenido dinámico.
Al igual que en la solicitud, asegúrese de haber incluido nombres y descripciones adecuados, ya que pueden ayudar a facilitar el uso de los valores.
Validación
Observe que aparece una sección de validación similar a la siguiente imagen en la parte inferior de la pantalla.
Asegúrese de que esta pantalla no muestre errores y luego tómese tiempo para resolver los problemas que se presentan.
Otras configuraciones
Hay otras opciones de configuración que no se han abarcado en profundidad en este módulo, como los desencadenadores, las referencias y las directivas.
Los desencadenadores se pueden configurar si la API admite eventos de sondeo o webhook. Cuando se definen, los desencadenadores permiten usar un conector como desencadenador para un flujo de Power Automate.
Las referencias definen parámetros reutilizables y normalmente se crean cuando se importa la definición y se define un parámetro reutilizable. Las referencias también se pueden hacer manualmente, utilizando el editor de Swagger incorporado.
Las directivas se pueden utilizar para cambiar el comportamiento de las acciones y los desencadenadores. Las directivas se crean utilizando una de las plantillas de directivas predefinidas.
Estos temas avanzados se tratan en detalle más adelante en esta ruta de aprendizaje.
