Création d’un connecteur personnalisé avec CLI

Article
04/24/2024

L’outil en ligne de commande paconn est conçu pour faciliter le développement de connecteurs personnalisés Microsoft Power Platform.

Notes

Ces notes de publication décrivent des fonctionnalités qui n’ont peut-être pas encore été publiées.
Pour rechercher la date de publication prévue de ces fonctionnalités, accédez à Nouveautés et prévisions pour Common Data Model et Intégration de données.
Le calendrier de publication et les fonctionnalités prévues peuvent changer ou ne pas être livrés (accédez à Stratégie Microsoft).

Install

Installez Python 3.5+ à partir de [https://www.python.org/downloads](Python downloads). Sélectionnez le lien Télécharger sur n’importe quelle version de Python supérieure à Python 3.5. Pour Linux et macOS X, suivez le lien correspondant sur la page. Vous pouvez également installer à l’aide d’un gestionnaire de package spécifique au système d’exploitation de votre choix.
Exécutez le programme d’installation pour commencer l’installation et veillez à cocher la case « Add Python X.X to PATH » (Ajouter Python X.X à CHEMIN).
Assurez-vous que le chemin d’installation est dans la variable PATH en exécutant :

python --version
Après l’installation de Python, installez paconn en exécutant :

pip install paconn

Si vous obtenez des erreurs disant « Accès refusé », envisagez d'utiliser l'option --user ou d'exécuter la commande en tant qu'administrateur (Windows).

Répertoire et fichiers du connecteur personnalisé

Un connecteur personnalisé se compose de deux à quatre fichiers : une définition Swagger Open API, un fichier de propriétés d'API, une icône facultative pour le connecteur et un fichier de script csharp facultatif. Les fichiers se trouvent généralement dans un répertoire qui utilise l’ID du connecteur comme nom.

Parfois, le répertoire du connecteur personnalisé peut inclure un fichier settings.json. Bien que ce fichier ne fasse pas partie de la définition du connecteur, il peut être utilisé comme magasin d’arguments pour l’interface CLI.

Fichier (swagger) de définition de l’API

Le fichier de définition de l’API décrit l’API du connecteur personnalisé à l’aide de la spécification OpenAPI. Il est également connu sous le nom de fichier Swagger. Pour plus d’informations sur les définitions d’API utilisées pour écrire un connecteur personnalisé, accédez à Créer un connecteur personnalisé à partir d’une définition OpenAPI. Consultez également le didacticiel dans l’article Étendre une définition OpenAPI pour un connecteur personnalisé.

Fichier des propriétés d’API

Le fichier de propriétés de l’API contient des propriétés pour le connecteur personnalisé. Ces propriétés ne font pas partie de la définition de l’API. Il contient des informations comme la couleur de la personnalisation, les informations d’authentification, etc. Un fichier de propriétés de l’API typique ressemble à l'exemple suivant :

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

Vous trouverez ci-dessous plus d’informations sur chacune des propriétés :

properties : Conteneur des informations.
connectionParameters : Définit le paramètre de connexion pour le service.
iconBrandColor : couleur de personnalisation de l’icône en code hexadécimal HTML pour le connecteur personnalisé.
scriptOperations : une liste des opérations qui sont exécutées avec le fichier de script. Une liste scriptOperations vide indique que toutes les opérations sont exécutées avec le fichier de script.
capabilities : décrit les fonctionnalités du connecteur, par exemple : cloud uniquement, passerelle locale, etc.
policyTemplateInstances : Liste facultative de valeurs et d’instances de modèle de stratégie utilisées dans le connecteur personnalisé.

Fichier icône

Le fichier d’icône est une petite image représentant l’icône du connecteur personnalisé.

Fichier de script

Le script est un fichier de script CSX qui est déployé pour le connecteur personnalisé et exécuté pour chaque appel à un sous-ensemble des opérations du connecteur.

Fichier de paramètres

Au lieu de fournir les arguments dans la ligne de commande, un fichier settings.json peut être utilisé pour les spécifier. Un fichier settings.json typique ressemble à l'exemple suivant :

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

Dans le fichier de paramètres, les éléments suivants sont attendus. Si une option obligatoire est manquante, la console vous demandera de fournir les informations manquantes.

connectorId : Chaîne d’ID de connecteur pour le connecteur personnalisé. Ce paramètre est requis pour les opérations de téléchargement et de mise à jour, mais pas pour l'opération de création ou de validation. Un nouveau connecteur personnalisé avec le nouvel ID sera créé pour la commande create. Si vous devez mettre à jour un nouveau connecteur personnalisé à l’aide du même fichier de paramètres, vérifiez que ce dernier a bien été mis à jour avec le nouvel ID de connecteur à partir de l’opération de création.
environment : chaîne d’ID d’environnement pour le connecteur personnalisé. Ce paramètre est obligatoire pour toutes les opérations, à l'exception de l'opération de validation.
apiProperties : chemin d’accès au fichier apiProperties.json de propriétés de l’API. Il est requis pour l’opération de création et de mise à jour. Lorsque cette option est présente pendant le téléchargement, le fichier est téléchargé à l’emplacement donné, sinon il sera enregistré sous le nom apiProperties.json.
apiDefinition : chemin d’accès au fichier Swagger. Il est requis pour les opérations de création, de mise à jour et de validation. Lorsque cette option est présente pendant l'opération de téléchargement, le fichier est écrit à l’emplacement indiqué ; sinon il est enregistré sous le nom apiDefinition.swagger.json.
icon : chemin d’accès au fichier d’icône facultatif. Les opérations de création et de mise à jour utiliseront l'icône par défaut lorsque ce paramètre n'est pas spécifié. Lorsque cette option est présente pendant l'opération de téléchargement, le fichier est écrit à l’emplacement indiqué ; sinon il est enregistré sous le nom icon.png.
script : chemin d’accès au fichier de script facultatif. Les opérations de création et de mise à jour utiliseront uniquement la valeur à l'intérieur du paramètre spécifié. Lorsque cette option est présente pendant l'opération de téléchargement, le fichier est écrit à l’emplacement indiqué ; sinon il est enregistré sous le nom script.csx.
powerAppsUrl : URL de l'API pour Power Apps. Ce paramètre est facultatif et défini sur https://api.powerapps.com par défaut.
powerAppsApiVersion : version d'API à utiliser pour Power Apps. Ce paramètre est facultatif et défini sur 2016-11-01 par défaut.

Opérations de ligne de commande

Se connecter à Power Platform en exécutant :

paconn login

Cette commande vous demandera de vous connecter à l’aide du processus de connexion avec le code de l’appareil. Suivez l’invite de connexion. L'authentification du principe de service n'est pas prise en charge à ce stade.

Déconnexion

Déconnectez-vous en exécutant :

paconn logout

Télécharger les fichiers du connecteur personnalisé

Les fichiers du connecteur sont toujours téléchargés dans un sous-répertoire qui utilise l’ID du connecteur comme nom de répertoire. Lorsqu’un répertoire de destination est spécifié, le sous-répertoire est créé dans le répertoire spécifié. Dans le cas contraire, il est créé dans le répertoire actif. En plus des trois fichiers du connecteur, l’opération de téléchargement écrit également un quatrième fichier appelé settings.json qui contient les paramètres utilisés pour télécharger les fichiers.

Téléchargez les fichiers du connecteur personnalisé en exécutant :

paconn download

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

paconn download -s [Path to settings.json]

Lorsque l’ID de l’environnement ou du connecteur n’est pas indiqué, la commande demande le ou les arguments manquants. La commande génère l’emplacement de téléchargement du connecteur si le téléchargement réussit.

Tous les arguments peuvent également être spécifiés à l’aide d’un fichier 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.

Créer un connecteur personnalisé

Un nouveau connecteur personnalisé peut être créé à partir des fichiers de connecteurs en exécutant l'opération create. Créez un connecteur en exécutant :

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]

