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

Статья
05/02/2024

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

Снимок экрана: портал Центра API после входа пользователя.

Сведения о портале Центра API

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

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

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

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

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

Центр API в подписке Azure. Если вы еще не создали его, см . краткое руководство. Создание центра API.
Разрешения на создание регистрации приложения в клиенте Microsoft Entra, связанном с подпиской Azure, и разрешения на предоставление доступа к данным в центре API.
Чтобы создать и развернуть портал, вам потребуется учетная запись GitHub и следующие средства, установленные на локальном компьютере:
- Node.js и npm
- Пакет Vite

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

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

В портал Azure перейдите к идентификатору >Microsoft Entra ID Регистрация приложений.
Выберите + Создать регистрацию.
На странице Регистрация приложения задайте необходимые значения следующим образом.
- Задайте для имени понятное имя , например api-center-portal
- В разделе "Поддерживаемые типы учетных записей" выберите "Учетные записи" в этом каталоге организации (один клиент).
- В URI перенаправления выберите одностраничные приложения (SPA) и задайте универсальный код ресурса (URI).
  - Для локального тестирования задайте для URI значение https://localhost:5173.
  - Для рабочей среды задайте универсальный код ресурса (URI) для развертывания портала Центра API.
- Выберите Зарегистрировать.
На странице обзора скопируйте идентификатор приложения (клиента) и идентификатор каталога (клиента). Эти значения задаются при создании портала.
На странице разрешений API нажмите кнопку +Добавить разрешение.
1. На странице разрешений API запроса выберите API, которые использует моя организация. Найдите и выберите Центр API Azure. Вы также можете найти и выбрать идентификатор c3ca1a77-7a87-4dba-b8f8-eea115ae4573приложения.
2. На странице разрешений запроса выберите user_impersonation.
3. Выберите Добавить разрешения.
Разрешения Центра API Azure отображаются в разделе "Настроенные разрешения".

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

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

Клонируйте начальный репозиторий портала Центра API на локальный компьютер.
```
git clone https://github.com/Azure/APICenter-Portal-Starter.git
```
Перейдите в каталог APICenter-Portal-Starter.
```
cd APICenter-Portal-Starter
```
Извлеките главную ветвь.
```
git checkout main
```
Чтобы настроить службу, скопируйте или переименуйте public/config.example файл public/config.jsonв .
Затем измените public/config.json файл, чтобы указать службу. Обновите значения в файле следующим образом:
- Замените и <region> назовите <service name> центр API и регион, в котором он развернут.
- Замените <client ID> идентификатор приложения (клиента) и идентификатор каталога (клиента) регистрации приложения, созданной в предыдущем разделе.<tenant ID>
- Обновите значение title имени, которое вы хотите появить на портале.
```
{
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}
```
Установите необходимые пакеты.
```
npm install
```
Запустите сервер разработки. Следующая команда запустит портал в режиме разработки локально:
```
npm start
```
Перейдите на портал https://localhost:5173.

Развернуть в Azure

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

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

Внимание

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

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

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

Примечание.

Чтобы упростить настройку доступа для новых пользователей, рекомендуется назначить роль группе Microsoft Entra и настроить правило динамического членства в группах. Дополнительные сведения см. в статье "Создание или обновление динамической группы" в идентификаторе Microsoft Entra.

После настройки доступа к порталу настроенные пользователи могут войти на портал и просмотреть API в центре 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 соответствует 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

Сведения о портале Центра API

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

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

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

Развернуть в Azure

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

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

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

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

Обратная связь

Дополнительные ресурсы

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

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

Сведения о портале Центра API

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

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

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

Развернуть в Azure

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

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

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

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

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

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

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

Обратная связь

Дополнительные ресурсы