Crear un conector personalizado desde cero

  • Artículo

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.

Nota

Asegúrese de leer la descripción general del conector personalizado para entender el proceso.

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.

Para otra forma de describir una API, vaya a Crear un conector personalizado desde una definición de OpenAPI.

Nota

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

Inicie el asistente para conector personalizado

  1. Inicie sesión en Power Apps o Power Automate.

  2. En el panel de navegación izquierdo, seleccione Datos > Conectores personalizados.

  3. Seleccione Nuevo conector personalizado > Crear desde cero.

  4. 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:

  1. 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.

  2. 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.

  1. En la pestaña Seguridad, en Tipo de autenticación, seleccione Clave de API.

  2. 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

  3. 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.

  1. 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.

    No hay desencadenadores en este conector. Para aprender sobre desencadenadores para conectores personalizados, vaya a Usar webhooks con Azure Logic Apps y Power Automate.

  2. 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

  3. El área Solicitud muestra información basada en la solicitud HTTP de la acción. Seleccione Importar desde ejemplo.

  4. 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).

    Parámetro valor
    Verbo PUBLICAR
    Dirección URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body Use el código JSON siguiente:

    Ejemplo:

    {
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}

  5. El área Respuesta muestra información basada en la respuesta HTTP de la acción. Seleccione Agregar respuesta predeterminada.

  6. 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.

    Ejemplo:

    {
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}

  7. 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.

  1. En el área Solicitud, seleccione cuerpo y, después, seleccione Editar.

  2. 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.

  3. 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í

  4. 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í

  5. 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í

  6. En el área Parámetro, seleccione Volver para volver a la pestaña Definición principal.

  7. 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)

  1. 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.

  2. En la parte superior derecha, seleccione una opción del menú Nuevo conector vcustom.

  3. Asegúrese de haber completado el Paso 1, Paso 2 y Paso 3 en este artículo.

  4. Seleccione la pestaña Complemento de IA (versión preliminar).

  5. En la sección Manifiesto del complemento, ingrese los detalles para habilitar este conector como un complemento de IA.

    Captura de pantalla de los campos de la página 'Manifiesto del complemento'.

    Campo Description
    Manifiesto de complemento: nombre Nombre del complemento de IA.
    Manifiesto del complemento: descripción Descripción del complemento de IA. Más información: Crear un complemento de IA de conector (vista previa)
    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.

  6. 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.

    Captura de pantalla de los campos de la página 'Detalles de acción del complemento'.

    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.

  7. Desplácese hacia abajo hasta la sección Parámetro e ingrese los detalles del parámetro para el complemento AI de su conector.

    Captura de pantalla de los campos de la página 'Parámetros'.

    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.

  8. 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.
  • Tenga un tamaño de archivo no superior a 1 MB.

Para obtener instrucciones y ejemplos de código de escritura, vaya a Escribir código en conectores personalizados.

Para preguntas frecuentes sobre código personalizado, vaya a Preguntas frecuentes sobre códigos personalizados.

  1. 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.

    Captura de pantalla de Cargar su código personalizado

    Importante

    Actualmente, solo admitimos el resaltado de sintaxis en el editor de código. Asegúrese de probar su código localmente.

  2. 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á.

  3. 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.

    Captura de pantalla de Seleccionar desencadenadores y referencias

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.

  1. En la pestaña Prueba, seleccione Nueva conexión.

  2. 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.

  3. 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.

      Captura de pantalla de actualizar conexión.

    • (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.

  4. 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.

  5. El conector llama a la API y puede revisar la respuesta, que incluye la puntuación de opinión.

    Captura de pantalla de la respuesta del conector.

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.

Proporcionar comentarios

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.