Включение и просмотр каталога API Центра API Центра API Azure

В этой статье показано, как предоставить корпоративным разработчикам доступ к каталогу API центра API Azure (предварительная версия) в расширении Visual Studio Code для Центра API Azure. Используя каталог API платформы, разработчики могут обнаруживать API в центре API Azure, просматривать определения API и при необходимости создавать клиенты API, если у них нет доступа к самому центру API или добавлять API в инвентаризацию. Доступ к каталогу API платформы управляется с помощью идентификатора Microsoft Entra и управления доступом на основе ролей Azure.

Совет

Расширение Visual Studio Code предоставляет дополнительные возможности для разработчиков API, имеющих разрешения на управление центром API Azure. Например, разработчики API могут регистрировать API в центре API непосредственно или с помощью конвейеров CI/CD. Подробнее

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

Администраторы центра API

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

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

Для разработчиков приложений

• Расширение Центра API Azure для Visual Studio Code

  Внимание

  В настоящее время доступ к каталогу API платформы доступен только в предварительной версии расширения. При установке расширения из Visual Studio Code Marketplace можно установить версию выпуска или предварительную версию. Переключение между двумя версиями в любое время с помощью контекстного меню "Управление расширением" в представлении расширений.

Следующее расширение Visual Studio Code является необязательным:

• Расширение Microsoft Kiota — для создания клиентов API

Действия для администраторов центра API для включения доступа к каталогу

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

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

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

1. В портал Azure перейдите к идентификатору >Microsoft Entra ID Регистрация приложений.

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

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

   • Задайте для имени понятное имя , например platform-api-catalog
   • В разделе "Поддерживаемые типы учетных записей" выберите "Учетные записи" в этом каталоге организации (один клиент).
   • В URI перенаправления выберите одностраничные приложения (SPA) и задайте универсальный код ресурса (URI) среды выполнения центра API. Например, https://<service name>.data.<region>.azure-apicenter.ms. Пример: https://contoso-apic.data.eastus.azure-apicenter.ms.
   • Выберите Зарегистрировать.

   Совет

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

4. На странице обзора скопируйте идентификатор приложения (клиента) и идентификатор каталога (клиента). Эти значения задаются позже при подключении к центру API из расширения Visual Studio Code.

5. В меню слева в разделе "Управление" выберите "Проверка подлинности> и добавление платформы".

6. На странице "Настройка платформ" выберите мобильные и классические приложения.

7. На странице "Настройка рабочего стола и устройств" введите следующий URI перенаправления и выберите "Настроить".

   https://vscode.dev/redirect

8. В меню слева в разделе "Управление" выберите разрешения> API+ Добавить разрешение.

9. На странице разрешений API запросов выполните следующие действия.

   1. Щелкните вкладку API, используемые моей организацией.
   2. Найдите и выберите Центр API Azure. Вы также можете найти и выбрать идентификатор c3ca1a77-7a87-4dba-b8f8-eea115ae4573приложения.
   3. На странице "Выбор разрешений" выберите user_impersonation.
   4. Выберите Добавить разрешения.

   Разрешения Центра API Azure отображаются в разделе "Настроенные разрешения".

   

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

Корпоративные разработчики должны войти с помощью учетной записи Майкрософт, чтобы просмотреть каталог API платформы для центра API. При необходимости добавьте или пригласите разработчиков в клиент Microsoft Entra.

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

Внимание

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

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

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

Примечание.

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

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

Разработчики могут выполнить следующие действия, чтобы подключиться и войти в систему, чтобы просмотреть каталог API платформы с помощью расширения Visual Studio Code. Параметры для подключения к центру API должны предоставляться администратором центра API.

Подключение к центру API

1. Установите предварительную версию расширения Центра API Azure для Visual Studio Code для Visual Studio Code для Visual Studio Code.

2. В Visual Studio Code в строке действий слева выберите центр API.

   

3. Используйте сочетание клавиш CTRL+SHIFT+P, чтобы открыть палитру команд. Введите Центр API Azure: подключитесь к Центру API и нажмите клавишу ВВОД.

4. Ответьте на запросы для ввода следующих сведений:

   1. URL-адрес среды выполнения центра API в формате <service name>.data.<region>.azure-apicenter.ms (не префикс с https://). Пример: contoso-apic.data.eastus.azure-apicenter.ms. Этот URL-адрес среды выполнения отображается на странице обзора центра API в портал Azure.
   2. Идентификатор приложения (клиента) из регистрации приложения, настроенного администратором в предыдущем разделе.
   3. Идентификатор каталога (клиента) из регистрации приложения, настроенного администратором в предыдущем разделе.

   Совет

   Администратор центра API должен предоставить эти сведения о подключении разработчикам или предоставить прямую ссылку в следующем формате:
   vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

   После подключения к центру API имя центра API появится в каталоге API платформы API Центра API.

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

   

6. После входа выберите API для перечисления API в центре API. Разверните API для изучения версий и определений.

   

7. Повторите предыдущие шаги, чтобы подключиться к нескольким центрам API, если доступ настроен.

Обнаружение и использование API в каталоге

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

• Экспорт документа спецификации API— экспорт спецификации API из определения и его скачивание в виде файла
• Создание клиента API. Использование расширения Microsoft Kiota для создания клиента API для любимого языка
• Создание Markdown — создание документации по API в формате Markdown
• Документация по OpenAPI. Просмотрите документацию по определению API и попробуйте выполнить операции в пользовательском интерфейсе Swagger (доступно только для определений OpenAPI).

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

Ошибка: не удается считывать свойства неопределенного (чтение nextLink)

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

Error: Cannot read properties of undefined (reading 'nextLink')

Убедитесь, что пользователю назначена роль читателя данных Центра обработки данных Центра API Azure в центре API. При необходимости переназначьте роль пользователю. Затем обновите каталог API платформы Центра API в расширении Visual Studio Code.

Не удается войти в Azure

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

Проверьте параметры регистрации приложения, настроенной в идентификаторе Microsoft Entra. Подтвердите значения идентификатора приложения (клиента) и идентификатор каталога (клиента) в регистрации приложения и URL-адрес среды выполнения центра API. Затем снова настройте подключение к центру 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 Azure для Visual Studio Code
• Рекомендации по Azure RBAC
• Регистрация поставщика ресурсов