Подготовьте файлы соединителя для агента и Power Platform для сертификации

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

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

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

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

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

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

Примеры

• Хорошие заголовки соединителя: Azure Sentinel*, *Office 365 Outlook
• Плохое название соединителя: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Убедитесь, что openapidefinition.json находится в файле 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, если вы хотите локализовать значения этих строк. Строки в форме CaMel (например, minimizeHighways или MinimizeHighways) обычно считаются непереводимыми.

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

Средство проверки решений — это механизм для проведения статического анализа, чтобы убедиться, что соединитель соответствует стандартам сертификации Microsoft. Добавьте соединитель в решение в Power Automate или Power Apps, а затем следуйте инструкциям в Validate a custom connector with solution checker для запуска средства проверки решений.

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

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

Убедитесь, что действия соединителя соответствуют следующим рекомендациям:

• Руководство по ответственному использованию искусственного интеллекта определяет, каким требованиям должны соответствовать все соединители, готовые для агентов.
• В разделе 100.10 Недопустимое содержимое условий использования Microsoft Commercial Marketplace описываются стандарты, которым должны соответствовать все соединители, готовые к использованию агентами. Действия соединителя не должны создавать или содержать неприемлемый, вредоносный или оскорбительный контент, сгенерированный ИИ, а также предоставлять доступ к такому контенту.
• Используйте соединители в Copilot Studio, чтобы узнать, что соединители — это инструменты, расширяющие функциональные возможности Microsoft Copilot Studio.

Шаг 4. Подготовка соединителя и связанных артефактов

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

Упакуйте файлы соединителя

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

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

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

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

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

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

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

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

   

Заметка

Имена папок и файлов за пределами решения приведены только в иллюстративных целях — вы можете задавать их на свое усмотрение. Тем не менее манипулировать файлами внутри решения не следует.

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

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

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

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

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

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

Шаг 5: Проверка структуры пакета

Скрипт проверки пакета проверяет структуру пакета и помогает создать пакет в приемлемом формате для сертификации. Скачайте скрипт проверки пакета 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, введя zip-файл путь, содержащий пакет соединителя.

   Как показано в следующем примере, первый аргумент — это допустимый путь к ZIP-файлу, содержащему пакет.

   

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

   

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

   

Шаг 6. Отправка соединителя для сертификации

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

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

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

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

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

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

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

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

• Ваш настраиваемый соединитель соответствует всем стандартам, установленным в шаге 1: Соответствие требованиям для передачи соединителей и шаге 3: Соответствие требованиям для действий соединителя.

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

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

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

По вопросам, связанным с сертификацией

Вам необходимо иметь Microsoft Teams, чтобы присоединиться к собранию в рабочие часы. Если вам нужен доступ, просмотрите параметры в Microsoft Teams.

Присоединяйтесь к Собранию в рабочее время каждый вторник с 15:30 до 16:30 по UTC (всемирное координированное время).

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

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