Crear un conector personalizado desde cero

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, crea un conector personalizado desde cero, sin usar una colección Postman o una definición OpenAPI para describir la API Text Analytics Sentiment de Cognitive Services (nuestro ejemplo para esta serie). En su lugar, describe el conector completamente en el asistente para conector personalizado.

Para conocer otras formas de describir una API, consulte los siguientes temas:

• Creación de un conector personalizado desde una definición de OpenAPI
• Creación de un conector personalizado a partir de una colección de Postman

Requisitos previos

• Una clave de API para la API de Text Analytics de Cognitive Services
• Una de las siguientes suscripciones:
  • Power Automate
  • Power Apps

Inicie el asistente para conector personalizado

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

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

   

3. Seleccione Nuevo conector personalizado y, a continuación, elija 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.

1. En la página General:

   • Escriba un valor significativo para Descripción. Esta descripción se muestra en los detalles del conector personalizado, y puede ayudar a otros usuarios a saber si el conector podría serles útil.

   • Actualice 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
   Descripción	"Usa la API Text Analytics Sentiment de Cognitive Services para determinar si el texto es positivo o negativo".
   Host	"westus.api.cognitive.microsoft.com"

   Nota

   Para obtener más información sobre la opción Conectar mediante la puerta de enlace de datos local, vea Conectar a las API locales utilizando la puerta de enlace de datos.

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 página Seguridad, en Tipo de autenticación, elija 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. Elija 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 el nombre se establece en "SentimentDemo" y, después, 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 API Text Analytics Sentiment.

1. En la página Definición, el área izquierda muestra las acciones, los desencadenadores (para Logic Apps y Power Automate) y las referencias definidas para el conector. Elija Nueva acción.

   

   No hay desencadenadores en este conector. Puede aprender sobre desencadenadores para conectores personalizados en 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 popiedad 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. elija Importar desde ejemplo.

   

4. Especifique la información necesaria para conectarse a la API y el cuerpo de la solicitud, luego seleccione Importar. Proporcionamos esta información para usted (debajo de la imagen). Para una API pública, normalmente la obtiene de la documentación, como API Text Analytics Sentiment.

   

   Parámetro	valor
   Verbo	"POST"
   URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Cuerpo	Consulte a continuación

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

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

   

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

   

   {
    "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. Verifique el estado. Luego, en la parte superior derecha del asistente, elija 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, elija body y, después, Editar.

   

2. En el área Parámetro, ahora verá los tres parámetros que espera la API: id, language y text. Elija id y, después, Editar.

   

3. En el área Propiedad de esquema, actualice los valores del parámetro y, a continuación, elija Volver.

   

4. En el área Parámetro, elija language, después Editar y repita el proceso que ha usado anteriormente para id con los valores siguientes.

   Parámetro	valor
   Título	"Language"
   Descripción	"El código de idioma de dos o cuatro caracteres para el texto"
   Valor predeterminado	"en"
   Es obligatorio	"Sí"

5. En el área Parámetro, elija text, después Editar y repita el proceso que ha usado anteriormente para id y language, con los valores siguientes.

   Parámetro	valor
   Título	"Texto"
   Descripción	"El texto para analizar las opiniones"
   Valor predeterminado	Nada
   Es obligatorio	"Sí"

6. En el área Parámetro, elija Volver para volver a la página de definición principal.

7. En la parte superior derecha del asistente, elija 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, tendrá prioridad sobre la definición sin código. Esto significa que el código se ejecutará y no enviaremos la solicitud al backend.

Puede pegar su código o cargar un archivo con su código. Su código debe cumplir los siguientes requisitos:

• Estar escrito en C#.
• Tener un tiempo de ejecución máximo de 5 segundos.
• No puede tener más de 1 MB (tamaño del archivo de código).

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 página Código, inserte su código personalizado usando una de las siguientes opciones:

   • Copiar y pegar, o
   • 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.

2. Una vez que pegue o cargue 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 la lista desplegable. Si no se selecciona ninguna operación, se aplica a todas las operaciones.

   

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.

1. En la página Prueba, elija Nueva conexión.

   

2. Escriba la clave de API de Text Analytics API y, después, elija Crear conexión.

   

3. Vuelva a la página de prueba:

   • En Power Automate, le dirigirá de nuevo a la página Prueba. Elija el icono de actualización para asegurarse de que se actualiza la información de la conexión.

   

   • En Power Apps, accede a la lista de conexiones disponibles en el entorno actual. En el panel de navegación, elija Datos > Conectores personalizados. Elija el conector que ha creado y vuelva a la página Prueba.

     

4. En la página Prueba, escriba un valor para el campo text (los demás campos utilizan los valores predeterminados que estableció anteriormente) y, a continuación, elija Probar operación.

   

5. 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 de origen 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:

• Un flujo
• Una aplicación
• Una aplicación lógica

También puede compartir un conector dentro de su organización y certificar el conector para que los usuarios ajenos a su organización puedan utilizarlo:

• Compartir el conector
• Certificación del conector