Начало работы с Центром API

Завершено

В этом упражнении вы выполните следующие действия.

1. Создайте службу Центра API.

2. Определите свойства метаданных.

3. Добавьте API в Центр API.

4. Добавление развертываний и сред.

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

Чтобы начать управление API через Центр API, вам потребуется:

1. Подписка Azure.
2. Поставщик ресурсов Microsoft.ApiCenter , зарегистрированный в подписке.
3. По крайней мере назначение роли участника или эквивалентные разрешения в подписке Azure.

Примечание.

Если вы еще не сделали этого, необходимо зарегистрировать поставщик ресурсов Microsoft.ApiCenter в подписке.

1. Войдите на портал Azure.
2. Введите подписки в строке поиска.
3. Выберите подписку, в которой нужно создать Центр API.
4. В меню слева в разделе "Ресурсы" выберите "Поставщики ресурсов".
5. Найдите Microsoft.ApiCenter в списке поставщиков ресурсов. Если он не зарегистрирован, выберите "Зарегистрировать".

Шаг 1. Создание службы Центра API

1. Войдите на портал Azure.

2. Введите центры API в строке поиска.

3. Выберите + Создать.

4. На вкладке "Основные сведения" выберите или введите следующие параметры:

   a. Выберите свою подписку Azure.

   b. Выберите существующую группу ресурсов или нажмите кнопку "Создать ", чтобы создать новую.

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

   d. В регионе выберите один из доступных регионов для Центра API.

   д) Для плана ценообразования выберите бесплатную пробную версию ($0 в течение 90 дней).

   f. Выберите Review + create (Просмотреть и создать).

   h. После завершения проверки щелкните Создать.

   После развертывания центр API готов к использованию!

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

az login

Примечание.

Если вы еще не сделали этого, необходимо зарегистрировать поставщик ресурсов Microsoft.ApiCenter в подписке.

Выполните следующую команду, чтобы зарегистрировать поставщика ресурсов

az provider register –namespace Microsoft.ApiCenter 

Шаг 1. Создание службы Центра API

Создайте группу ресурсов, выполнив следующую команду, передав следующую команду:

• Имя группы ресурсов --name . Пример. Contoso
• Location --location Example. Eastus

az group create –-name contoso –-location eastus  

Примечание.

команды az apic требуют расширения Azure CLI apic-extension. Если вы не использовали команды az apic , расширение будет установлено динамически при выполнении первой команды az apic или установить расширение вручную. Дополнительные сведения о расширениях Azure CLI.

Создайте Центр API, выполнив следующую команду, передав следующую команду:

• Имя службы центра API -n Пример. contoso-apis
• Пример группы ресурсов -g . Contoso
• Пример location --l . Eastus

az apic create -n contoso-apis -g contoso -l eastus 

Примечание.

По умолчанию Центр API будет создан в ценовой категории "Бесплатный ".

Примечание.

Создание службы Центра API в настоящее время не поддерживается в VS Code. Создайте его с помощью Azure CLI или портал Azure.

Шаг 2. Определение свойств метаданных

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

Примечание.

Не включать конфиденциальную, конфиденциальную или личную информацию в заголовки или имена свойств метаданных.

Компания Contoso, как и многие другие организации, хотели бы передать все api-интерфейсы утверждающего, прежде чем они становятся доступными для использования, и убедиться, что проверка соответствия выполняется для всех API. Организация также имеет ИНТЕРФЕЙСы API, которые являются общедоступными и созданными исключительно для внутреннего использования. Чтобы применить это в масштабе для всех API, мы добавим три настраиваемых свойства метаданных:

• Утверждающий API типа String
• Проверка соответствия предопределенным параметрам типа
• Общедоступная лицовая часть типа Boolean

1. В меню слева выберите "Метаданные ресурсов >> " и "Новые метаданные".

2. На вкладке "Сведения" введите сведения о свойстве.

   a. В заголовке введите утверждающий API

   b. В описании введите утверждающий API по умолчанию

   c. Выберите тип "Строка" и нажмите кнопку "Далее"

