Créez un connecteur personnalisé avec CLI

L’outil paconn en ligne de commande vous aide à créer des connecteurs personnalisés pour Copilot Studio et Power Platform.

Installer Python et paconn

1. Installez Python 3.5 ou version ultérieure à partir de [https://www.python.org/downloads](téléchargements Python). Sélectionnez le lien Télécharger pour n’importe quelle version de Python supérieure à Python 3.5. Pour Linux et macOS, suivez le lien approprié sur la page. Vous pouvez également installer Python à 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 cochez la case Ajouter Python X.X à PATH.

3. Vérifiez que le chemin d’installation se trouve dans la variable PATH en exécutant :

   python --version

4. Une fois Python installé, 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 ou Swagger
• un fichier de propriétés de l’API
• une icône facultative pour le connecteur
• un fichier de script C# facultatif

Vous trouvez les fichiers dans un répertoire qui utilise l’ID du connecteur comme nom.

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 l’interface CLI.

Fichier de définition d’API (Swagger)

Le fichier de définition d’API décrit l’API pour le connecteur personnalisé à l’aide de la spécification OpenAPI. Cette spécification est également appelée 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é, consultez Créer un connecteur personnalisé à partir d’une définition OpenAPI. Consultez également le tutoriel dans l’article Étendre une définition OpenAPI pour un connecteur personnalisé.

Fichier des propriétés de l’API

Le fichier de propriétés de l’API contient des propriétés pour le connecteur personnalisé qui ne font pas partie de la définition de l’API. Il inclut des informations telles que la couleur de la marque et les informations d’authentification. 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 chaque propriété :

• properties : Le conteneur pour les informations.

• connectionParameters : Définit le paramètre de connexion pour le service.

• iconBrandColor : couleur de marque 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 vide scriptOperations indique que toutes les opérations s’exécutent avec le fichier de script.

• capabilities: Description des fonctionnalités du connecteur, telles que la passerelle cloud uniquement et la passerelle locale.

• policyTemplateInstances : liste facultative d’instances de modèle de stratégie et de leurs valeurs utilisées par le connecteur personnalisé.

Fichier d’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, utilisez un fichier settings.json 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 de téléchargement et de mise à jour nécessitent le paramètre ID du connecteur, tandis que les opérations de création et de validation ne le font pas. La commande create crée un connecteur personnalisé avec un nouvel ID. Si vous devez mettre à jour un connecteur personnalisé existant à l’aide du même fichier de paramètres, veillez à 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é à son emplacement d’origine ; 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é à son emplacement d’origine ; sinon, le fichier est enregistré en tant que apiDefinition.swagger.json.

• icon : chemin d’accès au fichier d’icône facultatif. S’il n’existe aucune spécification pour ce paramètre, les opérations de création et de mise à 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é à son emplacement d’origine ; 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 dans le paramètre spécifié. Lorsque cette option est présente pendant l’opération de téléchargement, le fichier est téléchargé à 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

Connectez-vous

Connectez-vous à Power Platform en exécutant :

paconn login

Cette commande vous invite à vous connecter à l’aide du processus d’authentification du code de l’appareil. Suivez les instructions d’authentification. Cette commande ne prend pas en charge l’authentification du principal de service.

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, ce répertoire devient le parent du nouveau sous-répertoire. Si vous ne spécifiez pas de répertoire de destination, le sous-répertoire est créé dans le répertoire actif. Outre les trois fichiers de connecteur, l’opération de téléchargement crée 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]

Si vous ne spécifiez pas l’environnement ou l’ID du connecteur, la commande vous invite à entrer les arguments manquants. Si le téléchargement réussit, la commande affiche l’emplacement de téléchargement du connecteur.

Vous pouvez également spécifier tous les arguments à 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 du connecteur 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]

ou

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]

ou

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 demande quel environnement utiliser. 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 à l’aide d’OAuth2. Une fois l’opération terminée correctement, la commande imprime l’ID du connecteur personnalisé nouvellement créé. Si vous utilisez un settings.json fichier pour la commande create, veillez à le mettre à jour avec le nouvel ID de 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

Comme l’opération create , vous pouvez 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]

ou

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]

ou

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 à l’aide d’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, veillez à spécifier l’environnement et l’ID de connecteur appropriés.

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 suit toutes les règles recommandées. Validez un fichier swagger en exécutant :

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

ou

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.

Meilleure pratique

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

L’interface paconn CLI est limitée à 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. Lorsque vous ne spécifiez pas d'environnement, vous avez uniquement la possibilité de sélectionner un environnement Power Automate. Pour un connecteur non personnalisé, le fichier Swagger n’est pas retourné.

Signalement de problèmes 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 que vous avez trouvé une vulnérabilité de sécurité qui répond à la définition de Microsoft d'une vulnérabilité de sécurité, envoyez un rapport à MSRC. Pour plus d’informations, consultez les questions fréquentes de MSRC sur le signalement.

Donner votre avis

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.