Compartir a través de

Crear un conector personalizado desde cero

Nota

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, y el uso de conectores Copilot en Microsoft Copilot Studio. Asegúrese de leer la descripción general del conector personalizado para entender el proceso.

Vaya a Usar conectores de Power Platform en Copilot Studio para obtener información sobre cómo puede llamar a los conectores como acciones de conector en su agente de Microsoft Copilot.

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 operación de opinión de API 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 izquierdo, seleccione Soluciones.

  3. Edite o cree una solución no administrada que incluirá su conector personalizado. Aprenda cómo crear soluciones

  4. Seleccione el menú desplegable Nuevo y Automatización>Conector personalizado.

    Se abre el asistente para nuevos conectores

  5. Escriba el Nombre del conector, como SentimentDemo.

    Complete el resto de los pasos siguiendo las siguientes instrucciones.

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

    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. En la página Definición, el panel izquierdo muestra las acciones, los desencadenadores (para Logic Apps Power Automate y Copilot Studio), y las referencias definidas para el conector.

Nota

No hay desencadenadores en este conector. Puede aprender sobre desencadenadores para conectores personalizados en Usar webhooks como desencadenante de Azure Logic Apps y Power Automate.

  1. Seleccione Nueva acción.

  2. En el área General, añada 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. En el área Solicitud seleccione Importar desde muestra.

  4. Especifique la información necesaria para conectarse a la API, especifique el cuerpo de la solicitud (proporcionado después de la tabla) y, a continuación, 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 Utilice el ejemplo JSON.

    Ejemplo:

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

  5. En el área de Respuesta, seleccione Agregar respuesta predeterminada.

  6. Especifique el cuerpo de la respuesta y, luego, seleccione Importar. Al igual que la solicitud, le proporcionamos esta información, pero generalmente se encuentra en la documentación de la API.

    Ejemplo:

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

    En el área Validación se muestran los problemas detectados en la definición de la API.

  7. Solucione cualquier problema. Debería ver una marca de verificación verde cuando la validación de la definición se realice correctamente.

  8. 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 use en una aplicación lógica, Power Automate, Power Apps o Copilot Studio.

  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ámetro, elija idioma>Editar y repita el proceso que ha usado anteriormente para id para agregar los valores de language siguientes.

    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ámetro, elija Texto>Editar y repita el proceso que ha usado anteriormente para id y language para agregar los valores de text siguientes.

    Parámetro valor
    Nombre Text
    Description El texto para analizar las opiniones
    Default value None
    Es obligatorio Sí

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

  7. En la esquina superior derecah del asistente, seleccione Actualizar conector.

Paso 4: (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, tiene 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 5: 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 5: 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 izquierdo, seleccione 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.

    El conector llama a la API.

  5. Revise 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 su comportamiento, puede usar el conector de:

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 funciones. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.