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

Nota

Este tema 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. 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, con una definición de OpenAPI que describa la API de Texto Analytics de Cognitive Services (nuestro ejemplo para esta serie).

Para otra forma de describir una API, vaya a Crear un conector personalizado desde cero.

Requisitos previos

• Una definición de OpenAPI que describe la API de ejemplo. Al crear un conector personalizado, la definición de OpenAPI debe ser inferior a 1 MB. La definición de OpenAPI debe estar en formato OpenAPI 2.0 (anteriormente conocido como Swagger).

  Si hay varias definiciones de seguridad, el conector personalizado elige la definición de seguridad superior. La creación de conectores personalizados no admite credenciales de cliente (por ejemplo, aplicación y contraseña) en la definición de seguridad de OAuth.

• Una clave de API para la API de Texto Analytics de Cognitive Services.

• Una de las siguientes suscripciones:

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

• Si usa Logic Apps, cree un conector personalizado de Azure Logic Apps en primer lugar.

Importar la definición de OpenAPI

Ahora está listo para trabajar con la definición de OpenAPI que descargó. Toda la información requerida está contenida en la definición, y puede revisar y actualizar esta información a medida que avanza por el asistente para conector personalizado.

Comience por importar la definición de OpenAPI para Logic Apps o para Power Automate y Power Apps.

Nota

Una definición de OpenAPI debe estar en formato OpenAPI 2.0 (anteriormente conocido como Swagger). Las definiciones de OpenAPI que están en OpenAPI 3.0 no son compatibles.

Importar la definición de OpenAPI 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, seleccione Conector de Logic Apps y, después, Editar.

   

3. En General, seleccione Cargar un archivo de OpenAPI y, a continuación, vaya a la definición de OpenAPI que creó.

   

Nota

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

Importar la definición de OpenAPI para Power Automate y Power Apps

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 y, después, Importar un archivo de OpenAPI.

   

4. Escriba un nombre para el conector personalizado, vaya a la definición de OpenAPI que ha descargado o creado y, después, seleccione Continuar.

   

   Parámetro	valor
   Título de conector personalizado	SentimentDemo

Revisar 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ñalaremos cualquier diferencia. En esta parte de tema, revisaremos principalmente la interfaz de usuario y le mostraremos cómo los valores corresponden a las secciones del archivo OpenAPI.

1. En la parte superior del asistente, asegúrese de que se establezca el nombre SentimentDemo y, a continuación, seleccione Crear conector.

2. En la página General, revise la información que se importó desde la definición de OpenAPI, incluido el anfitrión de la API y la dirección URL base para la API. El conector usa el host de la API 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, vaya a Conectar a las API locales utilizando la puerta de enlace de datos.

   La siguiente sección de la definición de OpenAPI contiene información para esta página de la interfaz de usuario:

     "info": {
       "version": "1.0.0",
       "title": "SentimentDemo",
       "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
     },
     "host": "westus.api.cognitive.microsoft.com",
     "basePath": "/",
     "schemes": [
       "https"
     ]
   

Revisar 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 se especifica en la definición de OpenAPI.

En la página Seguridad, revise la información de autenticación para la clave de API.

La etiqueta se muestra cuando alguien se conecta por primera vez con el conector personalizado; se puede seleccionar Editar y cambiar este valor. El nombre y la ubicación del parámetro deben coincidir con lo que espera la API, en este caso, Ocp-Apim-Subscription-Key y Header.

La siguiente sección de la definición de OpenAPI contiene información para esta página de la interfaz de usuario:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Revisar la definición del conector

La página Definición del asistente del conector personalizado proporciona muchas opciones para definir cómo funciona el conector y cómo se expone en Logic Apps, flujos y aplicaciones. Explicaremos la IU y cubriremos algunas opciones en esta sección, pero también le animamos a explorar por su cuenta. Para obtener información sobre cómo definir objetos desde cero en esta interfaz de usuario, vaya a Crear la definición del conector.

1. En el área siguiente 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 definición de OpenAPI. 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. 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:

   • Ninguna: normalmente se muestra en la aplicación lógica o el flujo

   • avanzada: oculta en un menú adicional

   • interna: oculta al usuario

   • Importante: se muestra siempre primero al usuario

     

3. En el área Solicitud, se muestra la información basada en la solicitud HTTP que se incluye en la definición de OpenAPI. 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.

   

   La siguiente sección de la definición de OpenAPI contiene información para las áreas General y Solicitud de la interfaz de usuario:

   "paths": {
     "/text/analytics/v2.0/sentiment": {
       "post": {
         "summary": "Returns a numeric score representing the sentiment detected",
         "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
         "operationId": "DetectSentiment"
   

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

   

   La siguiente sección de la definición de OpenAPI contiene alguna información relacionada con la respuesta:

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   Esta sección muestra los dos valores que devuelve el conector: id y score. Incluye sus tipos de datos y el campo x-ms-summary, que es una extensión OpenAPI. Para obtener más información sobre esta y otras extensiones, vaya a Extender una definición de OpenAPI para un conector personalizado.

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

La definición de OpenAPI que ha descargado es un buen ejemplo básico, pero podría trabajar con definiciones que requieren una gran cantidad de actualización, para que el conector sea menos problemático cuando alguien lo utiliza en Logic Apps, un flujo o una aplicación. Le mostraremos cómo hacer un cambio en la definició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 la descripción del parámetro y, a continuación, seleccione Volver.

   

   Parámetro	Valor
   Descripción	Un identificador numérico para cada documento que se envía

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

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

Descargue el archivo de OpenAPI actualizado

Actualmente puede crear un conector personalizado desde un archivo de OpenAPI o desde cero (en Power Automate y Power Apps). Independientemente de cómo cree el conector, puede descargar la definición de OpenAPI que el servicio utiliza internamente.

• En Logic Apps, se descarga desde el conector personalizado.

  

• En Power Automate o Power Apps, descargue desde la lista de conectores personalizados.

  

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, seleccione Nueva conexión.

   

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

   

3. Vuelva a la página Prueba y realice una de las siguientes acciones:

   • En Power Automate, regresará a la página Prueba. Seleccione 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, seleccione 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, seleccione Probar operación.

   

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

   

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 de una aplicación lógica

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