Creación de un conector personalizado con una extensión de OpenAPI

Una manera de crear conectores personalizados para Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate o Microsoft Power Apps es proporcionar un archivo de definición de OpenAPI. Un archivo de definición de OpenAPI es un documento independiente del lenguaje y legible por la máquina 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
Recomendado: Utilizar 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, esquema de respuesta
Recomendado: usar la casi de 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

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

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

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

Posibles valores: important, advanced y internal
Se aplica a: operaciones, parámetros y esquemas

• El usuario siempre ve primero important las operaciones y los parámetros.
• El usuario ve advanced las operaciones y los parámetros solo cuando usan un menú adicional.
• El usuario no ve internal operaciones y parámetros.

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

"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 para el control de versiones y 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

Use esta propiedad para simular la activación de un desencadenador para poder probar 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 usa esta propiedad en el nivel de conector, se proporciona información general sobre las funcionalidades que ofrece el conector, incluidas las operaciones específicas.

Se aplica a: conectores

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

Cuando se utiliza esta propiedad en el nivel de operación, se identifica que la operación admite la carga de fragmentos y el tamaño de fragmento estático, que el usuario puede proporcionar.

Se aplica a: operaciones

• chunkTransfer: valor booleano que indica si se admite la transferencia de fragmentos.

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

x-ms-trigger

Indica si la operación actual es un desencadenador que genera un único evento. Si este campo está ausente, la operación es un action.

Se aplica a: operaciones

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

"x-ms-trigger": "batch"

x-ms-trigger-hint

Describe el 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. Este esquema define la carga del webhook que los servicios externos publican en la dirección URL de notificación.

Se aplica a recursos

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

x-ms-notification-url

Use un valor booleano para especificar si se debe incluir una dirección URL de notificación de webhook en este parámetro o campo para una operación de registro de webhook.

Se aplica a: Parámetros y campos de entrada

"x-ms-notification-url": true

x-ms-url-encoding

Especifique si el parámetro de ruta de acceso actual debe usar la codificación de dirección URL doble (double) o la codificación url única (single). Si falta este campo, predetermina la codificación de single.

Se aplica a: parámetros de ruta

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

x-ms-dynamic-values

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

Puede definir valores dinámicos de dos maneras:

• Usar x-ms-dynamic-values

  Nombre	Obligatorios	Descripción
  operationId	Sí	La operación que devuelve los valores.
  parameters	Sí	Un objeto que proporciona los parámetros de entrada necesarios para invocar una operación de valores dinámicos.
  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>"
          }
      }
  }  
  

{
    "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."
        }
    }
}

• Usa x-ms-dynamic-list

  No se pueden hacer referencia de forma inequívoca a los parámetros. 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. Además, si la extensión dinámica hace referencia a propiedades dentro de parámetros, debe 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 se define cada propiedad de entrada de la operación dinámica a la que se llama 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 en la sección siguiente.

  • 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: esta es la ruta de referencia de parámetro completa, empezando por el nombre del parámetro seguido de la cadena de ruta de la propiedad a la que se va a hacer 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"
        }
      }
    }
    

Con x-ms-dynamic-list, utilice referencias de parámetro con la cadena de ruta 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."
    }
  }
} 

x-ms-dynamic-schema

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

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

En la imagen siguiente se muestra cómo cambian las salidas, 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

Puede definir el esquema dinámico de dos maneras:

• x-ms-dynamic-schema:

  Nombre	Obligatorios	Descripción
  operationId	Sí	La operación que devuelve el esquema.
  parameters	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 que hace referencia a la propiedad que tiene el esquema. Si no especifica esta propiedad, se supone que la respuesta contiene el esquema en las propiedades del objeto raíz. Si se especifica, la respuesta satisfactoria 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"
        }
      }
    }
  

{

    "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

• 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. Además, si la extensión dinámica hace referencia a propiedades dentro de parámetros, debe 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 se define cada propiedad de entrada de la operación dinámica a la que se llama 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 en la sección siguiente.

  • 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

  Para hacer referencia a cualquier propiedad marcada como interna con un valor predeterminado, use el valor predeterminado como un valor estático en la definición aquí, en lugar de parameterReference. El valor predeterminado del esquema no se utiliza si se ha definido mediante parameterReference.

  Nombre	Obligatorios	Descripción
  operationId	Sí	La operación que devuelve el esquema.
  parameters	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.

  Al usar x-ms-dynamic-properties, puede 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

Información relacionada

Información general sobre los conectores personalizados

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.