Lorsque l’environnement n’est pas spécifié, la commande vous invite à le faire. Toutefois, la définition de l’API et le fichier de propriétés de l’API doivent être fournis dans le cadre de l’argument de ligne de commande ou d’un fichier de paramètres. Le secret OAuth2 doit être fourni pour un connecteur utilisant OAuth2. En cas de réussite, la commande imprime l’ID de connecteur pour le connecteur personnalisé nouvellement créé. Si vous utilisez un fichier settings.json pour la commande create, veillez à le mettre à jour avec l’ID du nouveau connecteur avant de mettre à jour le nouveau connecteur.

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.

Mettre à jour un connecteur personnalisé existant

À l'instar de l'opération create, un connecteur personnalisé existant peut être mis à jour à l'aide de l'opération update. Mettez à jour un connecteur en exécutant :

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]

Lorsque l’ID de l’environnement ou du connecteur n’est pas indiqué, la commande demande le ou les arguments manquants. Toutefois, la définition de l’API et le fichier de propriétés de l’API doivent être fournis dans le cadre de l’argument de ligne de commande ou d’un fichier de paramètres. Le secret OAuth2 doit être fourni pour un connecteur utilisant OAuth2. En cas de réussite, la commande imprime l’ID de connecteur mis à jour. Si vous utilisez un fichier settings.json pour la commande de mise à jour, vérifiez que l’environnement et l’ID de connecteur indiqués sont corrects.

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.