3. На вкладке "Назначения" выберите "Обязательный для API". Выберите " Необязательно" для развертываний и сред. Выберите Далее

4. Нажмите кнопку Создать

5. Повторите те же действия для свойства Public-facing , как показано на рисунке ниже. Для типа выберите boolean

6. На вкладке "Назначения" выберите "Обязательный для API". Выберите "Неприменимо для развертываний и сред". Выберите Далее

7. Нажмите кнопку Создать

8. Повторите те же действия для свойства проверки соответствия требованиям, как показано на рисунке ниже. Для типа выберите стандартные варианты и добавьте 3 варианта, не запущены, в процессе выполнения и завершены

9. На вкладке "Назначения" выберите "Обязательный для API". Выбор неприменимо для развертываний и сред

10. Выберите Далее

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

Откроется модал справа с подробными сведениями о метаданных, которые включают встроенные свойства из Центра API, таких как LifecycleStage, Name, Description, TermsOfService среди других. Если прокрутите страницу до нижней части файла, вы увидите настраиваемые метаданные, добавленные на предыдущих шагах, как показано ниже.

Примечание.

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

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

• Имя метаданных в качестве утверждающего API
• Схема с типом свойства в качестве строки и заголовка в качестве утверждающего API
• Назначения по мере необходимости для API, а также необязательные для среды и развертывания

az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Повторите те же действия для следующих действий:

• Имя метаданных как общедоступное
• Схема с типом свойства как boolean и title as Public Facing
• Назначения по мере необходимости для API, а также необязательные для среды и развертывания

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

az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Наконец, повторите те же действия для:

• Имя метаданных в качестве проверки соответствия требованиям
• Схема с типом свойства в виде строки и заголовка в качестве проверки соответствия требованиям
• Назначения по мере необходимости для API, а также необязательные для среды и развертывания

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

az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Чтобы просмотреть список всех определенных метаданных в Центре API, выполните следующую команду.

az apic metadata list -g <resource-group-name> -n <api-center-name> 

Примечание.

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

Примечание.

Это действие в настоящее время не поддерживается в VS Code. Создайте его с помощью Azure CLI или портал Azure.

Шаг 3. Добавление API в инвентаризацию

Организация Contoso хотела бы рекомендовать технические конференции для своих инженерных команд в рамках внутреннего навыков. Мы добавим API конференций с докладчиками, сеансами и темами.

URL-адрес API конференции: https://bigconference.azurewebsites.net/

Для выполнения следующих действий можно скопировать определение OpenAPI из приведенного выше веб-сайта и сохранить его в виде JSON-файла на локальном компьютере. Или замените другое определение API при добавлении API в инвентаризацию.

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

2. В меню слева выберите API > ресурсов > и зарегистрировать API.

3. На странице "Регистрация API" добавьте следующие необходимые сведения для API. В нижней части страницы вы увидите настраиваемые свойства метаданных утверждающего API, *public-facing и проверки соответствия требованиям.

Чтобы просмотреть созданный API, в меню слева выберите > API конференций активов >.

Вкладка "Обзор" предоставляет представление конфигурации API. Разверните сведения , чтобы просмотреть и изменить дополнительные сведения, такие как версия API и развертывания (на данный момент у нас нет развертываний).

Обычно необходимо добавить определение API для версии API и Центр API поддерживает форматы спецификаций текста, включая OpenAPI 2, OpenAPI 3 для REST.

Чтобы добавить определение,

1. В меню слева выберите API "Активы" >> Выберите API (API конференций).>
2. Разверните сведения и выберите версии.
3. Выберите версию (версия 1) и разверните узел "Сведения".
4. В разделе "Подробные сведения" выберите "Добавить определение определений>".

Расширение Центра API Azure для Visual Studio Code можно использовать для регистрации API в экземпляре API.

Шаг 1.Установка расширения

