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

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 utilizando una definición de OpenAPI que describe la API Text Analytics Sentiment de Cognitive Services (nuestro ejemplo para esta serie).

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

• Creación de un conector personalizado a partir de una colección de Postman
• Creación de 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).
• 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, 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.

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, elija Conector de Logic Apps y elija Editar.

   

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

   

Importar la definición de OpenAPI 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. Seleccione Nuevo conector personalizado y, después, Importar un archivo de OpenAPI.

   

4. Escriba un nombre para el conector personalizado, navegue a la definición de OpenAPI que ha descargado o creado y 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 se correponden los valores con las secciones del archivo OpenAPI.

1. En la parte superior del asistente, asegúrese de que el nombre se establece en "SentimentDemo" y, después, seleccione Crear conector.

2. En la página General, revise la información que se importó desde la definición de OpenAPI, incluido el host de API y la dirección URL base de 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, vea 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 IU:

     "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 elegir Edición 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 IU:

  "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 para 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. Para obtener información sobre cómo definir objetos desde cero en esta interfaz de usuario, vea 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, ve 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 IU:

   "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 de la 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, consulte Ampliar 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 más descriptivo cuando alguien lo utilice en una aplicación lógica, un flujo o una aplicación. Le mostraremos cómo hacer un cambio simple en la definició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 la descripción del parámetro y, a continuación, elija Volver.

   

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

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

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

Descargue el archivo OpenAPI actualizado

Puede crear un conector personalizado desde un archivo de OpenAPI, una colección de Postman 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 de 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.

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 Microsoft Flow, regresará 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.

   

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