Valider un JSON swagger

L'opération de validation prend un fichier swagger et vérifie s'il respecte toutes les règles recommandées. Validez un fichier swagger en exécutant :

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

paconn validate -s [Path to settings.json]

La commande imprime le message d'erreur, d'avertissement ou de réussite en fonction du résultat de la validation.

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.

Meilleures pratiques

Téléchargez tous les connecteurs personnalisés et utilisez git ou tout autre système de contrôle de code source pour enregistrer les fichiers. En cas de mise à jour incorrecte, redéployez le connecteur en réexécutant la commande de mise à jour avec le jeu de fichiers correct à partir du système de contrôle de code source.

Testez le connecteur personnalisé et le fichier de paramètres dans un environnement de test avant de les déployer dans l’environnement de production. Vérifiez toujours que l’environnement et l’ID de connecteur sont corrects.

Limitations

Le projet est limité à la création, à la mise à jour et au téléchargement d’un connecteur personnalisé dans l’environnement Power Automate et Power Apps. Lorsque aucun environnement n’est indiqué, seuls les environnements Power Automate sont proposés. Pour un connecteur non personnalisé, le fichier Swagger n’est pas retourné.

Propriété stackOwner et fichier apiProperties

Actuellement, il existe une limitation qui vous empêche de mettre à jour les artefacts de votre connecteur dans votre environnement à l'aide de Paconn lorsque la propriété stackOwner est présente dans votre dossier apiProperties.json. Pour contourner ce problème, créez deux versions de vos artefacts de connecteur : la première est la version soumise à la certification et contient la propriété stackOwner. La seconde omet la propriété stackOwner pour activer la mise à jour dans votre environnement. Nous nous efforçons de supprimer la limitation et mettrons à jour cette section une fois l'opération terminée.

Problèmes liés à la création de rapports et commentaires

Si vous rencontrez des bogues en utilisant l’outil, signalez un problème dans la section Issues (Problèmes) de notre référentiel GitHub.

Si vous pensez avoir trouvé une faille de sécurité qui correspond à la définition de Microsoft d’une faille de sécurité, envoyez un rapport au Centre de réponse aux problèmes de sécurité Microsoft. Pour plus d’informations, consultez Forum aux questions MSRC sur la création de rapports.

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plateforme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.

Partager via

Création d’un connecteur personnalisé avec CLI

Install

Répertoire et fichiers du connecteur personnalisé

Fichier (swagger) de définition de l’API

Fichier des propriétés d’API

Fichier icône

Fichier de script

Fichier de paramètres

Opérations de ligne de commande

Déconnexion

Télécharger les fichiers du connecteur personnalisé

Créer un connecteur personnalisé

Mettre à jour un connecteur personnalisé existant

Valider un JSON swagger

Meilleures pratiques

Limitations

Problèmes liés à la création de rapports et commentaires

Fournir des commentaires

Ressources supplémentaires

Partager via

Création d’un connecteur personnalisé avec CLI

Install

Répertoire et fichiers du connecteur personnalisé

Fichier (swagger) de définition de l’API

Fichier des propriétés d’API

Fichier icône

Fichier de script

Fichier de paramètres

Opérations de ligne de commande

Connexion

Déconnexion

Télécharger les fichiers du connecteur personnalisé

Créer un connecteur personnalisé

Mettre à jour un connecteur personnalisé existant

Valider un JSON swagger

Meilleures pratiques

Limitations

Problèmes liés à la création de rapports et commentaires

Fournir des commentaires

Ressources supplémentaires