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

Подготовка файлов соединителя и подключаемого модуля Power Platform к сертификации

  • Статья

Этот процесс предназначен как для проверенных, так и для независимых издателей.

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

Примечание

В этой статье представлена информация для сертификации пользовательских соединителей в Azure Logic Apps, Power Automate и Power Apps, а также подключаемых модулей в Copilot. Перед выполнением шагов в этой статье прочтите статью Сертификация соединителя и/или подключаемого модуля.

Шаг 1. Зарегистрируйте соединитель и/или подключаемый модуль (применимо только для независимых издателей)

Этот раздел не относится к проверенным издателям.

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

В течение двух рабочих дней вы получите сообщение электронной почты от контактного лица Майкрософт, который:

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

Шаг 2. Выполните требования к отправке соединителей

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

Дайте название соединителю

Название должно удовлетворять следующим требованиям.

  • Должно существовать и быть написано на английском языке.
  • Должно быть уникальным и отличимым от любого существующего названия соединителя и/или подключаемого модуля.
  • Должно быть названием вашего продукта или организации.
  • Должно следовать существующим шаблонам именования для сертифицированного соединителя и/или подключаемого модуля. В случае независимых издателей имя соединителя должно соответствовать шаблону Connector and/or plugin Name (Independent Publisher).
  • Длина имени не может превышать 30 символов.
  • Не должен содержать слова API, Connector или любые названия наших продуктов Power Platform (например, Power Apps).
  • Не может заканчиваться не буквенно-цифровым символом, включая возврат строки, новую строку или пробел.

Примеры

  • Хорошие названия соединителей и/или подключаемых модулей: Azure Sentinel*, *Office 365 Outlook
  • Плохие названия соединителей и/или подключаемых модулей: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Напишите описание своего соединителя

Описание должно удовлетворять следующим требованиям.

  • Должно существовать и быть написано на английском языке.
  • Не должно содержать грамматические и орфографические ошибки.
  • Должен кратко описывать основное назначение и ценность вашего соединителя.
  • Не может быть короче 30 или длиннее 500 символов.
  • Не может содержать названия продуктов Power Platform (например, "Power Apps").

Разработайте значок для своего соединителя (применимо только для проверенных издателей)

