Начало работы с Azure SDK и Maven

В этой статье показано, как использовать Apache Maven для создания приложений с помощью пакета SDK Azure для Java. В этой статье вы настраиваете новый проект с помощью Maven, создаёте проекты с помощью Maven и используете инструменты GraalVM для создания образов, чтобы создать двоичные файлы, специфичные для платформы.

Проект Пакета SDK Azure для Java включает архетип Maven, который может ускорить загрузку нового проекта. SDK Azure для Java Maven шаблон создает новое приложение с файлами и структурой каталогов, которая соответствует лучшим практикам. В частности, архетип Пакета SDK Azure для Java Maven создает новый проект Maven со следующими функциями:

• Зависимость от последней версии azure-sdk-bom BOM, которая гарантирует выравнивание всех зависимостей для пакета SDK Azure для Java и обеспечивает оптимальный интерфейс разработчика.
• Встроенная поддержка компиляции собственных образов GraalVM.
• Поддержка создания нового проекта с указанным набором azure SDK для клиентских библиотек Java.
• Интеграция с инструментами сборки Azure SDK для Java, которая обеспечивает анализ на этапе сборки проекта, чтобы гарантировать соблюдение множества лучших практик.

Необходимые условия

• пакет средств разработчика Javaверсии 8 или более поздней. Для наилучшей работы используйте версию 17.
• Apache Maven

Создание проекта Maven

Архетип Maven для Azure SDK for Java доступен в репозитории Maven Central. Архетип можно использовать непосредственно для загрузки нового приложения, выполнив следующую команду:

mvn archetype:generate \
    -DarchetypeGroupId=com.azure.tools \
    -DarchetypeArtifactId=azure-sdk-archetype

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

Имя	Описание
groupId	(обязательно) Maven groupId использовать в файле POM, созданном для созданного проекта.
artifactId	(обязательно) Maven artifactId использовать в файле POM, созданном для созданного проекта.
package	(Необязательно) Имя пакета, в который нужно поместить созданный код. Если не указано, выводится из groupId.
azureLibraries	(Необязательно) Разделенный запятыми список библиотек SDK Azure для Java с использованием их идентификаторов артефактов Maven. См. список таких идентификаторов артефактов в выпусках Azure SDK .
enableGraalVM	(Необязательно) false, чтобы указать, что созданный POM-файл Maven не должен включать поддержку компиляции приложения на собственный образ с помощью GraalVM; в противном случае true. Значение по умолчанию — true.
javaVersion	(Необязательно) Минимальная версия JDK для целевого объекта при создании созданного проекта, например 8, 11или 17. Значением по умолчанию является последний выпуск LTS (в настоящее время 17). Минимальное значение равно 8.
junitVersion	(Необязательно) Версия JUnit, включаемая в качестве зависимости. Значение по умолчанию — 5. Допустимые значения — 4 и 5.

Кроме того, эти значения можно указать при вызове команды архетипа, показанной ранее. Этот подход полезен, например, для целей автоматизации. Значения можно указать в качестве параметров с помощью стандартного синтаксиса Maven для добавления -D к имени параметра, например:

-DjavaVersion=17

Поддержка версий Java

Рекомендуется использовать выпуск LTS Java при развертывании в рабочей среде. По умолчанию архетип Azure SDK Maven выбирает последний выпуск LTS, который в настоящее время задает базовый план Java 17. Однако можно переопределить поведение по умолчанию, задав параметр javaVersion.

Использование средства сборки пакета SDK Azure для Java

Azure SDK для проекта Java включает средство сборки Maven, которое можно добавить в проекты. Это средство выполняется локально и не отправляет данные в Microsoft. Инструмент можно настроить так, чтобы он создавал отчет или помечал сборку как неуспешную при соблюдении определенных условий. Эта функция помогает обеспечить соответствие рекомендациям, таким как следующие методики:

• Проверка правильного использования azure-sdk-for-java BOM, включая использование последней версии и использование ее для определения версий зависимостей в клиентских библиотеках Пакета SDK Azure для Java. Дополнительные сведения см. в разделе Добавление пакета SDK Azure для Java в существующий проект.
• Проверка того, что исторические Azure клиентские библиотеки не используются при наличии более новых и улучшенных версий.

В отчете также содержатся сведения об использовании бета-API.

Средство сборки можно настроить в файле POM проекта Maven, как показано в следующем примере. Обязательно замените заполнитель {latest_version} на последнюю версию , опубликованную в интернете.

<build>
  <plugins>
    <plugin>
      <groupId>com.azure.tools</groupId>
      <artifactId>azure-sdk-build-tool</artifactId>
      <version>{latest_version}</version>
    </plugin>
  </plugins>
</build>

После добавления средства сборки в проект Maven запустите средство, вызвав средство mvn compile azure:run. В зависимости от предоставленной конфигурации можно ожидать, что будут отображаться сбои сборки или файлы отчетов, которые могут сообщить о потенциальных проблемах, прежде чем они становятся более серьезными. Запустите этот инструмент как часть конвейера CI/CD. По мере развития средства сборки команда разработчиков публикует новые выпуски. Регулярно проверяйте наличие новых версий и при необходимости обновляйте.

Средство сборки можно настроить для включения или отключения определенных функций. Для этой конфигурации добавьте раздел configuration в XML, показанный ранее. В этом разделе настройте параметры, показанные в следующей таблице. Любая конфигурация, которая явно не упоминается, принимает значение по умолчанию, указанное в таблице.

