Начало работы с расширением Центра API Azure для Visual Studio Code

Чтобы создать, обнаружить, попробовать и использовать API в центре API, вы можете использовать расширение Центра API Azure в среде разработки Visual Studio Code:

• Создание API— создание API-интерфейсов , которые вы создаете для других пользователей, регистрируя их в центре API. Соответствие конструктора API влево с помощью shift-left проверка в Visual Studio Code с интегрированной поддержкой подстановки. Убедитесь, что новые версии API не прерывают работу потребителей API с обнаружением критических изменений.

• Обнаружение API— обзор API в центре API и просмотр их сведений и документации.

• Попробуйте использовать ИНТЕРФЕЙСы API— используйте пользовательский интерфейс Swagger или клиент REST для изучения запросов и ответов API.

• Использование API — создание клиентов пакета SDK API для избранного языка, включая JavaScript, TypeScript, .NET, Python и Java, с помощью подсистемы Microsoft Kiota, которая создает пакеты SDK для Microsoft Graph, GitHub и многое другое.

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

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

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

• Visual Studio Code

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

Следующие расширения Visual Studio Code являются необязательными и необходимы только для определенных сценариев, как указано ниже.

• Расширение клиента REST— для отправки HTTP-запросов и просмотра ответов в Visual Studio Code напрямую
• Расширение Microsoft Kiota — для создания клиентов API
• Расширение Spectral — для выполнения соответствия конструктора API влево с сдвигом проверка влево в Visual Studio Code
• Optic CLI — для обнаружения критических изменений между документами спецификации API

Настройка

1. Установите расширение Центра API Azure для Visual Studio Code из Visual Studio Code Marketplace. При необходимости установите необязательные расширения.
2. В Visual Studio Code в строке действий слева выберите центр API.
3. Если вы не вошли в учетную запись Azure, выберите вход в Azure... и следуйте инструкциям по входу. Выберите учетную запись Azure с центром API (или центрами API), из которой вы хотите просмотреть API. Вы также можете отфильтровать определенные подписки, если у вас есть много для просмотра.

Регистрация API

Зарегистрируйте API в центре API непосредственно из Visual Studio Code, зарегистрируя его в качестве однократной операции или конвейера CI/CD.

1. Используйте сочетание клавиш CTRL+SHIFT+P, чтобы открыть палитру команд. Введите Центр API Azure: зарегистрируйте API и нажмите клавишу ВВОД.
2. Выберите способ регистрации API в центре API:
   • Пошаговые инструкции лучше всего использовать для однократной регистрации API.
   • CI/CD добавляет предварительно настроенный конвейер GitHub или Azure DevOps в активную рабочую область Visual Studio Code, которая выполняется в рамках рабочего процесса CI/CD для каждой фиксации системы управления версиями. Рекомендуется инвентаризации API в центре API с помощью CI/CD, чтобы гарантировать, что метаданные API, включая спецификацию и версию, остаются текущими в центре API, так как API продолжает развиваться с течением времени.
3. Выполните действия по регистрации:
   • На шаге выберите центр API, чтобы зарегистрировать API и ответить на запросы с информацией, включая название API, тип, этап жизненного цикла, версию и спецификацию ДЛЯ завершения регистрации API.
   • Для CI/CD выберите GitHub или Azure DevOps в зависимости от предпочтительного механизма управления версиями. Для расширения Центра API Azure необходимо открыть рабочую область Visual Studio Code, чтобы добавить конвейер в рабочую область. После добавления файла выполните действия, описанные в самом файле конвейера CI/CD, чтобы настроить переменные среды и удостоверения среды Azure Pipeline/GitHub Action. При отправке в систему управления версиями API будет зарегистрирован в центре API.

Соответствие требованиям к проектированию API

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

