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

Быстрый старт: Развернуть приложение RESTful API в Azure Spring Apps

Примечание.

Планы Basic, Standardи Enterprise вступили в период вывода из обращения 17 марта 2025 года. Дополнительные сведения см. в объявлении о выходе на пенсию в Azure Spring Apps.

В этой статье описывается, как развернуть приложение API RESTful, защищенное идентификатором Microsoft Entra в Azure Spring Apps. Пример проекта — это упрощенная версия на основе простого веб-приложения Todo , который предоставляет только серверную службу и использует идентификатор Microsoft Entra для защиты API RESTful.

Эти API RESTful защищены путем применения управления доступом на основе ролей (RBAC). Анонимные пользователи не могут получить доступ к данным и не могут управлять доступом для разных пользователей. Анонимные пользователи имеют только следующие три разрешения:

  • Чтение. С этим разрешением пользователь может считывать данные ToDo.
  • Запись. С помощью этого разрешения пользователь может добавлять или обновлять данные ToDo.
  • Удаление: с этим разрешением пользователь может удалить данные ToDo.

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

Снимок экрана: пользовательский интерфейс Swagger, в котором показан документ API.

На следующей схеме показана архитектура системы:

Схема, демонстрирующая архитектуру веб-приложения Spring.

В этой статье описаны следующие варианты создания ресурсов и их развертывания в Azure Spring Apps:

  • Параметр портал Azure + подключаемый модуль Maven предоставляет более привычный способ создания ресурсов и поэтапного развертывания приложений. Этот вариант подходит для разработчиков Spring, которые впервые используют облачные службы Azure.
  • Параметр Azure CLI использует мощное средство командной строки для управления ресурсами Azure. Этот вариант подходит для разработчиков Spring, знакомых с облачными службами Azure.

1. Предварительные требования

2. Подготовка проекта Spring

Чтобы развернуть приложение API RESTful, сначала необходимо подготовить проект Spring для локального запуска.

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

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

    git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git

  2. Если вы хотите локально запустить приложение, выполните действия, описанные в разделах "Предоставление API RESTful" и обновление разделов конфигурации приложения, а затем выполните следующую команду, чтобы запустить пример приложения с Maven:

    cd ASA-Samples-Restful-Application
./mvnw spring-boot:run

3. Подготовка облачной среды

Основными ресурсами, необходимыми для запуска этого примера приложения, являются экземпляр Azure Spring Apps и экземпляр База данных Azure для PostgreSQL. В следующих разделах описывается создание этих ресурсов.

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

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

3.2. Создайте экземпляр Azure Spring Apps

Чтобы создать экземпляр службы Azure Spring Apps, выполните следующие действия.

  1. Выберите "Создать ресурс" в углу портал Azure.

  2. Выберите Compute>Azure Spring Apps.

  3. Заполните форму Основные данные , указав следующую информацию:

    Настройка Предлагаемое значение Описание
    Подписка Имя вашей подписки. Подписка Azure, которую вы хотите использовать для сервера. Если у вас есть несколько подписок, выберите ту, через которую вы предпочитаете оплачивать этот ресурс.
    Группа ресурсов myresourcegroup Новое имя группы ресурсов или уже имеющееся из подписки.
    Имя мясо Уникальное имя, определяющее службу Azure Spring Apps. Его длина должна быть от 4 до 32 знаков. Имя может содержать только строчные буквы, цифры и дефисы. Первым символом в имени службы должна быть буква, а последним — буква или цифра.
    План Корпорация План ценообразования, определяющий ресурс и затраты, связанные с вашим экземпляром.
    Регион Регион, ближайший к вашим пользователям. Ближайшее к пользователям место.
    Избыточность зон не выбрано Возможность создания службы Azure Spring Apps в зоне доступности Azure. Эта функция в настоящее время не поддерживается во всех регионах.
    План IP-адресов программного обеспечения Оплата по мере использования План ценообразования, который позволяет платить по мере использования Azure Spring Apps.
    Terms Выбрано Флажок соглашения, связанный с предложением на торговой площадке. Вам необходимо установить этот флажок.
    Развертывание примера проекта не выбрано Возможность использовать встроенное тестовое приложение.

  4. Выберите "Рецензирование" и " Создать ", чтобы просмотреть выбранные варианты. Затем выберите "Создать ", чтобы подготовить экземпляр Azure Spring Apps.

  5. На панели инструментов щелкните значок Уведомления (колокольчик), чтобы отслеживать процесс развертывания. После завершения развертывания можно выбрать «Закрепить на панели мониторинга», что создаст плитку этой службы на панели мониторинга портала Azure как ярлык для страницы «Обзор» службы.

    Снимок экрана: портал Azure, на котором показана область уведомлений для создания Azure Spring Apps.

  6. Выберите Перейти к ресурсу, чтобы перейти на страницу Обзор Azure Spring Apps.