Шаг 2. Открытие поддона команды CTRL+SHIFT+ P и центр API типов : Регистрация API

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

Регистрация API	Пошаговое руководство
Выбор службы Центра API	Выбор экземпляра Центра API
Название API	Введите имя API (API конференции)
Тип API	REST
Название версии API	Введите имя версии для API (версия 1)
Жизненный цикл версий API	Выберите жизненный цикл из раскрывающегося списка (разработка)
Название определения API	Введите имя определения (определение API конференции)
Имя спецификации API	Выберите спецификацию из раскрывающегося списка (OpenAPI 2)
Выбор файла определения API для импорта	Просмотр и выбор файла определения из хранилища

Обновите вкладку расширения Центра API, а созданный API отображается в соответствующем экземпляре ИЛИ ресурсе APIC.

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

• Пример группы ресурсов -g . Contoso
• Имя службы центра API -n Пример. contoso-api-center
• Заголовок --title Example. API конференций
• Пример идентификатора API --api-id . конференц-api
• Пример типа -type . REST

az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

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

• Пример группы ресурсов -g . contoso
• Имя службы центра API -n Пример. contoso-apis
• Пример идентификатора API --api-id . конференц-api
• Заголовок --title Example. v1.2.2
• Пример идентификатора версии --version-id . 2024-07-03
• Пример этапа жизненного цикла — этап жизненного цикла. проектировать

az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design

Вы также можете добавить определение API для версии API и Центр API поддерживает форматы спецификаций текста, включая OpenAPI 2, OpenAPI 3 для REST.

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

• Пример группы ресурсов -g . contoso
• Имя службы центра API -n Пример. contoso-apis
• Пример идентификатора API --api-id . конференц-api
• Пример идентификатора версии --version-id . 2024-07-03
• Заголовок --title Example. OpenAPI
• Идентификатор определения --definition-id Example. openapi

az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi 

Чтобы импортировать файл определения OpenAPI из URL-адреса, используйте команду az apic api definition import-specification для импорта. Пример: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples

az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'

Шаг 4. Добавление развертываний и сред

Среды

Среда (разработка, тестирование, промежуточное развертывание или рабочая среда) представляет расположение, в котором развертывается среда выполнения API. Инженеры платформы API в Contoso определяют две среды— тестирование и рабочую среду в экземпляре Центра API для управления и отслеживания различных сред выполнения API в своей организации.

Чтобы создать среду,

1. В меню слева выберите "Среды > ресурсов > " + Новая среда".

2. Добавьте следующие данные.

3. Нажмите кнопку создания.

4. Повторите те же действия для рабочей среды.

   

Чтобы создать среду, выполните следующую команду CLI.

az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing

Повторите то же самое для рабочей среды

az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production

Примечание.

Создание сред в настоящее время не поддерживается в VS Code. Используйте Azure CLI или параметр портал Azure для этого шага.

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

Уникальное расположение (адрес) для пользователей, взаимодействующих с API, предоставляется для каждой среды выполнения API в данной среде. Это расположение называется развертыванием, а одна версия API может иметь два развертывания — промежуточное и рабочее развертывание.

Contoso имеет один API, API конференции, который мы связываем с созданными средами.

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

2. В меню слева выберите API и выберите API, например API конференции.

3. На странице API конференции разверните раздел "Сведения > о развертывании > " и "Добавить развертывание".

4. Добавьте следующие данные:

   a. Выберите Contoso Testing в раскрывающемся списке для поля "Среда ".

   b. Для определения нажмите кнопку "Выбрать", выберите версию API версии 1 в раскрывающемся списке и выберите добавленное ранее определение. Щелкните Выбрать.

   c. После успешного добавления определения добавьте URL-адрес базовой среды выполнения, который будет использоваться для API в выбранной среде.

   

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

az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'

Примечание.

Создание развертываний в настоящее время не поддерживается в VS Code. Используйте Azure CLI или параметр портал Azure для этого шага.