Microsoft Power PlatformDirección CLI de conectores

  • Artículo
  • Tiempo de lectura: 9 minutos

Nota

En estas notas de la versión se describe una funcionalidad que puede que no se haya publicado todavía. Para ver cuándo está prevista la publicación de esta funcionalidad, consulte 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 (consulte Directiva de Microsoft).

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

Instalando

  1. Instale Python 3.5+ desde https://www.python.org/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

Directorio y archivos del conector personalizado

Un conector personalizado consta de tres archivos: un icono para el conector, una definición de swagger de Open API y un archivo de propiedades de la API. 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. Puede encontrar más información sobre las definición de la API utilizadas para escribir un conector personalizado en la documentación del conector sobre el tema. Revise también el tutorial sobre Extensión de una definición de OpenApi.

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

  • 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 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",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://preview.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, ya que se creará un nuevo conector personalizado con el 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. Este parámetro es necesario para las tres operaciones.

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

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

  • icon: ruta de acceso al archivo del icono. Es necesario para las operaciones de creación y actualización. Cuando esta opción está presente durante la descarga, se escribirá en el archivo de la ubicación especificada.

  • powerAppsApiVersion: versión de API que se utilizará para Power Apps. Este elemento es opcional y está establecido en 2016-11-01 de forma predeterminada.

  • powerAppsUrl: URL de API para Power Apps. Este elemento es opcional y está establecido en https://preview.api.powerapps.com de forma 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.

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.
   --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 tres archivos descritos anteriormente. Para crear un conector, ejecute:

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

or

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]

or

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, la definición de la API, las propiedades de la API y el archivo del icono se deben proporcionar 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. 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.

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

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.
   --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 a partir de los tres archivos descritos anteriormente. Para actualizar un conector, ejecute:

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

or

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]

or

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, la definición de la API, las propiedades de la API y el archivo del icono se deben proporcionar 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 Id. de entorno y de conector correctos.

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

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

Práctica recomendada

Descargue todos los conectores personalizados y use Git o cualquier otro sistema de control de código fuente para guardar los archivos. En el caso de 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.

Informes de problemas y comentarios

Si aparecen errores al usar la herramienta, envíe un 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.