Самостоятельное размещение портала Центра API

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

Самостоятельное размещение — это альтернатива использованию Azure управляемой версии портала Центра API. Дополнительные сведения о портале, управляемом Azure, см. в статье Set up the API Center Portal.

О самостоятельном размещении портала

Вы можете создать и развернуть эталонную реализацию портала с помощью кода в начальном репозитории портала ЦЕНТРА API . На портале используется API уровня данных Центра API Azure для извлечения данных из вашего центра API.

Эталонная реализация портала Центра API предоставляет следующие возможности:

• Платформа для публикации и обслуживания портала API, управляемого клиентом, с помощью GitHub Actions
• Платформа портала, которую клиенты могут изменять или расширять в соответствии с потребностями.
• Гибкость размещения в разных инфраструктурах, включая развертывание служб, таких как статические веб-приложения Azure.

Предпосылки

• Центр API в подписке Azure. Если вы еще не создали его, см Краткое руководство: Создайте ваш центр API.

• Разрешения на создание регистрации приложения в клиенте Microsoft Entra, связанном с подпиской Azure, и разрешения на предоставление доступа к данным в центре API.

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

  • Node.js и npm
  • Пакет Vite

Создание регистрации приложения Microsoft Entra

Чтобы настроить Microsoft Entra ID в качестве поставщика удостоверений, сначала создайте регистрацию приложения в вашем клиенте Microsoft Entra ID. Регистрация приложения позволяет порталу Центра API получать доступ к данным из центра API от имени пользователя, вошедшего в систему.

Центр API может автоматически настроить регистрацию приложения или создать регистрацию приложения вручную.

Автоматическая настройка регистрации приложения (рекомендуется)

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

1. На портале Azure перейдите в центр API.

2. В меню боковой панели выберите Потребление>Параметры портала.

3. На вкладке Access выберите Configure Entra ID.

4. На странице "Настройка входа пользователя с помощью идентификатора Microsoft Entra ID" выберите "Настроить".

5. На вкладке Access нажмите кнопку "Сохранить и опубликовать".

Если вам потребуется получить доступ к регистрации приложения позже, его можно найти на портале в разделе регистрации приложений. Приложение называется следующим форматом: <api-center-name-apic-aad>.

Настройка регистрации приложения вручную

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

1. На портале Azure перейдите в раздел идентификатора Microsoft Entra>Управление> регистрацией приложений.

2. Выберите + Создать регистрацию.

3. На странице Регистрация приложения задайте необходимые значения следующим образом.

   1. Установите Имя на осмысленное название, например api-center-portal
   2. В разделе "Поддерживаемые типы учетных записей" выберите только учетные записи в этом каталоге организации (<имя> каталога — один клиент).
   3. В URI перенаправления выберите одностраничное приложение (SPA) и задайте URI. Введите URI развертывания портала Центра API в следующей форме: https://<service-name>.portal.<location>.azure-apicenter.ms. Замените <service name> и <location> на название вашего центра API и местоположение, где он развернут, например, https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Выберите Зарегистрировать.

Настройка дополнительных URI перенаправления для расширения VS Code

При включении представления портала Центра API в расширении Visual Studio Code для Центра API также настройте следующие URI перенаправления в регистрации приложения:

1. На портале Azure перейдите к регистрации приложения.

2. На странице "Управление>проверкой подлинности " выберите "Добавить платформу " и выберите мобильные и классические приложения.

3. Настройте следующие три настраиваемых URI перенаправления.
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Замените <application-client-id> идентификатором приложения (клиента) этого приложения. Это значение можно найти на странице обзора регистрации приложения.

Настройка локальной среды

Выполните следующие действия, чтобы создать и проверить портал Центра API локально.

1. Клонируйте начальный репозиторий портала Центра API на локальный компьютер.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. Перейдите в каталог APICenter-Portal-Starter.

   cd APICenter-Portal-Starter
   

3. Ознакомьтесь с главной ветвью.

   git checkout main
   