3.3. Подготовка экземпляра PostgreSQL

Чтобы создать сервер База данных Azure для PostgreSQL, выполните следующие действия.

  1. Перейдите к портал Azure и нажмите кнопку "Создать ресурс".

  2. Выберите Базы данных>База данных Azure для PostgreSQL.

  3. Выберите вариант развертывания Гибкий сервер.

    Снимок экрана: портал Azure, на котором показана страница выбора параметра развертывания База данных Azure для PostgreSQL.

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

    • Имя сервера: my-demo-pgsql
    • Регион: восточная часть США
    • Версия PostgreSQL: 14
    • Тип рабочей нагрузки: разработка
    • Включение высокой доступности: не выбрано
    • Метод проверки подлинности: только проверка подлинности PostgreSQL
    • Имя пользователя администратора: myadmin
    • Пароль и подтверждение пароля: введите пароль.

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

    • Метод подключения: общедоступный доступ (разрешенные IP-адреса)
    • Разрешить общедоступный доступ из любой службы Azure в Azure на этот сервер: выбрано:

  6. Выберите "Проверка и создание ", чтобы просмотреть выбранные элементы, и нажмите кнопку "Создать ", чтобы подготовить сервер. Эта операция может занять несколько минут.

  7. На портале Azure перейдите к серверу PostgreSQL. На странице обзора найдите значение имени сервера и запишите его для последующего использования. Необходимо настроить переменные среды для приложения в Azure Spring Apps.

  8. Выберите базы данных из меню навигации, чтобы создать базу данных, например todo.

    Снимок экрана: портал Azure, на котором показана страница

3.4. Подключение экземпляра приложения к экземпляру PostgreSQL

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

  1. Перейдите к экземпляру своей службы Azure Spring Apps на портале Azure.

  2. В меню навигации откройте приложения и нажмите кнопку "Создать приложение".

  3. На странице "Создание приложения" введите имя приложения simple-todo-api и выберите артефакты Java в качестве типа развертывания.

  4. Нажмите кнопку "Создать ", чтобы завершить создание приложения, а затем выберите приложение для просмотра сведений.

  5. Перейдите к приложению, созданному в портале Azure. На странице "Обзор" выберите "Назначить конечную точку", чтобы предоставить общедоступную конечную точку для приложения. Сохраните URL-адрес для доступа к приложению после развертывания.

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

    Снимок экрана: портал Azure, на котором показана страница соединителя службы планов предприятия с выделенной кнопкой

  7. Заполните вкладку "Основные сведения" следующими сведениями :

    • Тип службы: гибкий сервер базы данных для PostgreSQL
    • Имя подключения: заполняется автоматически созданное имя, которое также можно изменить.
    • Подписка. Выберите нужную подписку.
    • Гибкий сервер PostgreSQL: my-demo-pgsql
    • База данных PostgreSQL: выберите созданную базу данных.
    • Тип клиента: SpringBoot

    Снимок экрана портала Azure, на котором показана вкладка

  8. Настройте вкладку "Далее: проверка подлинности " со следующими сведениями:

    Примечание.

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

    • Выберите тип проверки подлинности, который вы хотите использовать между вычислительной службой и целевой службой.: выберите строку подключения.
    • Продолжить с...: выбор учетных данных базы данных
    • Имя пользователя: myadmin
    • Пароль. Введите пароль.

    Снимок экрана портала Azure, на котором показана вкладка

  9. Выберите Далее: сеть. Используйте параметр по умолчанию Настройка правил брандмауэра для включения доступа к целевой службе.

  10. Нажмите кнопку "Далее" и "Создать ", чтобы просмотреть выбранные элементы, а затем нажмите кнопку "Создать ", чтобы создать подключение.

3.5. Делать доступными API RESTful