Этот раздел не относится к независимым издателям.

  • Создайте логотип размером 1:1 в диапазоне от 100 x 100 до 230 x 230 пикселей (без закругленных краев).
  • Используйте непрозрачный фон не белого цвета (#ffffff), отличный от цвета по умолчанию (#007ee5), который соответствует указанному вами цвету фона значка.
  • Значок должен быть уникальным для любого другого значка сертифицированного соединителя.
  • Отправьте логотип в формате PNG: <icon>.png.
  • Установите размеры логотипа ниже 70 % по высоте и ширине изображения с однородным фоном.
  • Убедитесь, что фирменный цвет является допустимым шестнадцатеричным цветом. Он не должен быть белым (#ffffff) или цветом по умолчанию (#007ee5).

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

Сводки и описания должны удовлетворять следующим требованиям.

  • Должно существовать и быть написано на английском языке.
  • Не должно содержать грамматические и орфографические ошибки.
  • Сводки операций и параметров должны быть фразами длиной 80 символов или короче и содержать только буквенно-цифровые символы или круглые скобки.
  • Описания операций и параметров должны быть полными, описательными предложениями и заканчиваться знаками препинания.
  • Не может содержать названия продуктов Microsoft Power Platform (например, "Power Apps").

Определите точные отклики на операции

Отклики на операции должны удовлетворять следующим требованиям.

  • Определяйте отклики на операции с точной схемой только с ожидаемыми откликами.
  • Не используйте ответы по умолчанию с точным определением схемы.
  • Предоставьте допустимые определения схемы ответа для всех операций в Swagger.
  • Пустые схемы ответа не допускаются, за исключением особых случаев, когда схема ответа является динамической. Это означает, что в выходных данных не отображается динамический контент, и разработчики должны использовать JSON для анализа ответа.
  • Пустые операции не допускаются.
  • Удалите пустые свойства, если они не требуются.

Проверка свойств Swagger

Свойства должны удовлетворять следующим требованиям.

  • Убедитесь, что "openapidefinition" находится в файле JSON правильного формата.
  • Убедитесь, что определение Swagger соответствует стандарту OpenAPI 2.0 и расширенному стандарту соединителей.

Проверка параметров подключения

Параметры должны удовлетворять следующим требованиям.

  • Убедитесь, что свойство обновлено соответствующими значениями для "UIDefinition" (отображаемое имя, описание).

  • Если в параметре подключения используется обычная проверка подлинности, убедитесь, что JSON имеет правильный формат, как показано в следующем примере.

    {
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Если в параметре подключения используется APIKey для проверки подлинности, убедитесь, что JSON имеет правильный формат, как показано в следующем примере.

    {
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Если в параметре подключения используется универсальный протокол OAuth для проверки подлинности, убедитесь, что JSON имеет правильный формат, как показано в следующем примере.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

  • Если в параметре вашего соединения указан поставщик удостоверений OAuth2, убедитесь, что этот поставщик удостоверений входит в список поддерживаемых поставщиков OAuth2. Ниже приведен пример поставщика удостоверений OAuth2 в GitHub:

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

  • Если в параметре подключения в качестве механизма проверки подлинности используется Microsoft Entra ID, убедитесь, что JSON имеет правильный формат, как показано в следующем примере.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

Создавайте качественные строки на английском языке

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

  • Чтобы убедиться, что все значения строк не содержат опечаток, выполните программу проверки орфографии. Если есть какая-либо неполная строка на английском языке, результат перевода является неполным или неверным в контексте.

  • Убедитесь, что предложение составлено полностью. Если предложение не закончено, это также может привести к снижению качества перевода.

  • Убедитесь, что смысл предложения ясен. Если значение предложения неоднозначно, это также может привести к снижению качества или неправильному переводу.

  • Убедитесь, что сводки, x-ms-summaries и описания грамматически правильны. Не копируйте и не вставляйте их. Чтобы узнать, как они отображаются в продукте, прочтите Руководство по использованию строк соединителя.

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

  • Если вы используете сокращения, обязательно пишите их с заглавной буквы, чтобы было понятно. Это снижает вероятность того, что его ошибочно примут за опечатку.

  • Строки в форме CaMel (например, minimizeHighways или MinimizeHighways) обычно считаются непереводимыми. Если вы хотите локализовать строковое значение, вы должны исправить строку формы CaMel.

Шаг 3: Использование средства проверки решений для проверки соединителя

Средство проверки решений — это механизм проведения статического анализа, позволяющий убедиться, что ваш соединитель соответствует стандартам, требуемым Microsoft для сертификации. Добавьте соединитель в решение в Power Automate или Power Apps и выполните проверку решение, следуя инструкциям в разделе Проверка пользовательского соединителя с помощью средства проверки решения.

Посмотрите это видео, чтобы узнать, как выполнить проверку решения!

Шаг 4. Добавьте метаданные

Артефакты (файлы) соединителя должны содержать конкретные метаданные, описывающие соединитель и его конечную службу. Информация, представленная в метаданных, опубликована в нашей документации по соединителю и доступна всем пользователям. Не предоставляйте какую-либо личную или конфиденциальную информацию и сообщите нам через контактное лицо в Microsoft, если возникнут какие-либо проблемы с предоставлением нам этой информации. Чтобы узнать, как метаданные документируются, посетите любую из страниц документации по соединителю в разделе Справочное руководство по соединителям.

Шаг. 4a. Свойства publisher и stackOwner

  • "publisher" — это название вашей компании или организации. Укажите полное название компании (например, "Contoso Corporation"). Должно указываться в буквенно-цифровом формате.
  • "stackOwner" — компания-владелец или организация стека серверных служб, к которой подключается соединитель. Должно указываться в буквенно-цифровом формате.
Издатель Описание Пример
Проверено Издатель и stackOwner являются одними и теми же, если только независимый поставщик программного обеспечения не создает соединитель от имени stackOwner. "publisher": "Tesla",
"stackOwner": "Tesla"
Независимый Вы должны указать владельца стека и владельца издателя. "publisher": "Nirmal Kumar",
"stackOwner": "ITGlue"

Расположение файла: apiProperties.json
Чтобы узнать больше, прочтите Файл свойств API.

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

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

Шаг 4c.Фрагменты примера кода

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

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

Примечание

В настоящее время существует ограничение на использование свойства stackOwner и инструмента интерфейса командной строки Paconn. Дополнительные сведения см. в разделе Ограничения в файле README.

Шаг 4d. Форматирование файла JSON и ограничения

  • Убедитесь, что ваши свойства правильно настроены.

  • Вставьте свой JSON в Visual Studio Code. Не стесняйтесь использовать расширения, такие как средства проверки орфографии, и подключаемые модули, такие как подключаемые модули JSON.

  • Файлы Swagger не должны превышать 1 МБ.

    • Подумайте о конструкции вашего соединителя, прежде чем приступить к его созданию. Оцените, следует ли разбить разъем на два (2) или более соединителя.
    • Большие файлы swagger могут вызвать задержку при использовании соединителя.

    Например, на платформе есть три (3) разных соединителя HubSpot.

    Снимок экрана с папками для трех соединителей HubSpot.

Шаг 4e. Проверка файлов пользовательских соединителей

Запустите paconn validate --api-def [Location of apiDefinition.swagger.json]. Это средство проверяет определение соединителя и информирует обо всех ошибках, которые необходимо исправить перед отправкой.

Если в качестве типа проверки подлинности соединитель использует OAuth, добавьте эти разрешенные URL-адреса перенаправления в приложение:

  • https://global.consent.azure-apim.net/redirect/{apiname}

  • https://global-test.consent.azure-apim.net/redirect/{apiname}

Шаг 5. Выполните требования к отправке подключаемых модулей

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

Шаг 6. Подготовьте артефакты соединителя и/или подключаемого модуля

Примечание

  • Перед сертификацией убедитесь, что вы следовали спецификациям и проверили качество соединителя и/или подключаемого модуля. Несоблюдение этих условий приведет к задержкам в сертификации, так как вам будет предложено внести изменения.
  • Укажите производственную версию URL-адреса узла. URL-адреса промежуточного этапа, разработки и тестирования узла не разрешены.

В Майкрософт нужно отправить набор файлов, загруженный с помощью интерфейса командной строки (CLI), предоставляемого Майкрософт. Этот инструмент проверяет ваш соединитель на наличие неисправных ошибок.

Чтобы начать, выполните эти действия:

  1. Установите инструмент Microsoft Power Platform Connectors CLI, следуя инструкциям по установке.

  2. Войдите в Microsoft Power Platform , выполнив в командной строке команду paconn login. Следуйте инструкциям по входу в рамках процесса с использованием кода устройства от Майкрософт.

  3. После проверки подлинности загрузите файлы пользовательского соединителя:

    • Запустите paconn download. Выберите среду, в которой находится пользовательский соединитель. Для этого укажите его номер в командной строке, а затем выберите имя этого соединителя.

    Инструмент загрузит артефакты вашего соединителя и/или подключаемого модуля в виде папки в папку файловой системы, в которой вы запустили paconn. В зависимости от типа издателя вы видите различные артефакты:

Руководство по упаковке соединителей и подключаемых модулей

Процедуры, описанные в этом разделе, помогут вам разобраться в различных сценариях упаковки. Используйте первый сценарий, если вы хотите упаковать только пользовательский соединитель. Используйте второй сценарий, если вы хотите упаковать пользовательский соединитель и подключаемые модули. Используйте последний сценарий, если вы хотите упаковать существующий соединитель и подключаемые модули.

Упаковка пользовательского соединителя и его отправка на сертификацию

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

  2. Запустите средство проверки решений в решении соединителя на шаге 1.

  3. Экспортируйте решение соединителя.

  4. Создайте поток (тестирование) с помощью нового созданного пользовательского соединителя и добавьте поток в решение.

  5. Экспортируйте решение потока.

  6. Создайте пакет с решениями из шагов 3 и 5.

  7. Создайте файл intro.md.

  8. Создайте окончательный пакет в виде ZIP-файла в следующем формате:

    Снимок экрана папок и файлов в ZIP-файле для сертифицированного соединителя, подлежащего сертификации.

  9. Отправьте пакет в BLOB-объект хранилища и создайте URL-адрес SAS.

  10. Отправьте пакет в Центр партнеров.

Упаковка пользовательского соединителя и подключаемого модуля для сертификации

  1. Выполните шаги с 1 по 5 в разделе Упаковка пользовательского соединителя и его отправка на сертификацию этой статьи.

  2. Создайте подключаемый модуль на портале Microsoft Copilot Studio и экспортируйте его как решение.

  3. Создайте пакет из следующего:

  4. Создайте файл intro.md.

  5. Создайте окончательный пакет в виде ZIP-файла в следующем формате.

    Снимок экрана папок и файлов в ZIP-файле для сертифицированного соединителя и подключаемого модуля, подлежащих сертификации.

Упаковка существующего сертифицированного соединителя и подключаемого модуля для сертификации

  1. Создайте решение в Power Automate и добавьте уже сертифицированный соединитель в него.

  2. Выполните шаги с 2 по 4 в разделе Упаковка пользовательского соединителя и его отправка на сертификацию этой статьи.

  3. Создайте подключаемый модуль в Copilot Studio и экспортируйте его как решение.

  4. Экспортируйте подключаемый модуль как решение.

  5. Создайте пакет из следующего:

  6. Создайте файл intro.md.

  7. Создайте окончательный пакет в виде ZIP-файла в следующем формате.

    Снимок экрана папок и файлов в ZIP-файле для существующего сертифицированного соединителя и подключаемого модуля, подлежащих сертификации.

Как проверенные, так и независимые издатели загружают apiProperties.json в своих артефактах. Вам нужно установить IconBrandColor в этом файле.

  • Проверенные издатели: установите для iconBrandColor ваш фирменный цвет в файле apiProperties.
  • Независимые издатели: установите для iconBrandColor "#da3b01" в файле apiProperties.
    Снимок экрана ярко-оранжевого значка (da3b01).

Создание артефакта intro.md

Файл intro.md необходим как для независимых, так и для проверенных издателей. Файл intro.md необходимо создать, чтобы задокументировать функции и возможности вашего соединителя. Чтобы получить пример документации, которую нужно включить, перейдите в пример Readme.md. Чтобы узнать о написании файла intro.md, посмотрите другие файлы intro.md (также называемые файлы Readme.md) в нашем репозитории GitHub.

Если вы являетесь независимым издателем и ваш соединитель использует OAuth, обязательно включите инструкции по получению учетных данных.

Совет

Известные проблемы и ограничения — это отличный раздел, который нужно поддерживать, чтобы держать ваших пользователей в курсе последних событий.

Шаг 7. Отправьте соединитель и/или подключаемый модуль на сертификацию

В процессе отправки вы отправите открытый код своего соединителя и/или подключаемого модуля в наш репозиторий соединителей Microsoft Power Platform.

  1. (Для независимых издателей) Чтобы отправить пакет в Майкрософт на сертификацию, следуйте инструкциям в разделе Процесс сертификации для независимых издателей.

  2. (Для проверенных издателей) Чтобы отправить пакет в Майкрософт на сертификацию в Центр партнеров, следуйте инструкциям в разделе Процесс сертификации проверенных издателей.

    Если вы являетесь проверенным издателем, вам необходимо отправить файл script.csx, если вы используете собственный код.

    Если ваш соединитель поддерживает OAuth, отправьте идентификатор клиента и секрет в Центр партнеров. Кроме того, получите имя API из запроса на отправку соединителя, чтобы обновить приложение.

    В рамках отправки Майкрософт сертифицирует ваш соединитель и/или подключаемый модуль. Если вам нужно устранить ошибки Swagger, перейдите в Исправление ошибок средства проверки Swagger.

Контрольный список перед отправкой

Прежде чем перейти к Отправьте соединитель на сертификацию Microsoft, обеспечьте следующее:

Совет

  • Создайте видеоролики YouTube, блоги или другой контент, чтобы делиться примерами или снимками экрана о том, как начать работу с вашим соединителем и/или подключаемым модулем.
  • Включите ссылки в файл intro.md, чтобы мы могли добавить его в наши документы.
  • Добавьте всплывающие подсказки в ваш файл Swagger, чтобы помочь вашим пользователям добиться большего успеха.

Следующий шаг