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

Самостоятельное размещение портала разработчика для службы "Управление API"

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Стандартный | Премиум

В этом руководстве описывается, как самостоятельно разместить портал разработчика для службы "Управление API". Самостоятельное размещение — это один из нескольких вариантов расширения функциональности портала разработчика. Например, для одного экземпляра службы "Управление API" можно самостоятельно разместить несколько порталов, различающихся по функциям. При самостоятельном размещении портала вы сами отвечаете за его обновление.

Внимание

Рекомендуется самостоятельно размещать портал разработчика только в том случае, если необходимо изменить ядро базы кода портала разработчика. Для этого варианта требуется расширенная конфигурация, в том числе:

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

Примечание.

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

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

Необходимые компоненты

Чтобы настроить локальную среду разработки, необходимо следующее:

Шаг 1. Настройка локальной среды

Чтобы настроить локальную среду, необходимо клонировать репозиторий, перейти на последний выпуск портала разработчика и установить пакеты npm.

  1. Клонируйте репозиторий api-management-developer-portal с GitHub:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. Перейдите к локальной копии репозитория:

    cd api-management-developer-portal

  3. Получите для изменения последний выпуск портала.

    Перед выполнением приведенного ниже кода проверьте тег текущего выпуска в разделе "Releases" (Выпуски) репозитория и замените значение <current-release-tag> тегом последнего выпуска.

    git checkout <current-release-tag>

  4. Установите все доступные пакеты npm:

    npm install

Совет

Всегда используйте последний выпуск портала и поддерживайте свою вилку портала в актуальном состоянии. Разработчики программного обеспечения для повседневной разработки пользуются ветвью master этого репозитория. В ней содержатся нестабильные версии.

Шаг 2. Настройка файлов JSON, статического веб-сайта и параметров CORS

Для управления содержимым на портале разработчика необходимо использовать REST API службы "Управление API".

Файл config.design.json