Чтобы опубликовать API RESTful в Microsoft Entra ID, выполните следующие действия.

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

  2. Если у вас есть доступ к нескольким клиентам, используйте фильтр каталогов и подписок ( ) для выбора клиента, в котором требуется зарегистрировать приложение.

  3. Найдите и выберите Microsoft Entra ID.

  4. В разделе Управление выберите Регистрация приложений>Создать регистрацию.

  5. Введите имя приложения в поле "Имя ", например Todo. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.

  6. Для поддерживаемых типов учетных записей выберите учетные записи в любом каталоге организации (любой каталог Microsoft Entra — Multitenant) и личных учетных записей Майкрософт.

  7. Выберите Зарегистрировать, чтобы создать приложение.

  8. На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже. Вам потребуется настроить файл конфигурации YAML для этого проекта.

  9. В разделе "Управление" выберите "Предоставить API", найдите URI идентификатора приложения в начале страницы и нажмите кнопку "Добавить".

  10. На странице "Изменение идентификатора приложения" примите предлагаемый URI идентификатора приложения (api://{client ID}) или используйте понятное имя вместо идентификатора клиента, например api://simple-todo, а затем нажмите кнопку "Сохранить".

  11. В разделе «Управление» выберите «Опубликовать API»>«Добавить область», а затем введите следующие сведения:

    • В поле "Имя области" введите ToDo.Read.
    • Для того, кто может давать согласие, выберите только администраторы.
    • Для отображаемого имени согласия администратора введите Чтение данных ToDo.
    • В Описание согласия администратора введите Предоставляет аутентифицированным пользователям разрешение на считывание данных ToDo.
    • Для состояния оставьте его включенным.
    • Выберите Добавить область.

  12. Повторите предыдущие шаги, чтобы добавить другие две области: ToDo.Write и ToDo.Delete.

    Снимок экрана портала Azure, на котором показана страница 'Expose an API' приложения RESTful API.

3.6. Обновление конфигурации приложения

Чтобы обновить YAML-файл, чтобы использовать сведения о зарегистрированном приложении Microsoft Entra, выполните следующие действия, чтобы установить связь с приложением API RESTful:

  1. Найдите файл src/main/resources/application.yml для simple-todo-api приложения. Обновите конфигурацию в spring.cloud.azure.active-directory разделе, чтобы она соответствовала следующему примеру. Обязательно замените заполнители значениями, созданными ранее.

    spring:
  cloud:
    azure:
      active-directory:
        profile:
          tenant-id: <tenant>
        credential:
          client-id: <your-application-ID-of-ToDo>
        app-id-uri: <your-application-ID-URI-of-ToDo>

    Примечание.

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

    Допустимые значенияtenant-id: common, organizationsconsumersили идентификатор клиента. Дополнительные сведения об этих значениях см. в разделе "Использована неправильная конечная точка (личные и учетные записи организации)" в разделе "Ошибка AADSTS50020 - учетная запись пользователя от поставщика удостоверений не существует в клиенте". Сведения о преобразовании приложения с одним клиентом можно найти в разделе «Преобразование однотенантного приложения в мультитенант в Microsoft Entra ID».

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

    ./mvnw clean package

4. Развертывание приложения в Azure Spring Apps

Теперь вы можете развернуть приложение в Azure Spring Apps.

Выполните следующие действия для развертывания с плагином Maven для Azure Spring Apps:

  1. Перейдите к полному каталогу и выполните следующую команду, чтобы настроить приложение в Azure Spring Apps:

    ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

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

    • Вход OAuth2: необходимо авторизовать вход в Azure на основе протокола OAuth2.
    • Выберите подписку: выберите номер списка подписок созданного экземпляра Azure Spring Apps, который по умолчанию соответствует первой подписке в списке. Если вы используете номер по умолчанию, нажмите клавишу ВВОД напрямую.
    • Используйте существующие Azure Spring Apps в Azure: нажмите y , чтобы использовать существующий экземпляр Azure Spring Apps.
    • Выберите Azure Spring Apps для развертывания: выберите номер созданного экземпляра Azure Spring Apps. Если вы используете номер по умолчанию, нажмите клавишу ВВОД напрямую.
    • Используйте существующее приложение в Azure Spring Apps <с именем> экземпляра: нажмите клавишу Y , чтобы использовать созданное приложение.
    • Подтвердите сохранение всех указанных выше конфигураций: нажмите клавишу Y. Если нажать клавишу N, конфигурация не сохраняется в POM-файлах.

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

    ./mvnw azure-spring-apps:deploy

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

    • Вход OAuth2: необходимо авторизовать вход в Azure на основе протокола OAuth2.

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

[INFO] Deployment Status: Running
[INFO]   InstanceName:simple-todo-api-default-15-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:N/A       
[INFO] Getting public url of app(simple-todo-api)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-simple-todo-api.azuremicroservices.io

5. Проверка приложения

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

5.1. Запросите маркер доступа

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

Регистрация клиентского приложения

Чтобы зарегистрировать приложение в идентификаторе Microsoft Entra, которое используется для добавления разрешений для ToDo приложения, выполните следующие действия.

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

  2. Если у вас есть доступ к нескольким клиентам, используйте фильтр каталогов и подписок ( ) для выбора клиента, в котором требуется зарегистрировать приложение.

  3. Найдите и выберите Microsoft Entra ID.

  4. В разделе Управление выберите Регистрация приложений>Создать регистрацию.

  5. Введите имя приложения в поле "Имя ", например ToDoWeb. Пользователи приложения могут видеть это имя. Вы можете изменить его позже.

  6. Для поддерживаемых типов учетных записей используйте только учетные записи по умолчанию в этом каталоге организации.

  7. Выберите Зарегистрировать, чтобы создать приложение.

  8. На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже. Он необходим для получения токена доступа.

  9. Выберите Разрешения API>Добавить разрешение>Мои API. ToDo Выберите приложение, зарегистрированное ранее, и выберите разрешения ToDo.Read, ToDo.Write и ToDo.Delete. Выберите Добавить разрешения.

  10. Выберите < клиента, >чтобы предоставить согласие администратора для добавленных разрешений.

    Снимок экрана: портал Azure с разрешениями API веб-приложения.

Добавление пользователя для доступа к API RESTful

Выполните следующие действия, чтобы создать пользователя-участника в клиенте Microsoft Entra. Затем пользователь может управлять данными ToDo приложения с помощью API RESTful.

  1. В разделе "Управление" выберите "Пользователи>" Создать пользователя.>

  2. На странице "Создание нового пользователя" введите следующие сведения:

    • Имя основного пользователя: введите имя для пользователя.
    • Отображаемое имя: введите отображаемое имя пользователя.
    • Пароль. Скопируйте автоматически созданный пароль, указанный в поле "Пароль".

    Примечание.

    Новые пользователи должны завершить проверку подлинности первого входа и обновить пароли, в противном случае при получении маркера доступа возникает AADSTS50055: The password is expired ошибка.

    Когда новый пользователь входит в систему, он получает запрос на обязательное действие. Они могут выбрать запрос позже , чтобы пропустить проверку.

  3. Выберите Проверка и создание, чтобы проверить ваши выборы. Нажмите кнопку "Создать" , чтобы создать пользователя.

Обновление конфигурации OAuth2 для авторизации пользовательского интерфейса Swagger

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

  1. Откройте свой клиент Microsoft Entra ID в портале Azure и перейдите к зарегистрированному ToDoWeb приложению.

  2. В разделе "Управление" выберите "Проверка подлинности", выберите "Добавить платформу" и выберите одностраничные приложения.

  3. Используйте формат <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html в качестве URL-адреса перенаправления OAuth2 в поле перенаправления URI, а затем выберите Настроить.

    Снимок экрана: портал Azure, на котором показана страница проверки подлинности для идентификатора Microsoft Entra.

Получите маркер доступа

Выполните следующие шаги, чтобы использовать авторизационный поток OAuth 2.0 для получения токена доступа с идентификатором Microsoft Entra ID, для последующего доступа к RESTful API приложения ToDo.

  1. Откройте URL-адрес, предоставляемый приложением, а затем выберите "Авторизовать ", чтобы подготовить проверку подлинности OAuth2.

  2. В окне "Доступные авторизации" введите идентификатор ToDoWeb клиента приложения в поле client_id, выберите все области для полей "Области", пропустить поле client_secret, а затем выберите "Авторизовать" для перенаправления на страницу входа Microsoft Entra.

Завершив вход с предыдущим пользователем, вы вернеесь в окно "Доступные авторизации".

5.2. Доступ к API RESTful

Чтобы получить доступ к RESTful API приложения ToDo в интерфейсе Swagger, выполните следующие шаги.

  1. Выберите API POST /api/simple-todo/lists , а затем нажмите кнопку "Попробовать". Введите следующий текст запроса и нажмите кнопку "Выполнить ", чтобы создать список toDo.

    {
  "name": "My List"
}

    После завершения выполнения отобразится следующий текст ответа:

    {
  "id": "<ID-of-the-ToDo-list>",
  "name": "My List",
  "description": null
}

  2. Выберите API POST /api/simple-todo/list/{listId}/items , а затем нажмите кнопку "Попробовать". В поле listId введите созданный ранее идентификатор списка ToDo, введите следующий текст запроса, а затем нажмите кнопку "Выполнить ", чтобы создать элемент ToDo.

    {
  "name": "My first ToDo item", 
  "listId": "<ID-of-the-ToDo-list>",
  "state": "todo"
}

    Это действие возвращает следующую задачу ToDo:

    {
  "id": "<ID-of-the-ToDo-item>",
  "listId": "<ID-of-the-ToDo-list>",
  "name": "My first ToDo item",
  "description": null,
  "state": "todo",
  "dueDate": "2023-07-11T13:59:24.9033069+08:00",
  "completedDate": null
}

  3. Выберите API GET /api/simple-todo/lists , а затем выберите "Выполнить " для запроса списков ToDo. Это действие возвращает следующие списки ToDo:

    [
  {
    "id": "<ID-of-the-ToDo-list>",
    "name": "My List",
    "description": null
  }
]

  4. Выберите API GET /api/simple-todo/list/{listId}/items , а затем нажмите кнопку "Попробовать". В поле listId введите созданный ранее идентификатор списка ToDo, а затем нажмите кнопку "Выполнить ", чтобы запросить элементы ToDo. Это действие возвращает следующую задачу ToDo:

    [
  {
    "id": "<ID-of-the-ToDo-item>",
    "listId": "<ID-of-the-ToDo-list>",
    "name": "My first ToDo item",
    "description": null,
    "state": "todo",
    "dueDate": "2023-07-11T13:59:24.903307+08:00",
    "completedDate": null
  }
]

  5. Выберите API PUT /api/simple-todo/lists/{listId}/items/{itemId}, а затем нажмите кнопку "Попробовать". В поле listId введите идентификатор списка ToDo. Для itemId введите идентификатор элемента ToDo, введите следующий текст запроса, а затем нажмите кнопку "Выполнить ", чтобы обновить элемент ToDo.

    {
  "id": "<ID-of-the-ToDo-item>",
  "listId": "<ID-of-the-ToDo-list>",
  "name": "My first ToDo item",
  "description": "Updated description.",
  "dueDate": "2023-07-11T13:59:24.903307+08:00",
  "state": "inprogress"
}

    Это действие возвращает следующий обновленный элемент ToDo:

    {
  "id": "<ID-of-the-ToDo-item>",
  "listId": "<ID-of-the-ToDo-list>",
  "name": "My first ToDo item",
  "description": "Updated description.",
  "state": "inprogress",
  "dueDate": "2023-07-11T05:59:24.903307Z",
  "completedDate": null
}

  6. Выберите API DELETE /api/simple-todo/lists/{listId}/items/{itemId}, а затем нажмите кнопку "Попробовать". В поле listId введите идентификатор списка ToDo. В поле itemId введите идентификатор элемента ToDo и выберите "Выполнить ", чтобы удалить элемент ToDo. Вы должны увидеть, что код ответа сервера — 204.

6. Очистка ресурсов

Вы можете удалить группу ресурсов Azure, которая содержит все связанные ресурсы.

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

  1. Найдите группу ресурсов на портале Azure.

  2. В меню навигации выберите группы ресурсов. Затем выберите имя группы ресурсов, например myresourcegroup.

  3. На странице группы ресурсов щелкните Удалить. Введите имя группы ресурсов в текстовом поле, чтобы подтвердить удаление, например myresourcegroup. Затем нажмите кнопку Удалить.

7. Дальнейшие действия

Краткое руководство. Развертывание приложения на основе событий в Azure Spring Apps

Краткое руководство. Развертывание приложений микрослужб в Azure Spring Apps

Структурированный журнал приложений для Azure Spring Apps

Сопоставление существующего личного домена с Azure Spring Apps

Используйте CI/CD с Azure Spring Apps и GitHub Actions

Автоматизация развертываний приложений в Azure Spring Apps

Дополнительные сведения см. в следующих статьях:

  • Last updated on