Самохостинг портала разработчиков системы управления API

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

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

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

Предпосылки

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

• Экземпляр службы управления API. Если у вас его нет, см. Быстрый старт — Создание экземпляра службы управления API Azure.
• Учетная запись хранения Azure с включенной функцией статических веб-сайтов . См . статью "Создание учетной записи хранения".
• Git на вашем компьютере. Установите его, следуя этому руководству по Git.
• Node.js (LTS версия v10.15.0 или более поздняя) и npm на вашем устройстве. См. статью "Скачивание и установка Node.js и npm".
• Azure CLI. Выполните действия по установке Azure CLI.

Шаг 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. Ознакомьтесь с последним выпуском портала.

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

   git checkout <current-release-tag>
   

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

   npm install
   

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

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

файл config.design.json

Перейдите в папку srcconfig.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

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

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

Настройте файл:

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

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

файл config.runtime.json

Перейдите в папку srcconfig.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 файлах конфигурации портала) для включения нескольких функций, в том числе:

• Проверка CAPTCHA
• Авторизация OAuth 2.0 в тестовой консоли
• Делегирование проверки подлинности пользователей и подписки на продукт

Чтобы добавить параметры CORS, выполните следующие действия.

1. Перейдите к вашему экземпляру службы "Управление API" на портале Azure и выберите Портал разработчика>Параметры портала в меню слева.
2. На вкладке конфигурации локального портала добавьте одно или несколько значений домена Источника . Например:
   • Домен, в котором размещен автономный портал, например 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. Выполните следующую команду Azure CLI.

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

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

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

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

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

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

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

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

Обновите 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репозитория портала разработчика службы управления API GitHub.

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

Связанный контент

• Узнайте о альтернативных подходах к самостоятельному размещению