Crear un conector personalizado desde cero

Para crear un conector personalizado, debe definir la API a la que desea conectarse para que el conector comprenda las operaciones y las estructuras de datos de la API. En este artículo, creará un conector personalizado desde cero, sin usar un formato de definición de OpenAPI para describir la operación de análisis de sentimiento de la API de Text Analytics de Azure Cognitive Services (nuestro ejemplo para esta serie). En su lugar, se define el conector completamente en el Asistente para conectores personalizados.

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

Requisitos previos

• Una clave de la API para la API de Análisis de Texto de Cognitive Services

  Nota

  La API de Azure Cognitive Services Text Analytics se usa como LA API de ejemplo de esta serie de tutoriales. Si tiene problemas para obtener la clave de API, puede seguir los pasos descritos en este artículo mediante cualquier API REST a la que tenga acceso. El asistente para conectores personalizados acepta cualquier clave de API válida que espera la API de destino.

• 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 izquierdo, seleccione Soluciones.

3. Edite o cree una solución no administrada para el conector personalizado. Aprenda a crear una solución.

4. Seleccione la lista desplegable Nuevo conector personalizado y seleccione Crear en blanco.

5. Escriba el nombre del conector, como SentimentDemo. Seleccione Continuar para abrir el asistente para conectores, donde complete estas cinco secciones en Power Automate:

   • General

   • Security

   • Definición

   • Código (opcional)

   • Test

     

Paso 1: Actualizar los detalles generales

En la sección General se proporciona información del conector, como el icono, la descripción, el esquema, el host y la dirección URL base. Realice estos pasos:

1. Seleccione Cargar icono del conector o Cargar en el cuadro de icono para cargar un PNG o JPG del icono del conector. Asegúrese de que es inferior a 1 MB. También puede designar un color de fondo para el icono.

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

3. Seleccione el esquema URL del conector, HTTPS o HTTP.

4. 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
   Descripción	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

5. Actualice la dirección URL base, el punto de partida de todas las llamadas API a un servicio específico.

6. Seleccione Seguridad en la parte inferior para ir a la sección siguiente.

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 autenticación mediante clave de API, por lo que eso es lo que debe especificar para este tutorial.

1. En la sección Seguridad , en Tipo de autenticación, seleccione Clave de API en la lista desplegable.

2. En Clave de API, especifique una etiqueta de parámetro, un nombre y una ubicación. Especifique una etiqueta significativa, ya que se muestra cuando alguien realiza por primera vez una conexión 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 el nombre esté configurado en SentimentDemo, y luego seleccione Crear conector.

4. Seleccione Definición en la parte inferior para ir a la sección siguiente.

Paso 3: Crear la definición del conector

El asistente para conectores personalizado proporciona muchas opciones para describir cómo funciona el conector y cómo se expone en aplicaciones lógicas, flujos, aplicaciones y agentes. Puede definir acciones, desencadenadores, referencias y directivas. Explicamos la interfaz de usuario y repasamos algunas opciones en esta sección, pero también te animamos a explorar por tu cuenta.

Crear acciones

Lo primero que debe hacer es crear una acción que llame a la operación de análisis de opiniones de la API Text Analytics. En la pestaña Definición , el panel izquierdo muestra las acciones, desencadenadores (para Logic Apps, Power Automate y Copilot Studio), referencias y directivas definidas para el conector.

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:

   • ninguno: se muestra normalmente en la aplicación lógica o el flujo
   • avanzado: oculto bajo otro menú
   • interno: Oculto para el 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.

   Normalmente, esta información se obtiene de la documentación de api de una API pública.

   Parámetro	valor
   Verbo	PUBLICAR
   Dirección URL	https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
   Cuerpo	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. Como hicimos con el cuerpo de la solicitud, le proporcionamos esta información, pero normalmente se proporciona 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

Cambiemos algunas cosas para que el conector sea más fácil de usar al usarlo alguien en Logic Apps, 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
   Título	ID
   Descripción	Un identificador para cada documento que se envía
   Valor predeterminado	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
   Título	Lenguaje
   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 Texto>Editar y repita el proceso que ha usado anteriormente para id y language para agregar los valores de text siguientes.

   Parámetro	valor
   Título	Text
   Descripción	El texto para analizar las opiniones
   Valor predeterminado	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 derecha del asistente, seleccione Actualizar conector.

8. Seleccione Código en la parte inferior para ir a la sección siguiente.

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.

Puede pegar su código o cargar un archivo con su código. Tu código debe:

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

   

   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 del interruptor cambia a Código activado.

   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.

   

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

     

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

   

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.

• Vuelva a comprobar siempre que el entorno y el identificador del conector sean correctos.

Solucionar problemas comunes

• Las acciones del conector personalizado no se cargan: después de crear o actualizar un conector, espere unos minutos para que la plataforma propague los cambios antes de las pruebas. Borre la memoria caché del explorador o pruebe una sesión de exploración privada si las acciones aún no aparecen.

• 401 Errores no autorizados: compruebe que la clave de API o las credenciales de OAuth son correctas y no han expirado. En el caso de los conectores de OAuth, confirme que el URI de redirección del proveedor de identidades coincide con el URI de redirección por conector que se muestra en la pestaña Seguridad .

• 403 Errores prohibidos: compruebe que el punto de conexión de API permite conexiones desde intervalos IP de Power Platform. En el caso de Azure Functions detrás de una red virtual, revise las direcciones IP de salida de los conectores administrados y asegúrese de que las reglas de red permitan el tráfico procedente de esos rangos de direcciones IP.

• Conector no visible después del uso compartido: puede tardar unos minutos en aparecer un conector compartido para otros usuarios. Si agregó el conector a una solución, los usuarios necesitan acceder a esa solución para ver el conector.

Pasos siguientes

Ahora que ha creado un conector personalizado y ha definido su comportamiento, puede usar el conector de:

• Power Automate
• Power Apps
• Aplicaciones lógicas
• Copilot Studio

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.

• Compartir el conector
• Certificación del conector

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.