Extender una definición de OpenAPI para un conector personalizado

Una forma de crear conectores personalizados para Azure Logic Apps, Microsoft Power Automate o Microsoft Power Apps es proporcionar un archivo de definición de OpenAPI, que es un documento que pueden leer las máquinas, que es independiente del lenguaje y que describe las operaciones y los parámetros de la API. Junto con la funcionalidad lista para usar de OpenAPI, también puede incluir las siguientes extensiones de OpenAPI al crear conectores personalizados para Logic Apps y Power Automate:

• summary
• x-ms-summary
• description
• x-ms-visibility
• x-ms-api-annotation
• x-ms-operation-context
• x-ms-capabilities
• x-ms-trigger
• x-ms-trigger-hint
• x-ms-notification-content
• x-ms-notification-url
• x-ms-url-encoding
• x-ms-dynamic-values and x-ms-dynamic-list
• x-ms-dynamic-schema and x-ms-dynamic-properties

En las secciones siguientes se describen estas extensiones.

Resumen

Especifica el título de la acción (operación).

Se aplica a: operaciones
Recomendación: usar el caso de oración para summary.
Ejemplo: "Cuando se agrega un evento al calendario" o "Enviar un correo electrónico"

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

Especifica el título de una entidad.

Se aplica a: parámetros y esquema de respuesta
Recomendación: usar el tipo título para x-ms-summary.
Ejemplo: "Id. de calendario", "Asunto", "Descripción del evento"

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

Descripción

Especifica una explicación detallada de la funcionalidad de la operación o el formato y la función de una entidad.

Se aplica a: operaciones, parámetros y esquema de respuesta
Recomendación: usar el caso de oración para description.
Ejemplo: "Esta operación se desencadena cuando se agrega un nuevo evento al calendario", "Especificar el asunto del correo electrónico"

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

Especifica la visibilidad orientada hacia el usuario de una entidad.

Valores posibles: important, advanced e internal
Se aplica a: operaciones, parámetros y esquemas

• Las operaciones y los parámetros important siempre se muestran en primer lugar al usuario.
• Las operaciones y los parámetros advanced están ocultos en un menú adicional.
• Las operaciones y los parámetros internal se ocultan al usuario.

Nota

En el caso de los parámetros que sean internal y required, debe proporcionar los valores predeterminados de los mismos.

Ejemplo: los menús Ver más y Mostrar opciones avanzadas no muestran las operaciones y los parámetros advanced.

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

Se usa tanto para el control de versiones como para la administración del ciclo de vida de una operación.

Se aplica a: operaciones

• family—Cadena que muestra la carpeta de la familia de operaciones.
• revision—Un valor entero que indica el número de revisión.
• replacement—Objeto que contiene la información y las operaciones de la API de reemplazo.

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Se usa para simular la activación de un desencadenador, con el fin de habilitar las pruebas de un flujo dependiente del desencadenador.

Se aplica a: operaciones

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

Cuando se utiliza en un nivel de conector, se proporciona información general de las funcionalidades que ofrece el conector, lo que incluye operaciones específicas.

Se aplica a: conectores

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

Cuando se usa en el nivel de operación, se usa para identificar que la operación admite la carga de fragmentos o el tamaño de los fragmentos estáticos, y que usuario puede proporcionarlos.

Se aplica a: operaciones

• chunkTransfer—Valor booleano que indica si se admite la transferencia de fragmentos.

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Identifica si la operación actual es un desencadenador que genera un evento individual. La ausencia de este campo significa que se trata de una operación action.

Se aplica a: operaciones

• single—Respuesta de objeto
• batch—Respuesta de matriz

"x-ms-trigger": "batch"

x-ms-trigger-hint

Descripción del procedimiento para activar un evento para una operación del desencadenador.

Se aplica a: operaciones

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Contiene una definición del esquema de una solicitud de notificación de webhook. Es el esquema de una carga útil de webhook publicada por servicios externos en la dirección URL de notificación.

Se aplica a recursos

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

Identifica en un valor booleano si se debe colocar una dirección URL de notificación de webhook en este campo o parámetro en el caso de una operación de registro de webhook.

Se aplica a: parámetros/campos de entrada

"x-ms-notification-url": true

x-ms-url-encoding

Identifica si la codificación del parámetro de ruta de acceso actual se debe realizar con dos direcciones URL double o con una sola single. La ausencia de este campo indica que la codificación es single.

Se aplica a: parámetros de ruta

