Este artículo forma parte de una serie de tutoriales sobre la creación y el uso de conectores personalizados en Azure Logic Apps, Microsoft Power Automate y Microsoft Power Apps.
Para crear un conector personalizado debe describir la API a la que desea conectarse, de forma que el conector conozca las operaciones y las estructuras de datos de la API. En este tema, creará un conector personalizado desde cero, sin usar una definición de OpenAPI para describir la API de operación de sentimiento de análisis de textos de Azure Cognitive Services (nuestro ejemplo para esta serie). En su lugar, describe el conector completamente en el asistente para conector personalizado.
Actualmente puede crear un conector personalizado desde cero en Power Automate y Power Apps. Para Logic Apps, debe comenzar con al menos una definición de OpenAPI básica.
Requisitos previos
Una clave de API para la API de Texto Analytics de Cognitive Services
En el panel de navegación izquierdo, seleccione Datos > Conectores personalizados.
Seleccione Nuevo conector personalizado > Crear desde cero.
Escriba un nombre para el conector personalizado y, luego, seleccione Conectar.
Parámetro
valor
Título de conector personalizado
SentimentDemo
Paso 1: Actualizar los detalles generales
A partir de este punto, le mostraremos la interfaz de usuario de Power Automate, aunque los pasos son en gran medida los mismos entre tecnologías. Señalaremos cualquier diferencia.
En la pestaña General, puede realizar las siguientes acciones:
En el campo Descripción, introduzca un valor significativo. Esta descripción aparecerá en los detalles del conector personalizado y puede ayudar a otros usuarios a decidir si el conector podría serles útil.
Actualice el campo Host con la dirección de la API Text Analytics. El conector usa el host de la API y la dirección URL base para determinar cómo llamar a la API.
Parámetro
valor
Description
Usa la API Text Analytics Sentiment de Cognitive Services para determinar si el texto es positivo o negativo
Anfitrión
westus.api.cognitive.microsoft.com
Paso 2: Especificar el tipo de autenticación
Hay varias opciones disponibles para la autenticación en los conectores personalizados. Las API de Cognitive Services utilizan la autenticación de clave de API, así que eso es lo que especifica para este tutorial.
En la pestaña Seguridad, en Tipo de autenticación, seleccione Clave de API.
En Clave de API, especifique una etiqueta, el nombre y la ubicación del parámetro. Especifique una etiqueta descriptiva, ya que se mostrará cuando alguien realice una conexión por primera vez con el conector personalizado. El nombre y la ubicación del parámetro deben coincidir con lo que la API espera. Seleccione Conectar.
Parámetro
valor
Etiqueta de parámetro
Clave de API
Nombre de parámetro
Ocp-Apim-Subscription-Key
Ubicación del parámetro
Encabezado
En la parte superior del asistente, asegúrese de que se establezca el nombre SentimentDemo y, a continuación, seleccione Crear conector.
Paso 3: Crear la definición del conector
El asistente del conector personalizado proporciona muchas opciones para definir cómo funciona el conector y cómo se expone en aplicaciones lógicas, flujos y aplicaciones. Explicaremos la IU y cubriremos algunas opciones en esta sección, pero también le animamos a explorar por su cuenta.
Crear acciones
Lo primero que debe hacer es crear una acción que llame a la operación de opinión API Text Analytics.
En la página Definición, el panel izquierdo muestra las acciones, los desencadenadores (para Logic Apps y Power Automate) y las referencias definidas para el conector. Seleccione Nueva acción.
El área General muestra información acerca de la acción o el desencadenador seleccionado actualmente. Agregue un resumen, una descripción y un id. de operación para esta acción.
Parámetro
valor
Resumen
Devuelve una puntuación numérica que representa la opinión detectada
Descripción
La API devuelve una puntuación numérica comprendida entre 0 y 1. Las puntuaciones cercanas a 1 indican una opinión positiva, mientras que las puntuaciones cercanas a 0 indican una opinión negativa.
Id. de operación
DetectSentiment
Deja la propiedad Visibilidad establecida en ninguna. Esta propiedad para operaciones y parámetros en una aplicación lógica o flujo tiene las siguientes opciones:
Ninguna: normalmente se muestra en la aplicación lógica o el flujo
avanzado: oculto bajo otro menú
interna: oculta al usuario
Importante: se muestra siempre primero al usuario
El área Solicitud muestra información basada en la solicitud HTTP de la acción. Seleccione Importar desde ejemplo.
Especifique la información necesaria para conectarse a la API, especifique el cuerpo de la solicitud (se proporciona tras la siguiente imagen) y luego seleccione Importar. Esta información se la proporcionanos nostros, pero en una API pública, normalmente se obtendría de documentación como API de Text Analytics (v2.0).
El área Respuesta muestra información basada en la respuesta HTTP de la acción. Seleccione Agregar respuesta predeterminada.
Especifique el cuerpo de la respuesta y, luego, seleccione Importar. Al igual que hicimos con el cuerpo de la solicitud, esta información se proporciona después de la imgne, pero generalmente se encuentra en la documentación de la API.
En el área Validación se muestran los problemas detectados en la definición de la API. Compruebe el estado y, luego, en la esquina superior derecha del asistente, seleccione Actualizar conector.
Actualizar la definición
Ahora cambiemos algunas cosas para que el conector sea más sencillo cuando alguien lo usa en una aplicación lógica, un flujo o una aplicación.
En el área Solicitud, seleccione cuerpo y, después, seleccione Editar.
En el área Parámetro, ahora verá los tres parámetros que espera la API: id, language y text. Seleccione idy, a continuación, Editar.
En el área Propiedad de esquema, actualice los valores del parámetro y, a continuación, seleccione Volver.
Parámetro
valor
Nombre
ID
Description
Un identificador para cada documento que se envía
Default value
1
Es obligatorio
Sí
En el área Parámetros, seleccione idioma > Editar y luego repita el proceso que usó para id en los pasos 2 y 3 de este procedimiento, con los siguientes valores.
Parámetro
valor
Nombre
Lenguaje
Description
El código de idioma de dos o cuatro caracteres para el texto
Default value
en
Es obligatorio
Sí
En el área Parámetros, seleccione texto > Editar y luego repita el proceso que usó para id en los pasos 2 y 3 de este procedimiento, con los siguientes valores.
Parámetro
Valor
Nombre
Texto
Descripción
El texto para analizar las opiniones
Valor predeterminado
Ninguno
Es obligatorio
Sí
En el área Parámetro, seleccione Volver para volver a la pestaña Definición principal.
En la esquina superior derecah del asistente, seleccione Actualizar conector.
Paso 4: (Opcional) Habilite su conector como complemento de IA
Utilice la pestaña Complemento AI (vista previa) para un conector solo si planea certificar su conector. Para que un conector se pueda utilizar como complemento de IA, el conector debe estar certificado.
Antes de habilitar su conector como complemento de IA, asegúrese de comprender el caso de uso de los escenarios de complementos de IA y de haber revisado otras consideraciones, como la compatibilidad, las mejores prácticas y las recomendaciones. Más información: Crear un complemento de IA de conector (vista previa)
En el panel de navegación izquierdo, seleccione Conectores personalizados.
Si no ve Conectores personalizados, seleccione Más > Descubrir todo > Conectores personalizados. La opción aparece en el panel de navegación izquierdo.
En la parte superior derecha, seleccione una opción del menú Nuevo conector vcustom.
Asegúrese de haber completado el Paso 1, Paso 2 y Paso 3 en este artículo.
Seleccione la pestaña Complemento de IA (versión preliminar).
En la sección Manifiesto del complemento, ingrese los detalles para habilitar este conector como un complemento de IA.
Manifiesto del complemento: correo electrónico de contacto
Dirección de correo electrónico del contacto para este complemento de IA.
Manifiesto del complemento: URL de información legal
Una ubicación de acceso público donde se publica la información legal relacionada con su complemento de IA.
Desplácese hacia abajo hasta la sección Detalles de acciones del complemento e ingrese los detalles de la acción para cada acción en el complemento AI de su conector.
Campo
Description
Detalles de la acción del complemento: resumen
Resumen sobre cada acción del complemento de IA que los usuarios pueden realizar.
Detalles de la acción del complemento: descripción
Descripción de cada acción que los usuarios pueden realizar con respecto a este paso de acción específico del complemento de IA.
Casilla de verificación: habilitar como operación del complemento copiloto
Cuando hay una marca de verificación en la casilla de verificación, la operación del complemento AI está habilitada.
Casilla de verificación: ¿Se requiere confirmación del usuario?
Cuando hay una marca de verificación en la casilla de verificación, se requiere la confirmación del usuario.
Sugerencia
Si necesita ayuda para definir sus acciones, active la opción editor Swagger.
Desplácese hacia abajo hasta la sección Parámetro e ingrese los detalles del parámetro para el complemento AI de su conector.
Campo
Description
Parámetro: nombre
Nombre del parámetro. Utilice nombres identificables como Identificador de cuenta en lugar de ID.
Parámetro: descripción
Descripción del parámetro. Utilice una explicación descriptiva como Fecha de nacimiento de un contacto en formato MM/DD/AAAA en lugar de b_fecha. Estos nombres y descripciones ayudan a los LLM (modelos de lenguajes grandes) a interactuar de manera efectiva con el complemento de IA.
Parámetro: Resumen
Información de resumen acerca del parámetro.
Parámetro: valor predeterminado
Valor predeterminado del parámetro.
En la sección Solicitud bajo las secciones Complemento AI (vista previa), seleccione el parámetro de entrada y luego ingrese un descripción.
Paso 5: (Opcional) utilizar soporte de código personalizado
El código personalizado transforma las cargas útiles de solicitudes y respuestas más allá del alcance de las plantillas de políticas existentes. Las transformaciones incluyen el envío de solicitudes externas para obtener datos adicionales. Cuando se usa código, tendrá prioridad sobre la definición sin código. Esto significa que el código se ejecutará y no enviaremos la solicitud al backend.
Nota
Este paso es opcional. Puede completar la experiencia sin código para crear su conector ignorando este paso y yendo al Paso 6: probar el conector.
La compatibilidad con código personalizado está disponible en versión preliminar pública.
Puede pegar su código o cargar un archivo con su código. Es preciso que el código:
Se escriba en C#.
Tenga un tiempo de ejecución máximo de cinco segundos.
En la pestaña Código, inserte su código personalizado usando una de las siguientes opciones:
Copiar y pegar
Seleccione el botón Cargar.
Si elige cargar su código personalizado, solo estarán disponibles los archivos con extensión .cs o .csx.
Importante
Actualmente, solo admitimos el resaltado de sintaxis en el editor de código. Asegúrese de probar su código localmente.
Después de pegar o cargar su código, seleccione el conmutador junto a Código deshabilitado para habilitar su código. El nombre de la palanca cambia a Código habilitado.
Puede habilitar o deshabilitar su código en cualquier momento. Si el conmutador está en Código deshabilitado, su código se eliminará.
Seleccione las acciones y los desencadenadores a aplicar a su código personalizado seleccionando una opción en el menú desplegable. Si no se selecciona ninguna operación, las acciones y los activadores se aplican a todas las operaciones.
Paso 6: Probar el conector
Ahora que ha creado el conector, puede probarlo para asegurarse de que funciona correctamente. Actualmente, las pruebas solo están disponibles en Power Automate y Power Apps.
Importante
Cuando utilice una clave API, le recomendamos que no pruebe el conector inmediatamente después de crearlo. Pueden pasar unos minutos hasta que el conector esté listo para conectarse a la API.
En la pestaña Prueba, seleccione Nueva conexión.
Escriba la clave de API de Text Analytics API y, después, seleccione Crear conexión.
Nota
Para las API que requieren autenticación de portador, agregue Portador y un espacio antes de la clave de API.
Vuelva a la pestaña Prueba y realice una de las siguientes acciones:
(En Power Automate) Se le lleva de vuelta a la pestaña Prueba. Seleccione el icono de actualización para asegurarse de que la información de conexión esté actualizada.
(En Power Apps) Accede a la lista de conexiones disponibles en el entorno actual. En el panel de navegación izquierdo, seleccione Datos > Conectores personalizados. Elija el conector que ha creado y vuelva a la pestaña Prueba.
En la pestaña Prueba, escriba un valor para el campo text (los demás campos utilizan los valores predeterminados que estableció anteriormente) y, a continuación, seleccione Probar operación.
El conector llama a la API y puede revisar la respuesta, que incluye la puntuación de opinión.
Prácticas recomendadas (para usuarios de CLI)
Descargue todos sus conectores y use Git o cualquier otro sistema de gestión de código fuente para guardar los archivos.
Si hay una actualización incorrecta, vuelva a implementar el conector, volviendo a ejecutar el comando de actualización con el conjunto de archivos correcto a partir del sistema de gestión de código de origen.
Pruebe el conector personalizado y el archivo de configuración en un entorno de pruebas antes de su implementación en el entorno de producción.
Compruebe siempre que los id. del entorno y del conector son correctos.
Pasos siguientes
Ahora que ha creado un conector personalizado y ha definido sus comportamientos, puede usar el conector desde:
También puede compartir un conector dentro de su organización o certificar el conector para que los usuarios ajenos a su organización puedan utilizarlo.
Agradecemos enormemente los comentarios sobre problemas con nuestra plataforma de conectores o nuevas ideas de características. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.