Creación de un conector personalizado a partir de una colección de Postman

Nota

Este tema forma parte de una serie de tutoriales sobre la creación y el uso de conectores personalizados en Azure Logic Apps, Power Automate y Power Apps. 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 utilizando una colección Postman que describe la API Texto Analytics Sentiment de Cognitive Services (nuestro ejemplo para esta serie).

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

• Creación de un conector personalizado desde una definición de OpenAPI

• Creación de un conector personalizado desde cero

Requisitos previos

• Una colección Postman que describe la API de ejemplo:

  • Descargar la colección Postman que hemos creado
    o bien
  • Complete el tema Crear una colección de Postman para un conector personalizado Tenga en cuenta que, al crear un conector personalizado, la colección Postman no debe superar 1 MB.

• Una clave de API para la API de Text Analytics de Cognitive Services

• Una de las siguientes suscripciones:

  • Azure, si está utilizando Logic Apps
  • Power Automate
  • Power Apps

• Si usa Logic Apps, primero cree un conector personalizado de Azure Logic Apps

Importar la colección de Postman

Ahora está listo para trabajar con la colección de Postman que ha creado o descargado. La colección contiene mucha información de la necesaria. También puede revisar y actualizar esta información a medida que avance por el asistente del conector personalizado. Comience por importar la colección Postman para Logic Apps o para Power Automate y Power Apps.

Importar la colección Postman para Logic Apps

1. Vaya a Azure Portal y abra el conector de Logic Apps que creó anteriormente en Creación de un conector personalizado de Azure Logic Apps.

2. En el menú de su conector, elija Conector de Logic Apps y elija Editar.

   

3. Bajo General, elija Cargar colección Postman V1 y luego navegue a la colección Postman que creó.

   

   El asistente importa la colección y después la convierte en una definición de OpenAPI denominada generatedApiDefinition.swagger.json.

Nota

Este tutorial se centra en una API de REST, pero también puede usar una API SOAP con Logic Apps.

Importar la colección de Postman para Power Automate y Power Apps

1. Vaya a make.powerapps.com o flow.microsoft.com.

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

3. Elija Nuevo conector personalizado y, a continuación, Importar una colección de Postman.

4. Escriba un nombre para el conector personalizado, navegue a la colección de Postman que ha descargado o creado y seleccione Continuar.

   

   Parámetro	valor
   Título de conector personalizado	"SentimentDemo"

   El asistente importa la colección y después la convierte en una definición de OpenAPI denominada generatedApiDefinition.swagger.json.

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 en las tres tecnologías. Se resaltarán las diferencias.

1. En la página General, revise la información que se importó desde la colección de Postman, incluido el host y la dirección URL base de la API. El conector usa el host y la dirección URL base para determinar cómo llamar a la API.

   Nota

   Para obtener más información sobre cómo conectarse a las API locales, vea Conectar a las API locales utilizando la puerta de enlace de datos.

2. Actualice la descripción con algo descriptivo. Esta descripción se muestra en los detalles del conector personalizado, y puede ayudar a otros usuarios a la hora de averiguar cómo el conector podría resultarles de utilidad.

   Parámetro	valor
   Descripción	"Usa la API Text Analytics Sentiment de Cognitive Services para determinar si el texto es positivo o negativo".

Especifique el tipo de autenticación

Hay varias opciones disponibles para la autenticación en los conectores personalizados. Las Cognitive Services APIs usan la autenticación de clave de API.

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. Elija una etiqueta expresiva y significativa. Este texto se mostrará a los usuarios para ayudarles a establecer las conexiones mediante el conector personalizado. El nombre y la ubicación del parámetro deben coincidir con lo que espera la API (en este caso, el encabezado que ha especificado en Postman). 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.

Revisar y actualizar 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.

Revisar la interfaz de usuario y la definición

Antes de entrar en algunos pasos específicos en la página Definición, primero echaremos un vistazo a la interfaz de usuario.

1. En esta zona se muestran todas las acciones, los desencadenadores (para Logic Apps y Power Automate) y las referencias definidos para el conector. En este caso, se muestra la acción DetectSentiment de la colección Postman. No hay ningún desencadenador en este conector, pero puede obtener información acerca de los desencadenadores de 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. Esta información procede de la colección de Postman. Puede editar la información aquí, incluida la propiedad Visibility, para las operaciones y los parámetros de una aplicación lógica o de un flujo:

   • Importante: se muestra siempre primero al usuario
   • Ninguna: normalmente se muestra en la aplicación lógica o el flujo
   • Avanzada: inicialmente está oculta en un menú adicional
   • interna: no se muestra al usuario

3. En el área Solicitud se muestra la información basada en la solicitud HTTP que se incluye en la colección de Postman. En este caso, verá que el verbo HTTP es POST y la dirección URL es "/text/analytics/v2.0/sentiment" (la dirección URL completa de la API es <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Miraremos más de cerca el parámetro body en breve.

4. El área Respuesta muestra información basada en la respuesta HTTP que se incluye en la colección de Postman. En este caso, la única respuesta definida es para "200" (una respuesta correcta), pero puede definir respuestas adicionales.

5. En el área Validación se muestran los problemas detectados en la definición de la API. Asegúrese de comprobar esta área antes de guardar un 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 o Power Apps.

1. En el área General, actualice el resumen a "Devuelve una puntuación numérica que representa la opinión detectada".

2. En el área Solicitud, elija body y, después, Editar.

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

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

   

   Parámetro	valor
   Título	"Id."
   Descripción	"Un identificador para cada documento que se envía"
   Valor predeterminado	"1"
   Es obligatorio	"Sí"

5. En el área Parámetro, elija idioma y, después, Editar y repita el proceso que ha usado anteriormente 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í"

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

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

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

8. En la parte superior derecha del asistente, elija Actualizar conector.

Prueba del 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 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 la esquina superior derecha, elija el icono de engranaje y después 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.

   

Limitaciones

En Power Automate y Power Apps, si actualiza un conector personalizado existente mediante una colección de Postman, deberá volver a realizar las personalizaciones anteriores antes de guardar el conector. Por ejemplo, deberá volver a configurar el tipo de autenticación, los valores predeterminados de los parámetros para las acciones y otros.

Pasos siguientes

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

• Uso de un conector personalizado desde un flujo
• Usar un conector personalizado a partir de una aplicación
• Uso de un conector personalizado desde una aplicación lógica

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

• Compartir el conector
• Certificar el conector

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.