"x-ms-url-encoding": "double"

Usar valores dinámicos

Los valores dinámicos son una lista de opciones para que el usuario seleccione los parámetros de entrada para una operación. 

Se aplica a: parámetros 

Cómo usar valores dinámicos

Nota

Una cadena de ruta es un puntero JSON que no contiene la barra diagonal delantera. Entonces, este es un puntero JSON: /property/childProperty, y esta es una cadena de ruta: property/childProperty.

Existen dos formas de definir valores dinámicos:

1. Usar x-ms-dynamic-values

   Nombre	Obligatorios	Descripción
   operationId	Sí	La operación que devuelve los valores.
   parámetros	Sí	Un objeto que proporciona los parámetros de entrada necesarios para invocar una operación dynamic-values.
   value-collection	No	Una cadena de ruta de acceso que se evalúa como una matriz de objetos en la carga útil de respuesta. Si value-collection no se especifica, la respuesta se evalúa como una matriz.
   value-title	No	Una cadena de ruta de acceso en el objeto dentro de "value-collection" que hace referencia a la descripción del valor.
   value-path	No	Una cadena de ruta de acceso en el objeto dentro de "value-collection" que hace referencia al valor del parámetro.

   "x-ms-dynamic-values": {
       "operationId": "PopulateDropdown",
       "value-path": "name",
       "value-title": "properties/displayName",
       "value-collection": "value",
       "parameters": {
           "staticParameter": "<value>",
           "dynamicParameter": {
               "parameter": "<name of the parameter to be referenced>"
           }
       }
   }  
   

   Nota

   Es posible tener referencias de parámetros ambiguas cuando se usan valores dinámicos. Por ejemplo, en la siguiente definición de operación, los valores dinámicos hacen referencia al campo id, que es ambiguo en cuanto a la definición, ya que no está claro si hace referencia al parámetro id o la propiedad requestBody/id.

   {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicValuesWithAmbiguousReferences",
       "parameters": [{
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
       }, {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "id": {
                       "description": "The request Id",
                       "type": "string"
                   },
                   "model": {
                       "description": "The model",
                       "type": "string",
                       "x-ms-dynamic-values": {
                           "operationId": "GetSupportedModels",
                           "value-path": "name",
                           "value-title": "properties/displayName",
                           "value-collection": "value",
                           "parameters": {
                               "requestId": {
                                   "parameter": "id"
                               }
                           }
                       }
                   }
               }
           }
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "type": "object"
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

2. x-ms-dynamic-list

   No hay manera de hacer referencia a los parámetros de manera inequívoca. Esta característica se puede proporcionar en el futuro. Si desea que la operación saque provecho de las nuevas actualizaciones, agregue la nueva extensión x-ms-dynamic-list junto con x-ms-dynamic-values. También, si la extensión dinámica hace referencia a las propiedades de los parámetros, tiene que agregar la nueva extensión x-ms-dynamic-list junto con x-ms-dynamic-values. Las referencias de parámetros que apuntan a propiedades deben expresarse como cadenas de ruta.

   • parameters: esta propiedad es un objeto en el que cada propiedad de entrada de la operación dinámica a la que se llama se define con un campo de valor estático o una referencia dinámica a la propiedad de la operación de origen. Ambas opciones se definen a continuación.

   • value: este es el valor literal que se va a usar para el parámetro de entrada. En el ejemplo siguiente, el parámetro de entrada de la operación GetDynamicList denominado version se define utilizando un valor estático de 2.0.

     {
         "operationId": "GetDynamicList",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference: es la ruta de acceso de referencia del parámetro completa. Empieza por el nombre del parámetro y después la cadena de ruta de acceso de la propiedad a la que se hace referencia. Por ejemplo, la propiedad de entrada de la operación GetDynamicList llamada property1, que está debajo del parámetro destinationInputParam1, se define como una referencia dinámica a una propiedad llamada property1 bajo el parámetro sourceInputParam1 de la operación de origen.

     {
         "operationId": "GetDynamicList",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Nota

     Si desea hacer referencia a todas las propiedades marcadas como internas con un valor predeterminado, tiene que usar el valor predeterminado como valor estático en la definición, en lugar de parameterReference. El valor predeterminado de la lista no se utiliza si se ha definido mediante parameterReference.

     Nombre	Obligatorio	Descripción
     operationId	Sí	La operación que devuelve la lista.
     parámetros	Sí	Un objeto que proporciona los parámetros de entrada necesarios para invocar una operación de lista dinámica.
     itemsPath	No	Una cadena de ruta de acceso que se evalúa como una matriz de objetos en la carga útil de respuesta. Si itemsPath no se especifica, la respuesta se evalúa como una matriz.
     itemTitlePath	No	Una cadena de ruta de acceso en el objeto dentro de itemsPath  que hace referencia a una descripción del valor.
     itemValuePath	No	Cadena de ruta de acceso en el objeto dentro de itemsPath que hace referencia al valor del elemento.

     Con x-ms-dynamic-list, utilice referencias de parámetro con la cadena de ruta de acceso de la propiedad a la que hace referencia. Utilice estas referencias de parámetros para la clave y el valor de la referencia del parámetro de operación dinámica.

     {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicListWithAmbiguousReferences",
       "parameters": [
         {
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
         },
         {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
             "description": "Input body to execute the request",
             "type": "object",
             "properties": {
               "id": {
                 "description": "The request id",
                 "type": "string"
               },
               "model": {
                 "description": "The model",
                 "type": "string",
                 "x-ms-dynamic-values": {
                   "operationId": "GetSupportedModels",
                   "value-path": "name",
                   "value-title": "properties/displayName",
                   "value-collection": "cardTypes",
                   "parameters": {
                     "requestId": {
                       "parameter": "id"
                     }
                   }
                 },
                 "x-ms-dynamic-list": {
                   "operationId": "GetSupportedModels",
                   "itemsPath": "cardTypes",
                   "itemValuePath": "name",
                   "itemTitlePath": "properties/displayName",
                   "parameters": {
                     "requestId": {
                       "parameterReference": "requestBody/id"
                     }
                   }
                 }
               }
             }
           }
         }
       ],
       "responses": {
         "200": {
           "description": "OK",
           "schema": {
             "type": "object"
           }
         },
         "default": {
           "description": "Operation Failed."
         }
       }
     } 
     

Usar el esquema dinámico

El esquema dinámico indica que el esquema del parámetro o la respuesta actuales es dinámico. Este objeto invoca una operación a la que define el valor de este campo, detecta dinámicamente el esquema y muestra la interfaz de usuario (IU) apropiada para recopilar los datos que introduce el usuario o muestra los campos disponibles.

Se aplica a: parámetros, respuestas

Esta imagen muestra cómo cambia el formulario de entrada en función del elemento que el usuario selecciona en la lista:

Esta imagen muestra cómo cambia el resultado en función del elemento que el usuario selecciona en la lista desplegable. En esta versión, el usuario selecciona Coches:

En esta versión, el usuario selecciona Alimentación:

Cómo usar el esquema dinámico

Nota

Una cadena de ruta es un puntero JSON que no contiene la barra diagonal delantera. Entonces, este es un puntero JSON: /property/childProperty, y esta es una cadena de ruta: property/childProperty.

Existen dos formas de definir un esquema dinámico:

1. x-ms-dynamic-schema:

   Nombre	Obligatorios	Descripción
   operationId	Sí	La operación que devuelve el esquema.
   parámetros	Sí	Un objeto que proporciona los parámetros de entrada necesarios para invocar una operación dynamic-schema.
   value-path	No	Una cadena de ruta de acceso que hace referencia a la propiedad que tiene el esquema. Si no se especifica, se supone que la respuesta contiene el esquema en las propiedades del objeto raíz. Si se especifica, la respuesta exitosa debe contener la propiedad. Para un esquema vacío o indefinido, este valor debe ser nulo.

     {
     "name": "dynamicListSchema",
     "in": "body",
     "description": "Dynamic schema for items in the selected list",
     "schema": {
         "type": "object",
         "x-ms-dynamic-schema": {
             "operationId": "GetListSchema",
             "parameters": {
                 "listID": {
                     "parameter": "listID-dynamic"
                 }
             },
             "value-path": "items"
         }
       }
     }
   

   Nota

   Puede haber referencias ambiguas en los parámetros. Por ejemplo, en la siguiente definición de una operación, el esquema dinámico hace referencia a un campo denominado query, que no se puede entender de forma determinista a partir de la definición, tanto si hace referencia al objeto de parámetro query o a la propiedad de cadena query/query.

   {
   
       "summary": "Tests dynamic schema with ambiguous references",
       "description": "Tests dynamic schema with ambiguous references.",
       "operationId": "TestDynamicSchemaWithAmbiguousReferences",
       "parameters": [{
           "name": "query",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "query": {
                       "description": "Query Text",
                       "type": "string"
                   }
               }
           },
           "x-ms-summary": "query text"
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "x-ms-dynamic-schema": {
                       "operationId": "GetDynamicSchema",
                       "parameters": {
                           "query": {
                               "parameter": "query"
                           }
                       },
                       "value-path": "schema/valuePath"
                   }
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

   Ejemplos de conectores de código abierto

   Conector	Escenario	Vincular
   Ticketing	Obtener un esquema para obtener detalles del evento seleccionado	Ticketing

2. x-ms-dynamic-properties:

   No hay manera de hacer referencia a los parámetros de manera inequívoca. Esta característica se puede proporcionar en el futuro. Si desea que la operación saque provecho de las nuevas actualizaciones, agregue la nueva extensión x-ms-dynamic-properties junto con x-ms-dynamic-schema. También, si la extensión dinámica hace referencia a las propiedades de los parámetros, tiene que agregar la nueva extensión x-ms-dynamic-properties junto con x-ms-dynamic-schema. Las referencias de parámetros que apuntan a propiedades deben expresarse como cadenas de ruta.

   • parameters: esta propiedad es un objeto en el que cada propiedad de entrada de la operación dinámica a la que se llama se define con un campo de valor estático o una referencia dinámica a la propiedad de la operación de origen. Ambas opciones se definen a continuación.

   • value: este es el valor literal que se va a usar para el parámetro de entrada. En el siguiente ejemplo, el parámetro de entrada de la operación GetDynamicSchema denominado versión se define con el valor estático de 2.0.

     {
         "operationId": "GetDynamicSchema",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference: es la ruta de acceso de referencia del parámetro completa. Empieza por el nombre del parámetro y después la cadena de ruta de acceso de la propiedad a la que se hace referencia. Por ejemplo, la propiedad de entrada de la operación GetDynamicSchema llamada property1, que está debajo del parámetro destinationInputParam1, se define como una referencia dinámica a una propiedad llamada property1 bajo el parámetro sourceInputParam1 de la operación de origen.

     {
         "operationId": "GetDynamicSchema",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Nota

     Si desea hacer referencia a todas las propiedades marcadas como internas con un valor predeterminado, tiene que usar el valor predeterminado como valor estático en la definición, en lugar de parameterReference. El valor predeterminado del esquema no se utiliza si se ha definido mediante parameterReference.

     Nombre	Obligatorio	Descripción
     operationId	Sí	La operación que devuelve el esquema.
     parámetros	Sí	Un objeto que proporciona los parámetros de entrada necesarios para invocar una operación dynamic-schema.
     itemValuePath	No	Una cadena de ruta de acceso que hace referencia a la propiedad que tiene el esquema. Si no se especifica, se supone que la respuesta contiene el esquema en el objeto raíz. Si se especifica, la respuesta exitosa debe contener la propiedad. Para un esquema vacío o indefinido, este valor debe ser nulo.

     Con x-ms-dynamic-properties, se pueden usar referencias de parámetro con la cadena de ruta de acceso de la propiedad a la que se va a hacer referencia, tanto para la clave como para el valor de la referencia de parámetro de la operación dinámica.

         {
         "summary": "Tests dynamic schema with ambiguous references",
         "description": "Tests dynamic schema with ambiguous references.",
         "operationId": "TestDynamicSchemaWithAmbiguousReferences",
         "parameters": [{
             "name": "query",
             "in": "body",
             "description": "query text.",
             "required": true,
             "schema": {
                 "description": "Input body to execute the request",
                 "type": "object",
                 "properties": {
                     "query": {
                         "description": "Query Text",
                         "type": "string"
                     }
                 }
             },
             "x-ms-summary": "query text"
         }],
         "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                     "x-ms-dynamic-schema": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": "2.0",
                             "query": {
                                 "parameter": "query"
                             }
                         },
                         "value-path": "schema/valuePath"
                     },
                     "x-ms-dynamic-properties": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": {
                                 "value": "2.0"
                             },
                             "query/query": {
                                 "parameterReference": "query/query"
                             }
                         },
                         "itemValuePath": "schema/valuePath"
                     }
                 }
             },
             "default": {
                 "description": "Operation Failed."
             }
           }
         }
     

Siguiente paso

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

Consulte también

Información general sobre los conectores personalizados

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.