1. Используйте сочетание клавиш CTRL+SHIFT+P, чтобы открыть палитру команд. Введите Центр API Azure: задайте активное руководство по стилю API и нажмите клавишу ВВОД.
2. Выберите одно из указанных по умолчанию правил или, если в вашей организации уже доступно руководство по стилю, используйте параметр Select Local File or Input Remote URL-адрес , чтобы указать активный набор правил в Visual Studio Code. Нажмите клавишу ВВОД.

После установки активного руководства по стилю API открытие любого файла спецификации на основе OpenAPI или AsyncAPI запустит локальную операцию подстроки в Visual Studio Code. Результаты отображаются как встроенные в редакторе, так и в окне "Проблемы" (просмотр>проблем или CTRL+SHIFT+M).

Обнаружение критических изменений

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

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

Visual Studio Code откроет представление дифф между двумя спецификациями API. Все критические изменения отображаются как встроенные в редакторе, так и в окне "Проблемы" (просмотр>проблем или CTRL+SHIFT+M).

Обнаружение интерфейсов API

Ресурсы центра API отображаются в представлении дерева слева. Разверните ресурс центра API для просмотра API, версий, определений, сред и развертываний.

Найдите API в Центре API с помощью значка поиска, показанного в элементе представления дерева Apis .

Просмотр документации по API

Вы можете просмотреть документацию по определению API в центре API и попробовать операции API. Эта функция доступна только для API на основе OpenAPI в центре API.

1. Разверните представление дерева Центра API, чтобы отобразить определение API.

2. Щелкните правой кнопкой мыши определение и выберите "Открыть документацию по API". Откроется новая вкладка с пользовательским интерфейсом Swagger для определения API.

   

3. Чтобы попробовать API, выберите конечную точку, выберите "Попробовать", введите необходимые параметры и нажмите кнопку "Выполнить".

   Примечание.

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

Создание HTTP-файла

Файл можно просмотреть .http на основе определения API в центре API. Если установлено расширение клиента REST, можно выполнять запросы из редактора Visual Studio Code. Эта функция доступна только для API на основе OpenAPI в центре API.

1. Разверните представление дерева Центра API, чтобы отобразить определение API.

2. Щелкните правой кнопкой мыши определение и выберите "Создать HTTP-файл". Откроется новая вкладка, которая отображает http-документ, заполненный спецификацией API.

   

3. Чтобы выполнить запрос, выберите конечную точку и выберите команду "Отправить запрос".

   Примечание.

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

Создание клиента API

Используйте расширение Microsoft Kiota для создания клиента API для выбранного языка. Эта функция доступна только для API на основе OpenAPI в центре API.

1. Разверните представление дерева Центра API, чтобы отобразить определение API.
2. Щелкните правой кнопкой мыши определение и выберите "Создать клиент API". Откроется панель генератора OpenAPI Kiota.
3. Выберите конечные точки API и операции HTTP, которые необходимо включить в пакеты SDK.
4. Выберите " Создать клиент API".

   1. Введите сведения о конфигурации имени пакета SDK, пространства имен и выходного каталога.

   2. Выберите язык для созданного пакета SDK.

      

Клиент создается.

Дополнительные сведения об использовании расширения Kiota см . в расширении Microsoft Kiota для Visual Studio Code.

Спецификация API экспорта

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

Чтобы экспортировать спецификацию в представлении дерева расширения, выполните следующие действия.

1. Разверните представление дерева Центра API, чтобы отобразить определение API.

2. Щелкните правой кнопкой мыши определение и выберите "Экспорт API". Откроется новая вкладка, которая отображает документ спецификации API.

   

Вы также можете экспортировать спецификацию с помощью палитры команд:

1. Введите сочетание клавиш CTRL+SHIFT+P, чтобы открыть палитру команд.
2. Выберите Центр API Azure: экспорт API.
3. Сделайте выбор, чтобы перейти к определению API. Откроется новая вкладка, которая отображает документ спецификации API.

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

• Центр API Azure — основные понятия