Создание пользовательского соединителя с помощью интерфейса командной строки

Инструмент командной строки paconn предназначен, чтобы помочь в создании пользовательских соединителей для Copilot Studio и Power Platform.

Примечание.

Эта функциональность может быть еще не выпущена.
Чтобы ознакомиться с информацией о выпуске, см. статью Новые возможности и планируемые усовершенствования интеграции данных и Common Data Model.
Графики доставки и предполагаемые функциональные возможности могут изменяться или не входить в поставку (перейдите в раздел Политика Microsoft).

Установка

Установите Python 3.5+. Для этого перейдите по адресу [https://www.python.org/downloads](Python downloads). Выберите ссылку Скачать напротив любой версии Python выше Python 3.5. Перейдите по соответствующей ссылке на странице, если вы используете Linux и macOS X. Вы также можете выполнить установку, используя желаемый диспетчер пакетов соответствующей ОС.
Запустите установщик и обязательно установите флажок Добавить Python X.X в PATH.
Убедитесь, что путь установки находится в переменной PATH, выполнив команду:

python --version
После установки Python установите paconn, выполнив команду:

pip install paconn

Если вы получаете сообщение об ошибке Отказано в доступе, рассмотрите возможность использования параметра --user или запустите команду от имени администратора (Windows).

Каталог и файлы пользовательских соединителей

Пользовательский соединитель содержит от двух до четырех файлов:

определение Open API/Swagger
файл свойств API
Необязательный значок для соединителя
необязательный файл сценария csharp

Эти файлы находятся в каталоге с именем, соответствующим идентификатору соединителя.

Иногда каталог пользовательского соединителя включает файл settings.json. Хотя этот файл не является частью определения соединителя, вы можете использовать его как хранилище аргументов для CLI.

Файл определения API (swagger)

Файл определения API описывает API для пользовательского соединителя с использованием спецификации OpenAPI, также известной как файл Swagger. Дополнительные сведения о том, как файл определения API помогает создать пользовательский соединитель, см. в разделе Создание пользовательского соединителя из определения OpenAPI. Также просмотрите руководство в статье Расширение определения OpenAPI для пользовательского соединителя.

Файл свойств API

Файл свойств API содержит некоторые свойства пользовательского соединителя, которые не являются частью определения API. Файл свойств API содержит такие сведения, как фирменный цвет, информацию о проверке подлинности и т. д. Стандартный файл свойств API выглядит следующим образом:

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

Вот более подробная информация о каждом из свойств:

properties: контейнер для информации.
connectionParameters: определяет параметр подключения для службы.
iconBrandColor: фирменный цвет значка в шестнадцатеричном коде HTML для пользовательского соединителя.
scriptOperations: список операций, выполняемых с файлом сценария. Пустой список scriptOperations означает, что все операции выполняются с файлом сценария.
capabilities: описание возможностей соединителя. Например, облачный и локальный шлюз.
policyTemplateInstances: необязательный список экземпляров и значений шаблона политики, которые используются пользовательским соединителем.

Файл значка

Файл значка — это маленькое изображение, представляющее значок пользовательского соединителя.

Файл сценария

Файл сценария Visual C# Script (CSX) развертывается для пользовательского соединителя и выполняется для каждого вызова подмножества операций соединителя.

Файл параметров

Аргументы можно указать в файле settings.json, вместо того чтобы предоставлять их в командной строке. Стандартный файл settings.json выглядит как следующий пример:

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

Ожидайте эти пункты в файле настроек. Если параметр отсутствует, но требуется, консоль запрашивает недостающую информацию.

connectorId: строка идентификатора пользовательского соединителя. Для операций загрузки и обновления требуется параметр идентификатора соединителя, а для операций создания и проверки он не требуется. Команда создания создает новый пользовательский соединитель с новым идентификатором. Если вам нужно обновить существующий пользовательский соединитель, используя тот же файл параметров, обязательно обновите в файле параметров идентификатор нового соединителя из операции создания.
environment: строка идентификатора среды для пользовательского соединителя. Этот параметр требуется для всех операций, кроме операции проверки.
apiProperties: путь к файлу свойств API. Для операций создания и обновления требуется файл свойств API. Если этот параметр присутствует во время скачивания, файл загружается в его расположение; в противном случае файл сохраняется как apiProperties.json.
apiDefinition: путь к файлу Swagger. Для операций создания, обновления и проверки требуется файл определений API. Если этот параметр присутствует во время операции скачивания, файл загружается в его расположение; в противном случае файл сохраняется как apiDefinition.swagger.json.
icon: путь к необязательному файлу значка. Если спецификация для этого параметра отсутствует, операции создания и обновления используют значок по умолчанию. Если этот параметр присутствует во время операции скачивания, файл загружается в его расположение; в противном случае файл сохраняется как icon.png.
script: путь к необязательному файлу сценария. Операции создания и обновления используют только значение в указанном параметре. Если этот параметр присутствует во время операции скачивания, файл загружается в его расположение; в противном случае файл сохраняется как script.csx.
powerAppsUrl: URL-адрес API для Power Apps. Это необязательный параметр, для которого по умолчанию задано значение https://api.powerapps.com.
powerAppsApiVersion: версия API для использования для Power Apps. Это необязательный параметр, для которого по умолчанию задано значение 2016-11-01.

Операции командной строки

Войдите в Power Platform, выполнив:

paconn login

Эта команда предлагает войти, используя процесс входа в систему с кодом устройства. Следуйте указаниям в запросе для входа в систему. На данный момент поддержка проверки подлинности субъекта-службы отсутствует.

Выход

Выйдите из системы, запустив:

paconn logout

Скачивание файлов пользовательского соединителя

Обязательно загружайте файлы соединителя в подкаталог с идентификатором соединителя в качестве имени каталога. При указании каталога назначения при этом создается подкаталог в указанном каталоге. В противном случае он создается в текущем каталоге. В дополнение к трем файлам соединителя операция скачивания также записывает четвертый файл с именем settings.json, содержащий параметры, которые используются для скачивания файлов.

Скачайте файлы пользовательского соединителя, выполнив команду:

paconn download

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

paconn download -s [Path to settings.json]

Если идентификатор среды или соединителя не указан, команда запрашивает отсутствующие аргументы. Команда выводит расположение скачивания для соединителя, если его скачивание пройдет успешно.

Все аргументы также можно указать с помощью файла 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.

Создание нового пользовательского соединителя

Вы можете создать новый пользовательский соединитель из файлов соединителей, выполнив операцию create. Создайте соединитель, выполнив команду:

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]

