Crear un conector personalizado con el CLI

La herramienta de la línea de comandos paconn está diseñada para ayudar en la creación de conectores personalizados de Copilot Studio y Power Platform.

Nota

Es posible que esta funcionalidad aún no se haya lanzado.
Para ver cuándo se publica esta información, vaya a Características nuevas y previstas para Common Data Model y la integración de datos.
Las escalas de tiempo de entrega y la funcionalidad proyectada podrían cambiar o no distribuirse (vaya a Microsoft Policy).

Instalar

Instale Python 3.5+ desde [https://www.python.org/downloads](Python downloads). Seleccione el vínculo Descargar en cualquier versión de Python posterior a Python 3.5. Para Linux y macOS X siga el vínculo correspondiente de la página. También puede instalar con el administrador de paquetes específico del sistema operativo de su elección.
Ejecute el instalador para comenzar la instalación y asegúrese de activar la casilla Agregar Python X.X a PATH.
Asegúrese de que la ruta de instalación está en la variable PATH ejecutando:

python --version
Una vez instalado Python, instale paconn; para ello, ejecute:

pip install paconn

Si obtiene errores que dicen Acceso denegado, puede usar la opción --user o ejecutar el comando como Administrador (Windows).

Directorio y archivos del conector personalizados

Un conector personalizado consta de dos a cuatro archivos:

una definición Open API/swagger
un archivo de propiedades de la API
Un icono opcional para el conector
archivo de script csharp opcional

Los archivos suelen encontrarse en un directorio con el identificador del conector como nombre del directorio.

En ocasiones, el directorio del conector personalizado puede incluir un archivo settings.json. Aunque este archivo no forma parte de la definición del conector, se puede usar como almacén de argumentos para la CLI.

Archivo de definición de API (Swagger)

El archivo de definición de API describe la API para el conector personalizado mediante la especificación OpenAPI. También se conoce como archivo swagger. Para obtener más información sobre cómo un archivo de definición de API le ayuda a crear un conector personalizado, vaya a Crear un conector personalizado a partir de una definición de OpenAPI. También revise el tutorial en el artículo Extender una definición de OpenAPI para un conector personalizado.

Archivo de propiedades de la API

El archivo de propiedades de la API contiene algunas propiedades para el conector personalizado que no forman parte de la definición de la API. El archivo de propiedades API contiene información como el color de la marca, la información de autenticación, etc. Un archivo de propiedades de API típico tiene un aspecto como el de la muestra siguiente:

{
  "properties": {
    "capabilities": [],
    "connectionParameters": {
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "constraints": {
            "clearText": false,
            "required": "true",
            "tabIndex": 2
          },
          "description": "The KEY for this API",
          "displayName": "KEY",
          "tooltip": "Provide your KEY"
        }
      }
    },
    "iconBrandColor": "#007EE6",
    "scriptOperations": [
        "getCall",
        "postCall",
        "putCall"
    ],
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Aquí tienes más información sobre cada una de las propiedades:

properties: contenedor de la información.
connectionParameters: define el parámetro de conexión del servicio.
iconBrandColor: color de la marca del icono en código hexadecimal HTML del conector personalizado.
scriptOperations: una lista de las operaciones que se ejecutan con el archivo de script. Una lista vacía de scriptOperations indica que todas las operaciones se ejecutan con el archivo de script.
capabilities: descripción de las capacidades del conector. Por ejemplo, solo en la nube y puerta de enlace local.
policyTemplateInstances: lista opcional de instancias de la plantilla de directivas y valores utilizados en el conector personalizado.

Archivo de icono

El archivo de icono es una imagen pequeña que representa el icono del conector personalizado.

Archivo de script

El script de Visual C# es un archivo de script CSX que se implementa para el conector personalizado y se ejecuta para cada llamada a un subconjunto de las operaciones del conector.

Archivo de configuración

En lugar de proporcionar los argumentos en la línea de comandos, se puede usar el archivo settings.json para especificarlos. Un archivo de propiedades settings.json típico tiene un aspecto como el de la muestra siguiente:

{
  "connectorId": "CONNECTOR-ID",
  "environment": "ENVIRONMENT-GUID",
  "apiProperties": "apiProperties.json",
  "apiDefinition": "apiDefinition.swagger.json",
  "icon": "icon.png",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://api.powerapps.com"
}

Espere estos elementos en el archivo de configuración. Si falta una opción, pero es necesaria, la consola solicitará la información que falta.

connectorId: cadena del identificador de conector del conector personalizado. Las operaciones Descargar y actualizar requieren el parámetro ID del conector, mientras que las operaciones crear y validar no. El comando crear crea un nuevo conector personalizado con un nuevo ID. Si necesita actualizar un conector personalizado que se acaba de crear con el mismo archivo de configuración, asegúrese de que el archivo de configuración está actualizado correctamente con el nuevo Id. de conector de la operación de creación.
environment: cadena del identificador de entorno del conector personalizado. Todas las operaciones requieren este parámetro, excepto la operación de validación.
apiProperties: ruta de acceso al archivo de propiedades de la API. Las operaciones Crear y actualizar requieren el archivo de propiedades de la API. Cuando esta opción está presente durante la descarga, el archivo se descargará en su ubicación, de lo contrario, se guardará como apiProperties.json.
apiDefinition: ruta de acceso al archivo Swagger. Las operaciones crear, actualizar y validar requieren el archivo de definiciones de API. Cuando esta opción está presente durante la operación de descarga, el archivo se descarga en su ubicación; en caso contrario, el archivo se guarda como apiDefinition.swagger.json.
icon: ruta de acceso al archivo del icono opcional. Si no se especifica este parámetro, las operaciones crear y actualizar utilizan el icono predeterminado. Cuando esta opción está presente durante la operación de descarga, el archivo se descarga en su ubicación; en caso contrario, el archivo se guarda como icon.png.
script: ruta de acceso al archivo de script opcional. Las operaciones crear y actualizar solo utilizan el valor dentro del parámetro especificado. Cuando esta opción está presente durante la operación de descarga, el archivo se descarga en su ubicación; en caso contrario, el archivo se guarda como script.csx.
powerAppsUrl: URL de API para Power Apps. Este parámetro es opcional y se establece como https://api.powerapps.com de manera predeterminada.
powerAppsApiVersion: versión de API que se utilizará para Power Apps. Este parámetro es opcional y se establece como 2016-11-01 de manera predeterminada.

Operaciones de la línea de comandos

Inicie sesión en Power Platform ejecutando:

paconn login

Este comando le pide que inicie sesión utilizando el proceso de inicio de sesión con código de dispositivo. Siga las indicaciones del inicio de sesión. En este momento no hay soporte para la autenticación del principio de servicio.

Cerrar sesión

Cerrar sesión con ejecución:

paconn logout

Descargar archivos del conector personalizado

Los archivos del conector siempre se descargan en un subdirectorio con el Id. del conector como nombre del directorio. Cuando se especifica un directorio de destino, el subdirectorio se creará en el especificado. De lo contrario, se creará en el directorio actual. Además de los tres archivos del conector, la operación de descarga también escribirá un cuarto archivo llamado settings.json que contiene los parámetros utilizados para descargar los archivos.

Descargue los archivos del conector personalizado mediante la ejecución de:

paconn download

paconn download -e [Power Platform Environment GUID] -c [Connector ID]

paconn download -s [Path to settings.json]

Si no se especifica el ID del entorno o del conector, el comando solicita los argumentos que faltan. Si se descarga correctamente, el comando generará la ubicación de descarga del conector.

También se pueden especificar todos los argumentos mediante un archivo settings.json.

Arguments
   --cid -c       : The custom connector ID.
   --dest -d      : Destination directory.
   --env -e       : Power Platform environment GUID.
   --overwrite -w : Overwrite all the existing connector and settings files.
   --pau -u       : Power Platform URL.
   --pav -v       : Power Platform API version.
   --settings -s  : A settings file containing required parameters.
                    When a settings file is specified some command 
                    line parameters are ignored.

Crear un nuevo conector personalizado

Puede crear un nuevo conector personalizado a partir de los archivos de conectores ejecutando la operación create. Para crear un conector, ejecute:

paconn create --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn create -e [Power Platform Environment GUID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Si no especifica el entorno, el comando se lo pedirá. Sin embargo, es necesario proporcionar la definición de la API y el archivo de propiedades de la API como parte del argumento de la línea de comandos o en un archivo de configuración. Proporciona el secreto OAuth2 para un conector que utiliza OAuth2. El comando imprimirá el Id. de conector del conector personalizado recién creado cuando finalice correctamente. Si usa un archivo settings.json para el comando de creación, asegúrese de actualizarlo con el nuevo Id. de conector antes de actualizar el conector recién creado.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Actualizar un conector personalizado existente

Al igual que en la operación create, un conector personalizado existente se puede actualizar usando la operación update. Para actualizar un conector, ejecute:

paconn update --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn update -e [Power Platform Environment GUID] -c [Connector ID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Si no se especifica el Id. del entorno o del conector, el comando solicitará los argumentos que faltan. Sin embargo, es necesario proporcionar la definición de la API y el archivo de propiedades de la API como parte del argumento de la línea de comandos o en un archivo de configuración. Proporciona el secreto OAuth2 para un conector que utiliza OAuth2. El comando imprime el Id. del conector actualizado cuando finalice correctamente. Si usa un archivo settings.json para el comando de actualización, asegúrese de que se especifican los identificadores de entorno y de conector correctos.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --cid -c      : The custom connector ID.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Validar un archivo JSON de Swagger

La operación de validación toma un archivo Swagger y verifica si sigue todas las reglas recomendadas. Valide un archivo swagger ejecutando:

paconn validate --api-def [Path to apiDefinition.swagger.json]

paconn validate -s [Path to settings.json]

El comando imprimirá el mensaje de error, advertencia o correcto según el resultado de la validación.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Procedimiento recomendado

Descargue todos los conectores personalizados y use Git o cualquier otro sistema de control de código fuente para guardar los archivos. Si hay una actualización incorrecta, vuelva a implementar el conector; para ello, vuelva a ejecutar el comando de actualización con el conjunto de archivos correcto a partir del sistema de control de código fuente.

Pruebe el conector personalizado y el archivo de configuración en un entorno de pruebas antes de su implementación en el entorno de producción. Compruebe siempre que los Id. del entorno y del conector son correctos.

Limitaciones

El proyecto se limita a la creación, actualización y descarga de un conector personalizado en los entornos de Copilot Studio, Power Automate y Power Apps. Cuando no se especifica un entorno, sólo tiene la opción de seleccionar un entorno Power Automate. No se devuelve el archivo Swagger para los conectores no personalizados.

Nota

Propiedad stackOwner y archivo de propiedades de API

Actualmente, existe una limitación que le impide actualizar los artefactos de su conector en su entorno utilizando Paconn cuando la propiedad stackOwner está presente en su archivo de propiedades de API. Como solución alternativa a esto, cree dos versiones de los artefactos del conector:

Cree una versión que contenga la propiedad stackOwner y envíela para su certificación.
Cree una segunda versión que omita stackOwner para permitirle realizar actualizaciones en su propio entorno.

Estamos trabajando para eliminar la limitación y actualizaremos esta sección una vez completada.

Informes de problemas y comentarios

Si aparecen errores con la herramienta, envíe el problema en la sección Issues (Problemas) del repositorio de GitHub.

Si cree que ha encontrado una vulnerabilidad de seguridad que cumple la definición de Microsoft de una vulnerabilidad de seguridad, envíe un informe a MSRC. Puede encontrar más información en Preguntas más frecuentes sobre MSRC y los informes.

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.

Last updated on 2025-06-24

Compartir a través de