Partager via

Création d’un connecteur personnalisé avec CLI

L’outil de ligne de commande paconn est conçu pour faciliter la création de connecteurs personnalisés pour Copilot Studio et Power Platform.

Nonte

Install

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

  2. Exécutez le programme d’installation pour commencer l’installation et veillez à cocher la case Ajouter Python X.X à PATH.

  3. Assurez-vous que le chemin d’installation se trouve dans la variable PATH en exécutant :

    python --version

  4. Après l’installation de Python, installez paconn en exécutant :

    pip install paconn

    Si vous obtenez des erreurs indiquant 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 Open API/swagger
  • un fichier de propriétés de l’API
  • une icône facultative pour le connecteur
  • un fichier de script CSharp facultatif

Les fichiers se trouvent dans un répertoire qui utilise l’ID du connecteur comme nom du répertoire.

Parfois, le répertoire du connecteur personnalisé inclut un fichier settings.json. Bien que ce fichier ne fasse pas partie de la définition du connecteur, vous pouvez l’utiliser comme magasin d’arguments pour CLI.

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

Le fichier de définition de l’API décrit l’API pour le connecteur personnalisé à l’aide de la spécification OpenAPI. Il est également appelé fichier swagger. Pour plus d’informations sur la façon dont un fichier de définition d’API vous aide à créer 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 certaines propriétés du connecteur personnalisé qui ne font pas partie de la définition de l’API. Le fichier de propriétés de l’API contient des informations comme la couleur de la marque, 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"
        }
      }
    ]    
  }
}

Voici 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 : liste des opérations 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 : description des capacités du connecteur. Par exemple, passerelle cloud uniquement et sur site.

  • policyTemplateInstances : liste facultative de valeurs et d’instances de modèle de stratégie utilisées par 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 fichier de script Visual C# Script (CSX) 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 à cet exemple :

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

Attendez-vous à ce que ces éléments se trouvent dans le fichier de paramètres. Si une option est manquante mais obligatoire, la console vous invite à fournir les informations manquantes.

  • connectorId : Chaîne d’ID de connecteur pour le connecteur personnalisé. Les opérations télécharger et mettre à jour nécessitent le paramètre d’ID du connecteur, contrairement aux opérations créer et valider. La commande créer crée un connecteur personnalisé avec un nouvel ID. Si vous devez mettre à jour un connecteur personnalisé existant en utilisant le même fichier de paramètres, assurez-vous de mettre à jour le fichier de paramètres 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é. Toutes les opérations nécessitent ce paramètre, à l’exception de l’opération de validation.

  • apiProperties : chemin d’accès au fichier de propriétés de l’API. Les opérations créer et mettre à jour nécessitent le fichier de propriétés de l’API. Lorsque cette option est présente pendant le téléchargement, le fichier est téléchargé dans son emplacement ; sinon le fichier est enregistré en tant que apiProperties.json.

  • apiDefinition : chemin d’accès au fichier Swagger. Les opérations créer, mettre à jour et valider nécessitent le fichier de définitions de l’API. Lorsque cette option est présente pendant l’opération de téléchargement, le fichier est téléchargé dans son emplacement ; sinon le fichier est enregistré en tant que apiDefinition.swagger.json.

  • icon : chemin d’accès au fichier d’icône facultatif. Si ce paramètre n’est pas spécifié, les opérations créer et mettre à jour utilisent l’icône par défaut. Lorsque cette option est présente pendant l’opération de téléchargement, le fichier est téléchargé dans son emplacement ; sinon le fichier est enregistré en tant que icon.png.

  • script : chemin d’accès au fichier de script facultatif. Les opérations créer et mettre à jour n’utilisent que la valeur au sein du paramètre spécifié. Lorsque cette option est présente pendant l’opération de téléchargement, le fichier est téléchargé dans son emplacement ; sinon le fichier est enregistré en tant que 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

Connexion

Se connecter à Power Platform en exécutant :

paconn login

Cette commande vous demande de vous connecter à l’aide du processus de connexion par code d’appareil. Suivez l’invite de connexion. Il n’y a aucune prise en charge pour l’authentification du principal de service pour le moment.

Déconnexion

Déconnectez-vous en exécutant :

paconn logout

Télécharger les fichiers du connecteur personnalisé

Téléchargez toujours les fichiers du connecteur dans un sous-répertoire qui utilise l’ID du connecteur comme nom de répertoire. Lorsque vous spécifiez un répertoire de destination, cela crée un sous-répertoire dans le répertoire spécifié. Sinon, il est créé dans le répertoire actuel. 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

ou

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

ou

paconn download -s [Path to settings.json]

Lorsque l’ID de l’environnement ou du connecteur n’est pas indiqué, la commande vous invite à fournir les arguments manquants. La commande génère l’emplacement de téléchargement du connecteur s’il est téléchargé correctement.

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é

Vous pouvez créer un connecteur personnalisé à 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]

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]

Lorsque vous ne spécifiez pas l’environnement, la commande vous invite à le faire. Toutefois, vous devez fournir la définition de l’API et le fichier de propriétés de l’API dans le cadre de l’argument de ligne de commande ou dans un fichier de paramètres. Fournissez le secret OAuth2 pour un connecteur utilisant OAuth2. Une fois l’opération terminée correctement, la commande imprime l’ID du connecteur pour le connecteur personnalisé nouvellement créé. Si vous utilisez un fichier settings.json pour la commande de création, veillez à le mettre à jour avec l’ID du nouveau connecteur avant de mettre à jour le connecteur nouvellement créé.

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, vous devez mettre à jour un connecteur personnalisé existant à 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]

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]

Lorsque vous ne spécifiez pas l’ID de l’environnement ou du connecteur, la commande vous invite à fournir les arguments manquants. Toutefois, vous devez fournir la définition de l’API et le fichier de propriétés de l’API dans le cadre de l’argument de ligne de commande ou dans un fichier de paramètres. Fournissez le secret OAuth2 pour un connecteur utilisant OAuth2. Une fois l’opération terminée correctement, la commande imprime l’ID du connecteur mis à jour. Si vous utilisez un fichier settings.json pour la commande de mise à jour, assurez-vous de spécifier l’ID correct de l’environnement et du connecteur.

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]

or

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 les environnements Copilot Studio, Power Automate et Power Apps. Lorsqu’un environnement n’est pas spécifié, vous n’avez que la possibilité de sélectionner un environnement Power Automate. Pour un connecteur non personnalisé, le fichier Swagger n’est pas retourné.

Nonte

Propriété stackOwner et fichier de propriétés de l’API

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 le fichier de propriétés de votre API. Pour contourner ce problème, créez deux versions de vos artefacts de connecteur :

  • Créez une version contenant la propriété stackOwner et envoyez-la pour certification.
  • Créez une deuxième version qui omet stackOwner pour vous permettre d’effectuer des mises à jour dans votre propre 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 plate-forme 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.