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

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

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

Шаг 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" — компания-владелец или организация стека серверных служб, к которой подключается соединитель. Должно указываться в буквенно-цифровом формате.

Расположение файла: openapidefinition.json

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

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

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

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

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

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

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

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

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

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

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

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

  

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

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

• Убедитесь, что подключаемый модуль создан в соответствии с рекомендациями в разделе Создание подключаемых модулей ИИ для Microsoft Copilot (предварительная версия).
• Все отправленные подключаемые модули ИИ должны соответствовать стандартам, указанным в разделе 100.10 Недопустимое содержимое.
• Все подключаемые модули ИИ соответствуют рекомендациям по ответственному применению ИИ.
• Подключаемый модуль не должен создавать, содержать или предоставлять доступ к недопустимому, вредному или оскорбительному содержимому, созданному искусственным интеллектом (ИИ), в соответствии с существующими политиками коммерческой платформы, представленными в разделе 100.10 Недопустимое содержимое.

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

Вы отправляете в Microsoft набор файлов, представляющий собой генерацию решения с портала maker или Microsoft Copilot Studio. Чтобы упаковать файлы, следуйте инструкциям в этом разделе.

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

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

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

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

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

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

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

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

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

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

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

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

   

Примечание

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

1. Отправьте пакет в BLOB-объект хранилища и создайте URL-адрес SAS. Убедитесь, что ваш SAS URI действителен в течение как минимум 15 дней.
2. Отправьте пакет в Центр партнеров.

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

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

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

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

   • Запустите средство проверки решений (шаг 2 в разделе Упаковка пользовательского соединителя и его отправка на сертификацию).
   • Экспортируйте решение потока (шаг 5 в разделе Упаковка пользовательского соединителя и его отправка на сертификацию).
   • Создайте подключаемый модуль в Microsoft Copilot Studio и экспортируйте его как решение (шаг 2 в этой процедуре).

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

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

   

Примечание

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

1. Отправьте пакет в BLOB-объект хранилища и создайте URL-адрес SAS. Убедитесь, что ваш SAS URI действителен в течение как минимум 15 дней.
2. Отправьте пакет в Центр партнеров.

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

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

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

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

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

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

   • Запустите средство проверки решений в своем решении соединителя (шаг 2 в разделе Упаковка пользовательского соединителя и его отправка на сертификацию этой статьи).
   • Создайте подключаемый модуль в Copilot Studio и экспортируйте его как решение (шаг 3 в этой процедуре).
   • Создайте подключаемый модуль в Copilot Studio и экспортируйте его как решение (шаг 4 в этой процедуре).

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

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

   

Примечание

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

1. Отправьте пакет в BLOB-объект хранилища и создайте URL-адрес SAS. Убедитесь, что ваш SAS URI действителен в течение как минимум 15 дней.
2. Отправьте пакет в Центр партнеров.

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

• Проверенные издатели: Установите iconBrandColor на цвет вашего бренда в файле openapidefinition.
• Независимые издатели: Установите iconBrandColor на "#da3b01" в файле openapidefinition.
  

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

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

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

шаг 7: Проверка структуры пакета

Скрипт проверки пакета проверяет структуру пакета и помогает вам сгенерировать пакет в приемлемом формате для сертификации. Загрузите скрипт валидатора пакетов по этой ссылке: ConnectorPackageValidator.ps1.

Чтобы запустить скрипт, выполните следующие действия:

1. Откройте Windows PowerShell в режиме администратора.

   

2. Измените местоположение диска, введя cd /.

   В следующем примере используется C:\.

   

3. Перейдите по пути, куда вы скачали скрипт валидатора пакетов.

   Например, если путь C:\Users\user01\Downloads, введите cd .\Users\user01\Downloads\.

   

4. Установите политику выполнения на «без ограничений», введя следующую команду:

   Set-ExecutionPolicy -ExecutionPolicy Unrestricted

   

   Эта команда позволяет запускать PowerShell без каких-либо ограничений.

5. Подтвердите свой ввод, введя Y, что означает Да.

6. Выполните ConnectorPackageValidator.ps1, выполнив следующие шаги:

   1. Введите путь к zip-файлу, содержащему пакет соединителя.
   2. Укажите, включен ли подключаемый модуль ИИ.

   Как показано в следующем примере, первый аргумент — это допустимый путь к ZIP-файлу, содержащему пакет. Второй аргумент yes/y указывает, что подключаемый модуль ИИ включен, или no/n указывает, что он отключен.

   

   Если структура пакета правильная, отобразится следующее сообщение об успешном завершении:

   

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

   

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

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

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

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

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

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

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

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

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

• Ваш соединитель и/или подключаемый модуль соответствует всем стандартам, установленным в разделах Шаг 2. Выполните требования к отправке соединителей, Шаг 5. Выполните требования к отправке подключаемых модулей и Шаг 4. Добавьте метаданные.

• Для всех операций есть сводка, описание или информация о видимости.

• Вы протестировали свой пользовательский соединитель и/или подключаемый модуль, чтобы убедиться, что операции работают должным образом (не менее 10 успешных вызовов на операцию).

• Ошибки времени выполнения или проверки схемы не появляются в тестовом разделе мастера пользовательского соединителя.

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

• Процесс сертификации проверенных издателей
• Процесс сертификации для независимых издателей