Перейдите в папку src и откройте файл config.design.json.

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Задайте в файле следующие настройки:

  1. В значении свойства managementApiUrl замените строку <service-name> именем своего экземпляра службы "Управление API". Если вы задали личный домен (например, https://management.contoso.com), следует взамен указать его.

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. Создайте вручную маркер SAS, чтобы разрешить прямой доступ через REST API к экземпляру службы "Управление API".

  3. Скопируйте созданный маркер и вставьте его в качестве значения свойства managementApiAccessToken.

  4. В значении свойства backendUrl замените строку <service-name> именем своего экземпляра службы "Управление API". Если вы задали личный домен (например, https://portal.contoso.com), следует взамен указать его.

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

  5. Если вы хотите включить CAPTCHA на портале разработчика, задайте "useHipCaptcha": true. Обязательно настройте параметры CORS для серверной части портала разработчика.

  6. В integrationразделе googleFonts при необходимости задайте apiKey ключ API Google, который позволяет получить доступ к API разработчика веб-шрифтов. Этот ключ необходим только в том случае, если вы хотите добавить шрифты Google в раздел "Стили" редактора портала разработчика.

    Если у вас еще нет ключа, его можно настроить с помощью консоли Google Cloud. Выполните следующие действия:

    1. Откройте консоль Google Cloud.
    2. Проверьте, включен ли API разработчика веб-шрифтов. Если это не так, включите его.
    3. Выберите "Создать ключ API учетных>данных".
    4. В открывшемся диалоговом окне скопируйте созданный ключ и вставьте его в качестве значения apiKey в config.design.json файле.
    5. Нажмите кнопку "Изменить ключ API", чтобы открыть редактор ключей.
    6. В редакторе в разделе ограничений API выберите "Ограничить ключ". В раскрывающемся списке выберите API разработчика веб-шрифтов.
    7. Выберите Сохранить.

Файл config.publish.json

Перейдите в папку src и откройте файл config.publish.json.

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Задайте в файле следующие настройки:

  1. Скопируйте и вставьте значения managementApiUrl и managementApiAccessToken из предыдущего файла конфигурации.

  2. Если вы хотите включить CAPTCHA на портале разработчика, задайте "useHipCaptcha": true. Обязательно настройте параметры CORS для серверной части портала разработчика.

Файл config.runtime.json

Перейдите в папку src и откройте файл config.runtime.json.

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

Задайте в файле следующие настройки:

  1. Скопируйте и вставьте значение managementApiUrl из предыдущего файла конфигурации.

  2. В значении свойства backendUrl замените строку <service-name> именем своего экземпляра службы "Управление API". Если вы задали личный домен, следует взамен указать его (например, https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

Настройка статического веб-сайта

Настройте функцию размещения статического веб-сайта в учетной записи хранения, указав маршруты к страницам индекса и сообщения об ошибке:

  1. На портале Azure перейдите к своей учетной записи хранения и выберите Статический веб-сайт в меню слева.

  2. На странице Статический веб-сайт выберите Включено.

  3. В поле Имя документа индекса введите index.html.

  4. В поле Путь к документу с сообщением об ошибке введите 404/index.html.

  5. Выберите Сохранить.

Настройка параметров CORS для учетной записи хранения

Настройте параметры общего доступа к ресурсам независимо от источника (CORS) для учетной записи хранения.

  1. На портале Azure перейдите к своей учетной записи хранения и выберите CORS в меню слева.

  2. На вкладке Служба BLOB-объектов задайте следующие правила.

    Правило Значение
    Допустимые источники *
    Допустимые методы Выберите все HTTP-команды.
    Допустимые заголовки *
    Предоставляемые заголовки *
    Максимальный возраст 0

  3. Выберите Сохранить.

Настройка параметров CORS для серверной части портала разработчика

Настройте параметры CORS для серверной части портала разработчика, чтобы разрешить запросы, исходящие через локальный портал разработчика. Локальный портал разработчика использует внутреннюю конечную точку портала разработчика (задано в backendUrl в файлах конфигурации портала) для включения нескольких функций, в том числе:

Чтобы добавить параметры CORS:

  1. Перейдите к экземпляру Управления API на портале Azure и выберите Портал разработчика>Параметры портала в меню слева.
  2. На вкладке Конфигурация локального портала добавьте одно или несколько значений домена Origin. Например:
    • Домен, в котором размещен локальный портал, например https://www.contoso.com.
    • localhost для локальной разработки (если применимо), например http://localhost:8080 или https://localhost:8080.
  3. Выберите Сохранить.

Шаг 3. Запуск портала

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

Выполните следующую команду:

npm start

Через некоторое время автоматически откроется браузер по умолчанию с локальным экземпляром портала разработчика. Адрес по умолчанию — http://localhost:8080, но номер порта может измениться, если порт 8080 уже занят. Любые изменения в базе кода проекта активируют перестроение и обновление окна браузера.

Шаг 4. Правка в визуальном редакторе

Визуальный редактор используется для выполнения следующих задач:

  • настройка портала;
  • ввод содержимого;
  • упорядочивание структуры веб-сайта;
  • настройка внешнего вида веб-сайта.

См. статью "Руководство по доступу к порталу разработчика и его настройке. В ней приведены основные сведения о пользовательском интерфейсе администратора, а также рекомендуемые изменения в заданном по умолчанию содержимом. Сохраните все изменения в локальной среде и нажмите клавиши CTRL+C, чтобы закрыть ее.

Шаг 5. Локальная публикация

Данные портала создаются как строго типизированные объекты. Приведенная ниже команда преобразует их в статические файлы и помещает выходные данные в каталог ./dist/website:

npm run publish

Шаг 6. Отправка статических файлов в BLOB-объект

С помощью Azure CLI передайте локально созданные статические файлы в BLOB-объект и обеспечьте доступ к ним для посетителей:

  1. Откройте командную строку Windows, PowerShell или другую командную оболочку.

  2. Выполните следующую команду CLI Azure.

    Замените строку <account-connection-string> строкой подключения к своей учетной записи хранения. Эта строка доступна в разделе "Ключи доступа" вашей учетной записи хранения.

    az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>

Шаг 7. Переход на веб-сайт

Теперь ваш веб-сайт работает под именем узла, указанным в свойствах службы хранилища Azure (поле Основная конечная точка в разделе Статические веб-сайты).

Шаг 8. Изменение шаблонов уведомлений службы "Управление API"

Замените URL-адрес портала разработчика в шаблонах уведомлений службы "Управление API", чтобы он указывал на ваш самостоятельно размещенный портал. См. статью "Как настраивать уведомления и почтовые шаблоны в Azure API Management".

В частности, внесите следующие изменения в шаблоны по умолчанию.

Примечание.

Значения в подразделах с названием Новое содержимое ниже предполагают, что вы размещаете портал по адресу https://portal.contoso.com/.

Подтверждение изменения адреса электронной почты

Обновите URL-адрес портала разработчика в шаблоне уведомления Подтверждение изменения адреса электронной почты:

Исходное содержимое

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Обновлено

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Подтверждение новой учетной записи разработчика

Обновите URL-адрес портала разработчика в шаблоне уведомления Подтверждение новой учетной записи разработчика:

Исходное содержимое

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Обновлено

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Пригласить пользователя

Обновите URL-адрес портала разработчика в шаблоне Приглашение пользователя:

Исходное содержимое

<a href="$ConfirmUrl">$ConfirmUrl</a>

Обновлено

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Активирована новая подписка

Обновите URL-адрес портала разработчика в шаблоне Активирована новая подписка:

Исходное содержимое

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Обновлено

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Исходное содержимое

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Обновлено

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Исходное содержимое

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Обновлено

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Исходное содержимое

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Обновлено

<!--Remove the entire block of HTML code above.-->

Подтверждение изменения пароля

Обновите URL-адрес портала разработчика в шаблоне уведомления Подтверждение изменения пароля:

Исходное содержимое

<a href="$DevPortalUrl">$DevPortalUrl</a>

Обновлено

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Все шаблоны

Обновите URL-адрес портала разработчика во всех шаблонах, у которых есть ссылка в нижнем колонтитуле:

Исходное содержимое

<a href="$DevPortalUrl">$DevPortalUrl</a>

Обновлено

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

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

Со временем ваши бизнес-требования могут измениться. Однажды может оказаться, что управляемая версия портала разработчика для службы "Управление API" больше не отвечает вашим потребностям — например, в связи с новым требованием, для удовлетворения которого необходимо создать собственное мини-приложение, интегрированное со сторонним поставщиком данных. В отличие от управляемой версии, самостоятельно размещенная версия портала обеспечивает максимальную гибкость и расширяемость.

Процесс перехода

Перейти с управляемой версии на самостоятельно размещенную можно в том же экземпляре службы "Управление API". При этом сохраняются изменения, внесенные ранее в управляемую версию портала. Обязательно сделайте заранее резервную копию содержимого портала. Скрипт резервного копирования можно найти в папке scripts репозитория GitHub портала разработчика для службы "Управление API".

Процесс преобразования почти идентичен настройке самостоятельно размещенного портала общего назначения, показанной на предыдущих шагах. Есть лишь одно исключение: учетная запись хранения, указанная в файле config.design.json, должна совпадать с учетной записью хранения управляемой версии портала. Инструкции по получению URL-адреса SAS см. в статье "Руководство. Использование назначаемого системой управляемого удостоверения виртуальной машины Linux для доступа к службе хранилища Azure при помощи учетных данных SAS".

Совет

Рекомендуется указывать в файле config.publish.json отдельную учетную запись хранения. Такой подход обеспечивает более полный контроль и упрощает управление службой размещения портала.

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