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

Статья
04/24/2024

Программа командной строки paconn предназначена, чтобы помочь в разработке пользовательских соединителей Microsoft 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).

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

Пользовательский соединитель состоит из двух–четырех файлов: определение Swagger Open API, файл свойств API, необязательный значок для соединителя и необязательный файл сценария csharp. Эти файлы обычно находятся в каталоге с именем, соответствующим идентификатору соединителя.

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

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

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

Файл свойств 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: необязательный список экземпляров и значений шаблона политики, которые используются в пользовательском соединителе.

Файл значка

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

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

Сценарий — это файл сценария 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: путь к файлу apiProperties.json свойств API. Он требуется для операции создания и обновления. Если этот параметр присутствует во время скачивания, файл будет скачан в указанное расположение; в противном случае он будет сохранен как apiProperties.json.
apiDefinition: путь к файлу Swagger. Он требуется для операций создания, обновления и проверки. Если этот параметр присутствует во время операции скачивания, запись производится файл в указанном расположении; в противном случае он будет сохранен как 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 или любую другую систему управления версиями для сохранения файлов. В случае неправильного обновления снова разверните соединитель, повторно выполнив команду обновления с правильным набором файлов из системы управления версиями.

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

Ограничения

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

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

В настоящее время существует ограничение, которое не позволяет вам обновлять артефакты вашего соединителя в вашей среде с помощью Paconn, когда свойство stackOwner присутствует в вашем файле apiProperties.json. В качестве обходного пути создайте две версии артефактов соединителя: первая версия — это версия, отправленная на сертификацию и содержащая свойство stackOwner. Во второй свойство stackOwner опущено, чтобы разрешить обновление в вашей среде. Мы работаем над снятием этого ограничения и обновим этот раздел после завершения работы.

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

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

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

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

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

Поделиться через

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

Установка

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

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

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

Файл значка

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

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

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

Выход

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

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

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

Проверка JSON swagger

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

Ограничения

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

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

Дополнительные ресурсы

Поделиться через

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

Установка

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

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

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

Файл значка

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

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

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

Имя входа

Выход

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

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

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

Проверка JSON swagger

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

Ограничения

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

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

Дополнительные ресурсы