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

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

В этом руководстве описывается, как самостоятельно разместить портал разработчика службы управления API. Самостоятельное размещение — это один из нескольких вариантов расширения функциональности портала разработчика. Например, можно самостоятельно разместить несколько порталов для экземпляра службы управления API с различными функциями. При самостоятельном размещении портала вы становитесь его обслуживателем, и вы несете ответственность за его обновления. На портале разработчика требуется REST 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. Ознакомьтесь с последним выпуском портала.

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

    git checkout <current-release-tag>

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

    npm install

Подсказка

Всегда используйте последнюю версию портала и поддерживайте вашу разветвлённую версию портала up-toв актуальном состоянии. Команда разработчиков по управлению API использует master ветвь этого репозитория для ежедневных целей разработки. Она имеет неустойчивые версии программного обеспечения.

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

файл config.design.json

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

В поле subscriptionId, а также в resourceGroupName и serviceName введите значения для подписки, группы ресурсов и имени экземпляра управления API. I

Необязательные параметры в config.design.json

При необходимости настройте следующие параметры в config.design.json файле:

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

    {
    ...
    "useHipCaptcha": true
    ...
}

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

    {
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}

  3. Если у вас еще нет ключа, его можно настроить с помощью консоли 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",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

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

файл config.runtime.json

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

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

Замените < service name > именем экземпляра службы управления API, используемого в предыдущих файлах конфигурации.

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

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

  1. На портале Azure перейдите к учетной записи хранения на портале Azure.

  2. В меню боковой панели выберитестатический веб-сайт управления >данными.

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

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

  5. В поле пути к документу об ошибке введите 404/index.html.

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

Запишите URL-адрес основной конечной точки . Позже вы настроите его для доступа к локальному порталу.

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

Чтобы настроить параметры общего доступа к ресурсам между источниками (CORS) для учетной записи хранения:

  1. Войдите в свою учетную запись хранения на портале Azure.

  2. В меню боковой панели в разделе "Параметры" выберите "Общий доступ к ресурсам" (CORS).

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

    Правило Ценность
    Разрешенные источники *
    Разрешенные методы Выберите все HTTP-глаголы.
    Разрешенные заголовки *
    Открытые заголовки *
    Максимальный возраст 0

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

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

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

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

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

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

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

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

    npm run start

  2. Вам будет предложено пройти проверку подлинности через браузер. Выберите учетные данные Майкрософт, чтобы продолжить.

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

Шаг 4. Изменение с помощью визуального редактора

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

  • Настройка портала
  • Авторский контент
  • Упорядочение структуры веб-сайта
  • Стилизовать его внешний вид

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

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

  1. Выполните npm run publish. Вам будет предложено пройти проверку подлинности через браузер. Выберите учетные данные Майкрософт, чтобы продолжить.

  2. Через некоторое время содержимое публикуется в папке dist/website .

Шаг 6: Загрузка статических файлов в объект BLOB

Используйте Azure CLI для загрузки локально созданных статических файлов в BLOB-объект и убедитесь, что ваши посетители имеют доступ к ним.

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

  2. Выполните следующую az storage blog upload-batch команду. Замените <connection-string> на строку подключения для вашей учетной записи хранения. Его можно получить в разделе "Безопасность + сеть>Ключи доступа" вашей учетной записи хранения.

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

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

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

Размещение редактора веб-сайта

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

Для этого вам потребуется приложение Microsoft Entra ID в вашей организации:

  1. Зарегистрируйте приложение в тенанте Microsoft Entra ID. Запишите идентификатор приложения (клиента) и идентификатор каталога (клиента). Вы настраиваете их на следующем шаге.
  2. Настройте URI веб-перенаправления (URL-адрес ответа) в этом приложении, чтобы указать конечную точку веб-приложения, в которой размещен конструктор. Обычно это расположение веб-сайта, основанного на блоб-хранилище. Пример: https://<your-storage-account-name>z13.web.core.windows.net/.
  3. Если вы хотите разместить портал через конвейеры (GitHub Actions), также создайте секрет клиента для этого приложения. Запишите созданное значение секрета и сохраните его в безопасном расположении.

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

  1. Добавьте clientId и tenantId поля в config.design.json файл.

    {
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

  2. Выполните команду npm run build-designer для создания конструктора.

  3. Перейдите в созданную /dist/designer папку, содержащую файл config.json со следующим содержимым:

    {
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

  4. Подтвердите конфигурацию subscriptionId, resourceGroupName и serviceName, которые необходимы для подключения к службе Azure API Management с помощью API Azure Resource Manager.

Публикация портала в пайплайнах (GitHub Actions)

Вы можете опубликовать локальный портал в конвейере, например GitHub Actions.

Для выполнения публикации с помощью конвейера также требуются учетные данные приложения Entra ID. Вы можете использовать то же приложение Entra ID, описанное на предыдущих шагах. Элементы tenantId, clientId и особенно clientSecret должны храниться в соответствующем хранилище ключей. Дополнительные сведения см. в разделе "Использование секретов в GitHub Actions".

Пример конвейера GitHub Actions YAML:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

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

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

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

Примечание.

Значения в следующих разделах "Обновлено " предполагают, что вы размещаете портал на 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.v3репозитория портала разработчика службы управления API GitHub.

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

Подсказка

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

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

  • Last updated on