Comparteix a través de

Crear un conector personalizado con el CLI

  • Article

La herramienta de la línea de comandos paconn está diseñada para ayudar en el desarrollo de conectores personalizados de Microsoft Power Platform.

Nota

Instalar

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

  2. Ejecute el instalador para comenzar la instalación y asegúrese de activar la casilla 'Agregar Python X.X a PATH'.

  3. Asegúrese de que la ruta de instalación está en la variable PATH mediante la ejecución de:

    python --version

  4. 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 de swagger de API abierta, un archivo de propiedades de API, un icono opcional para el conector y un 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 las definiciones de API utilizadas para escribir conectores personalizados, 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 del conector personalizado. Estas propiedades no forman parte de la definición de la API. Contienen 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"
        }
      }
    ]    
  }
}

A continuación se proporciona 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: describe las funcionalidades del conector; por ejemplo, solo en la nube, puerta de enlace local, etc.

  • 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 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"
}

En el archivo de configuración, se esperan los siguientes elementos. 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. Este parámetro es necesario para las operaciones de descarga y actualización, pero no para la operación de creación o validación. Se creará un nuevo conector personalizado con el nuevo ID para el comando de creación. 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. Este parámetro es necesario para todas las operaciones, excepto la operación de validación.

  • apiProperties: ruta de acceso al archivo apiProperties.json de propiedades de la API. Es necesario para las operaciones de creación y actualización. Cuando esta opción está presente durante la descarga, el archivo se descargará en la ubicación especificada; de lo contrario, se guardará como apiProperties.json.

  • apiDefinition: ruta de acceso al archivo Swagger. Es necesario para las operaciones de creación, actualización y validación. Cuando esta opción está presente durante la operación de descarga, el archivo se escribirá en la ubicación especificada; de lo contrario, se guardará como apiDefinition.swagger.json.

  • icon: ruta de acceso al archivo del icono opcional. Las operaciones de creación y actualización utilizarán el icono predeterminado cuando no se especifique este parámetro. Cuando esta opción está presente durante la operación de descarga, el archivo se escribirá en la ubicación especificada; de lo contrario, se guardará como icon.png.

  • script: ruta de acceso al archivo de script opcional. Las operaciones de creación y actualización solo utilizarán el valor que esté dentro de los parámetros especificados. Cuando esta opción está presente durante la operación de descarga, el archivo se escribirá en la ubicación especificada; de lo contrario, se guardará 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

Inicio de sesión

Inicie sesión en Power Platform ejecutando:

paconn login

Este comando le pedirá que inicie sesión con el proceso de inicio de sesión del código de dispositivo. Siga las indicaciones del inicio de sesión. La autenticación del principio de servicio no se admite en este momento.

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

or

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

or

paconn download -s [Path to settings.json]

Si no se especifica el Id. del entorno o del conector, el comando solicitará 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

Se 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]

o bien

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]

o bien

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

Cuando no se especifica el entorno, el comando lo solicitará. 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. Para los conectores que utilicen OAuth2, se debe proporcionar el secreto de 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 identificador 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]

o bien

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]

o bien

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. Para un conector que utilice OAuth2, se debe proporcionar el secreto de OAuth2. El comando imprimirá 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]

o bien

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 el entorno de Power Automate y Power Apps. Cuando no se especifica un entorno, solo se muestran los entornos de Power Automate para elegir entre ellos. No se devuelve el archivo Swagger para los conectores no personalizados.

Propiedad stackOwner y archivo apiProperties

Actualmente, existe una limitación que le impide actualizar los artefactos de su conector en su entorno usando Paconn cuando el archivo apiProperties.json contiene la propiedad stackOwner. Como solución a esto, cree dos versiones de sus artefactos de conector: la primera es la versión que se envía a la certificación y contiene la propiedad stackOwner. La segunda tiene la propiedad stackOwner omitida para habilitar la actualización dentro de su 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 características. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.