Если вы не укажите среду, команда запросит ее. Однако вы должны предоставить определение API и файл свойств API как часть аргумента командной строки или файла параметров. Предоставьте секрет OAuth2 для соединителя, использующего OAuth2. При успешном выполнении операции создания команда печатает идентификатор для созданного пользовательского соединителя. Если вы используете файл 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.
   --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.

Обновление существующего пользовательского соединителя

Как и в случае операции create, вы можете обновить существующий пользовательский соединитель с помощью операции update. Обновите соединитель, выполнив команду:

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]

Если вы не указали идентификатор среды или соединителя, команда запрашивает отсутствующие аргументы. Однако вы должны предоставить определение API и файл свойств API как часть аргумента командной строки или файла параметров. Предоставьте секрет OAuth2 для соединителя, использующего OAuth2. В случае успешного завершения команда выводит обновленный идентификатор соединителя. Если вы используете файл 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.
   --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.

Проверка JSON swagger

Операция проверки берет файл Swagger и проверяет, соответствует ли он всем рекомендуемым правилам. Проверьте файл Swagger, выполнив:

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

paconn validate -s [Path to settings.json]

Команда печатает сообщение об ошибке, предупреждении или успехе в зависимости от результата проверки.

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.

Лучшие методики

Скачайте все пользовательские соединители и используйте git или любую другую систему управления версиями для сохранения файлов. В случае неправильного обновления снова разверните соединитель, повторно выполнив команду обновления с правильным набором файлов из системы управления версиями.

Прежде чем выполнять развертывание в рабочей среде, проверьте пользовательский соединитель и файл параметров в тестовой среде. Всегда тщательно проверяйте, правильно ли указан идентификатор среды и соединителя.

Ограничения

Проект ограничен созданием, обновлением и скачиванием пользовательского соединителя в средах Copilot Studio, Power Automate и Power Apps. Если среда не указана, вы можете выбрать только среду Power Automate. Файл Swagger не возвращается при использовании непользовательского соединителя.

Примечание.

Свойство stackOwner и файл свойств API

В настоящее время существует ограничение, которое не позволяет вам обновлять артефакты вашего соединителя в вашей среде с помощью Paconn, когда свойство stackOwner присутствует в вашем файле свойств API. Чтобы обойти эту проблему, создайте две версии артефактов соединителя:

Создайте одну версию, содержащую свойство stackOwner, и отправьте ее на сертификацию.
Создайте вторую версию, в которой отсутствует stackOwner, чтобы можно было вносить обновления в собственной среде.

Мы работаем над снятием этого ограничения и обновим этот раздел после завершения работы.

Сообщение о проблемах и отзывы

При возникновении каких-либо ошибок в программе сообщите об этом в разделе проблем репозитория GitHub.

Если вы считаете, что обнаружили уязвимость безопасности, которая соответствует определению уязвимости безопасности корпорации Microsoft, отправьте сообщение в MSRC. Дополнительные сведения можно найти на странице Рекомендации по отправке сообщения о проблеме.

Предоставление отзыва

Мы очень ценим отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, выберите пункт Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.

Last updated on 2025-05-28