4. Чтобы настроить службу, скопируйте файл config.example.json или переименуйте его в config.json.

5. Затем измените файл config.json, чтобы указать на вашу службу. Обновите значения в файле следующим образом:

   1. Замените <service name> и <region> названием вашего центра API и местоположением, где он развернут.
   2. Замените <client ID> и <tenant ID> на Идентификатор приложения (клиента) и идентификатор каталога (арендатора) регистрации приложения, созданной в предыдущем разделе.
   3. Обновите значение title, чтобы имя, которое вы хотите, отображалось в верхней панели портала.

   {
     "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/Data.Read.All"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. Установите необходимые пакеты.

   npm install
   

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

   npm start
   

   Перейдите на портал https://localhost:5173.

Развертывание в Azure

Инструкции по развертыванию портала в статических веб-приложениях Azure см. в начальном репозитории портала Центра API .

Включение входа на портал пользователями и группами Microsoft Entra

Если идентификатор Microsoft Entra настроен для доступа к порталу, пользователи должны войти на портал Центра API для доступа к API. Чтобы включить авторизацию, назначьте роль читателя данных API центра Azure пользователям или группам в вашей организации, в пределах вашего API центра.

Подробные предварительные требования и действия по назначению роли пользователям и группам см. в статье "Назначение ролей Azure" с помощью портала Azure. Краткие действия:

1. На портале Azure перейдите в центр API.
2. В боковом меню выберите Элемент управления доступом (IAM)>+ Добавить назначение ролей.
3. В области добавления назначения ролей задайте следующие значения:
   1. На странице "Роль" найдите и выберите Чтение данных Центра API Azure. Выберите Далее.
   2. На странице "Участники" в разделе "Назначение доступа" выберите "Пользователь", "Группа" или "Субъект-служба>" и "Выбрать участников".
   3. На странице "Выбор участников" найдите и выберите пользователей или группы, чтобы назначить роль. Нажмите кнопку Выбрать , а затем — Далее.
   4. Просмотрите назначение роли и нажмите кнопку "Проверить и назначить".

После настройки доступа к порталу пользователи могут войти на портал и просмотреть API в центре API.

Устранение неполадок

Ошибка: "Вы не авторизованы для доступа к этому порталу"

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

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Сначала убедитесь, что пользователю назначена роль читателя данных Центра обработки данных Центра API Azure в центре API.

Если пользователю назначена роль, может возникнуть проблема с регистрацией поставщика ресурсов Microsoft.ApiCenter в подписке, и может потребоваться повторно зарегистрировать поставщика ресурсов. Для этого выполните следующую команду в Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Не удается войти на портал

Если пользователи, которым назначена роль читателя данных Центра API Azure , не могут завершить поток входа после выбора входа на портале Центра API, может возникнуть проблема с настройкой поставщика удостоверений Идентификатора Microsoft Entra.

В регистрации приложения Microsoft Entra просмотрите параметры URI перенаправления и, при необходимости, обновите их, чтобы убедиться, что они совпадают с URI развертывания портала Центра API.

Не удается выбрать разрешения Центра API Azure в регистрации приложения Microsoft Entra

Если вы не можете запросить разрешения API в Центре API Azure в регистрации приложения Microsoft Entra на портале Центра API, убедитесь, что вы ищете Центр API Azure (или идентификатор c3ca1a77-7a87-4dba-b8f8-eea115ae4573приложения).

Если приложение отсутствует, может возникнуть проблема с регистрацией поставщика ресурсов Microsoft.ApiCenter в вашей подписке. Возможно, потребуется повторно зарегистрировать поставщика ресурсов. Для этого выполните следующую команду в Azure CLI:

az provider register --namespace Microsoft.ApiCenter

После повторной регистрации поставщика ресурсов повторите попытку запросить разрешения API.

Политика поддержки

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

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

• Настройка портала Центра API
• Что такое управление доступом на основе ролей в Azure (RBAC)?
• Рекомендации по Azure RBAC
• Регистрация поставщика ресурсов