Имя свойства	Значение по умолчанию	Описание
validateAzureSdkBomUsed	истинный	Гарантирует, что проект надлежащим образом ссылается на azure-sdk-for-java BOM, чтобы зависимости клиентских библиотек Azure SDK для Java получали свои версии из BOM.
validateLatestBomVersionUsed	истинный	Гарантирует, что зависимости остаются актуальными, сообщая об этом (или завершая сборку с ошибкой), если доступна более новая azure-sdk-for-java BOM. Вы всегда можете найти последнюю версию в интернете.
validateBomVersionsAreUsed	истинный	Гарантирует, что, если зависимость доступна в azure-sdk-for-java BOM, её версия не переопределяется вручную.
validateNoDeprecatedMicrosoftLibraryUsed	истинный	Гарантирует, что проект не использует библиотеки Azure предыдущего поколения. Использование новых и предыдущих библиотек поколения в одном проекте вряд ли приведет к возникновению проблем, но приводит к неоптимальному интерфейсу разработчика.
validateNoBetaLibraryUsed	ложный	Некоторые клиентские библиотеки Azure SDK для Java имеют бета-версии с строками версий в форме x.y.z-beta.n. Включение этой функции гарантирует, что не используются бета-библиотеки.
validateNoBetaApiUsed	истинный	Клиентские библиотеки Azure SDK для Java иногда имеют стабильные выпуски с методами, аннотированными как @Beta. Эта проверка проверяет, используются ли такие методы.
sendToMicrosoft	истинный	Указывает, следует ли отправлять отчет сборки в корпорацию Майкрософт для целей телеметрии. Этот отчет поможет команде разработчиков определить приоритеты документации, примеров и улучшенных api-интерфейсов удобства. Контент, который может идентифицировать пользователя, не отправляется.
reportFile	-	(Необязательно) Указывает расположение, в котором будет записан отчет о сборке в формате JSON. Если ничего не указано, отчет не создается, а в терминале отображается сводка сборки или информация о соответствующих сбоях сборки.

Добавление пакета SDK Azure для Java в существующий проект

Чтобы упростить управление версиями зависимостей, команда Azure SDK для Java ежемесячно публикует клиентский BOM Azure SDK для Java. Этот файл BOM включает все общедоступные клиентские пакеты Azure SDK для Java с совместимыми версиями зависимостей.

Чтобы использовать версии зависимостей для клиентской библиотеки Azure SDK для Java, указанной в BOM, добавьте следующий фрагмент кода в файл pom.xml проекта. Замените заполнитель {bom_version_to_target}последним выпуском пакета SDK Azure для Java BOM. Замените заполнитель {artifactId} именем пакета SDK службы Azure.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-sdk-bom</artifactId>
      <version>{bom_version_to_target}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>{artifactId}</artifactId>
  </dependency>
</dependencies>

Все выпуски Azure SDK для клиента Java можно найти на azure-sdk-bom. Используйте последнюю версию, чтобы воспользоваться новейшими функциями Azure SDK для клиентских библиотек Java.

С помощью Maven для определения зависимостей проекта можно упростить управление проектами. Используя Azure SDK BOM и Maven-архетип для Azure SDK, вы можете ускорить разработку проекта и при этом быть увереннее в долгосрочном управлении версиями зависимостей. Используйте BOM, чтобы зависимости оставались согласованными и актуальными.

Помимо добавления Azure SDK BOM, также включите Azure SDK для средства сборки Java. Это средство помогает диагностировать многие проблемы, часто возникающие при создании приложений, как описано ранее в этой статье.

Включите пакет, который не является частью спецификации материалов (BOM)

Azure SDK для Java клиентского BOM включает только общедоступные библиотеки. Если вы хотите использовать зависимость от пакета, который всё ещё находится на стадии бета-версии, или от версии библиотеки, отличной от включённой в BOM, укажите версию зависимости Maven вместе с groupId и artifactId в разделе зависимостей. Можно включить зависимости, использующие версии BOM, и зависимости с переопределёнными версиями в одном POM-файле проекта, как это показано в следующем примере:

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventhubs</artifactId> <!-- Use the dependency version that is in the BOM -->
  </dependency>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-servicebus</artifactId>
    <version>7.4.0</version> <!-- Override the Service Bus dependency version specified in the BOM -->
  </dependency>
</dependencies>

Если вы используете этот подход и задаете версии непосредственно в проекте, могут возникнуть конфликты версий зависимостей. Эти конфликты возникают, так как разные пакеты могут зависеть от разных версий распространенных зависимостей, и эти версии могут быть несовместимы друг с другом. При возникновении конфликтов можно столкнуться с нежелательным поведением во время компиляции или во время выполнения. Используйте версии, входящие в Azure SDK BOM, если нет необходимости в других. Дополнительные сведения о работе с зависимостями при использовании пакета SDK Azure для Java см. в статье Устранение конфликтов версий зависимостей.

Создание собственного образа с помощью GraalVM

Вы можете использовать GraalVM для создания собственного образа приложения Java. GraalVM компилирует код Java заранее в машинный код, что может повысить производительность в определенных ситуациях. Пакет SDK Azure для Java предоставляет необходимые метаданные в каждой из клиентских библиотек для поддержки компиляции собственных образов GraalVM.

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

Пакет SDK Azure для Java Maven archetype может настроить сборку для поддержки компиляции собственных образов GraalVM, но ее также можно добавить в существующую сборку Maven. Инструкции по Maven можно найти на веб-сайте GraalVM.

Затем вы готовы выполнить сборку нативного образа. Вы можете использовать стандартные средства Maven для использования собственного образа GraalVM. Для Maven используйте следующую команду:

mvn clean package -Pnative

После выполнения этой команды GraalVM выводит собственный исполняемый файл для платформы, на которой он работает. Исполняемый файл находится в каталоге Maven /target вашего проекта. Теперь вы можете запустить приложение с этим исполняемым файлом, и он должен выполняться аналогично стандартному приложению Java.

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

Начало работы с расширениями Azure для IntelliJ и Eclipse