Začínáme se sadou Azure SDK a Apache Mavenem

V tomto článku se dozvíte, jak pomocí Apache Mavenu vytvářet aplikace pomocí sady Azure SDK pro Javu. V tomto článku nastavíte nový projekt s Mavenem, sestavíte projekty s Mavenem a použijete nástroje nativní bitové kopie GraalVM k vytvoření nativních binárních souborů specifických pro platformu.

Projekt Azure SDK pro Javu obsahuje archetyp Mavenu, který může urychlit spouštění nového projektu. Archetyp Azure SDK pro Javu Maven vytvoří novou aplikaci se soubory a adresářovou strukturou, která se řídí osvědčenými postupy. Konkrétně archetyp Azure SDK pro Javu Maven vytvoří nový projekt Maven s následujícími funkcemi:

• Závislost na nejnovější azure-sdk-bom verzi kusovníku, která zajišťuje, že jsou všechny závislosti pro Sadu Azure SDK pro Javu sladěné a poskytují nejlepší možnosti pro vývojáře.
• Integrovaná podpora kompilace nativních imagí GraalVM
• Podpora generování nového projektu se zadanou sadou klientských knihoven Azure SDK pro Javu
• Integrace s nástroji pro sestavení v sadě Azure SDK pro Javu, která poskytuje analýzu času sestavení projektu, aby se zajistilo dodržování mnoha osvědčených postupů.

Požadavky

• Java Developer Kit verze 8 nebo novější. Pro co nejlepší prostředí doporučujeme verzi 17.
• Apache Maven

Vytvoření nového projektu Maven

Archetyp Azure SDK pro Javu Maven se publikuje v Centru Mavenu. To znamená, že archetyp můžete použít přímo ke spuštění nové aplikace pomocí následujícího příkazu:

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

Po zadání tohoto příkazu se řada výzev zeptá na podrobnosti o projektu, aby archetyp mohl vygenerovat správný výstup za vás. Následující tabulka popisuje vlastnosti, pro které potřebujete zadat hodnoty:

Název	Popis
groupId	(Povinné) Maven groupId , který se má použít v souboru POM vytvořeném pro vygenerovaný projekt.
artifactId	(Povinné) Maven artifactId , který se má použít v souboru POM vytvořeném pro vygenerovaný projekt.
package	(Volitelné) Název balíčku pro vložení vygenerovaného kódu. Odvozeno z groupId toho, jestli není zadané.
azureLibraries	(Volitelné) Seznam knihoven Azure SDK oddělených čárkami pro knihovny Java pomocí ID artefaktů Mavenu Seznam takových ID artefaktů najdete v tématu Vydané verze sady Azure SDK.
enableGraalVM	(Volitelné) False označující, že vygenerovaný soubor Maven POM by neměl obsahovat podporu kompilace aplikace do nativní bitové kopie pomocí GraalVM. V opačném případě je pravda. Výchozí hodnota je true.
javaVersion	(Volitelné) Minimální verze sady JDK, která se má cílit při sestavování vygenerovaného projektu, například 8, 11 nebo 17. Výchozí hodnota je nejnovější verze LTS (aktuálně 17). Minimální hodnota je 8.
junitVersion	(Volitelné) Verze JUnit, která se má zahrnout jako závislost. Výchozí hodnota je 5. Platné hodnoty 4 a 5.

Alternativně můžete tyto hodnoty zadat při volání příkazu archetype zobrazeného dříve. Tento přístup je užitečný například pro účely automatizace. Hodnoty můžete zadat jako parametry pomocí standardní syntaxe Mavenu pro připojení -D k názvu parametru, například:

-DjavaVersion=17

Podpora verzí Javy

Osvědčeným postupem je použití verze Java LTS při nasazování do produkčního prostředí. Ve výchozím nastavení archetyp Azure SDK Maven vybere nejnovější verzi LTS, která aktuálně nastavuje směrný plán Javy 17. Výchozí chování ale můžete přepsat nastavením parametru javaVersion .

Použití nástroje pro sestavení Sady Azure SDK pro Javu

Projekt Azure SDK pro Javu dodává nástroj pro sestavení Maven, který můžete zahrnout do svých projektů. Tento nástroj běží místně a nepřenáší žádná data do Microsoftu. Nástroj můžete nakonfigurovat tak, aby vygeneroval sestavu nebo selhal při splnění určitých podmínek, což je užitečné k zajištění dodržování mnoha osvědčených postupů, jako jsou například následující postupy:

• Ověření správného použití kusovníku azure-sdk-for-java , včetně použití nejnovější verze, a spoléhání se na něj k definování verzí závislostí v azure SDK pro klientské knihovny Java. Další informace najdete v části Přidání sady Azure SDK pro Javu do existující části projektu .
• Ověření, že se historické klientské knihovny Azure nepoužívají, když existují novější a vylepšené verze.

Sestava také poskytuje přehled o využití beta rozhraní API.

Nástroj sestavení můžete nakonfigurovat v souboru Maven POM projektu, jak je znázorněno v následujícím příkladu. Zástupný symbol nezapomeňte nahradit {latest_version} nejnovější verzí uvedenou online.

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

Po přidání nástroje sestavení do projektu Maven můžete nástroj spustit voláním mvn compile azure:run. V závislosti na zadané konfiguraci můžete očekávat, že se zobrazí chyby sestavení nebo vygenerované soubory sestav, které vás mohou informovat o potenciálních problémech, než se stanou vážnější. Tento nástroj doporučujeme spustit jako součást kanálu CI/CD. S vývojem nástroje pro sestavení publikujeme nové verze a doporučujeme, aby vývojáři podle potřeby často kontrolují nové verze a aktualizovali je.

Nástroj pro sestavení je možné nakonfigurovat tak, aby povolil nebo zakázal konkrétní funkce. Pro tuto konfiguraci přidejte configuration oddíl v souboru XML, který jste si zobrazili dříve. V této části nakonfigurujte nastavení uvedená v následující tabulce. Jakákoli konfigurace, která není explicitně zmíněna, přebírá výchozí hodnotu zadanou v tabulce.

Název vlastnosti	Výchozí hodnota	Popis
validateAzureSdkBomUsed	true	Zajišťuje, aby projekt správně odkazoval na kusovníky azure-sdk-for-java, aby závislosti klientské knihovny Azure SDK pro Javu mohly převzít jejich verze z kusovníku.
validateLatestBomVersionUsed	true	Zajišťuje, aby závislosti byly aktuální, a to tak, že sestavuje zpět (nebo selhává sestavení), pokud existuje novější kusovník azure-sdk-for-java. Nejnovější verzi najdete online.
validateBomVersionsAreUsed	true	Zajišťuje, že pokud je závislost k dispozici z kusovníku azure-sdk-for-java, verze se nepřepíše ručně.
validateNoDeprecatedMicrosoftLibraryUsed	true	Zajišťuje, že projekt nevyužívá knihovny Azure předchozí generace. Použití nových a předchozích knihoven v jednom projektu pravděpodobně nezpůsobuje žádný problém, ale výsledkem je neoptimální vývojářské prostředí.
validateNoBetaLibraryUsed	false (nepravda)	Některé klientské knihovny Azure SDK pro Javu mají beta verze s řetězci verzí ve formuláři x.y.z-beta.n. Povolením této funkce zajistíte, že se nepoužívají žádné beta knihovny.
validateNoBetaApiUsed	true	Klientské knihovny Azure SDK pro Javu někdy obsahují verze GA s metodami anotovanými metodami @Beta. Tato kontrola zjistí, jestli se některé z těchto metod používají.
sendToMicrosoft	true	Určuje, jestli se má sestava sestavení posílat Microsoftu pro účely telemetrie. Pomůžete tak vývojovému týmu určit prioritu dokumentace, ukázek a vylepšených rozhraní API pro usnadnění práce. Nebyl odeslán žádný identifikovatelný obsah uživatele.
reportFile	-	(Volitelné) Určuje umístění pro zápis sestavy sestavení do formátu JSON. Pokud není zadána žádná sestava, zapíše se žádná sestava a v terminálu se zobrazí souhrn sestavení nebo příslušná selhání sestavení.

Přidání sady Azure SDK pro Javu do existujícího projektu

Aby se správa verzí závislostí zjednodušil, tým Azure SDK pro Javu každý měsíc publikuje kusovníky klienta Azure SDK pro Javu. Tento soubor BOM obsahuje všechny obecně dostupné sady Azure SDK (GA) pro klientské balíčky Java s jejich kompatibilní verzí závislostí.

Pokud chcete použít verze závislostí pro klientskou knihovnu Azure SDK pro Javu, která je v kusovníku, vložte do souboru pom.xml projektu následující fragment kódu. {bom_version_to_target} Zástupný symbol nahraďte nejnovější verzí sady Azure SDK pro kusovníky Javy. {artifactId} Zástupný symbol nahraďte názvem balíčku sady SDK služby 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>

Všechny verze klientského kusovníku sady Azure SDK pro Javu najdete na bom azure-sdk-bom. Pokud chcete využívat nejnovější funkce sady Azure SDK pro klientské knihovny Java, doporučujeme použít nejnovější verzi.

Použití Mavenu k definování závislostí projektu může zjednodušit správu projektů. Díky archetypu Azure SDK a Sady Azure SDK Maven můžete svůj projekt urychlit a zároveň mít větší jistotu o verzích závislostí v dlouhodobém horizontu. Doporučujeme použít kusovník, abyste měli závislosti zarovnané a aktuální.

Kromě přidání kusovníku sady Azure SDK doporučujeme zahrnout také nástroj pro sestavení Sady Azure SDK pro Javu. Tento nástroj pomáhá diagnostikovat řadu běžných problémů při vytváření aplikací, jak je popsáno výše v tomto článku.

Zahrnutí balíčku, který není součástí kusovníku

Azure SDK pro klienta Java zahrnuje pouze obecně dostupné knihovny (GA). Pokud chcete záviset na balíčku, který je stále v beta verzi nebo na verzi knihovny, která se liší od verze zahrnuté v kusovníku, můžete společně s groupId částí závislostí a artifactId v části závislostí zadat verzi závislostí Maven. Můžete se rozhodnout mít závislosti, které používají verze kusovníku a závislosti s přepsánými verzemi ve stejném souboru POM projektu, jak je znázorněno v následujícím příkladu:

<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>

Pokud použijete tento přístup a zadáte verze přímo v projektu, může dojít ke konfliktům verzí závislostí. K těmto konfliktům dochází, protože různé balíčky můžou záviset na různých verzích běžných závislostí a tyto verze nemusí být vzájemně kompatibilní. Když dojde ke konfliktům, můžete zaznamenat nežádoucí chování v době kompilace nebo za běhu. Pokud to není nutné, doporučujeme spoléhat se na verze, které jsou v kusovníku sady Azure SDK. Další informace o řešení závislostí při použití sady Azure SDK pro Javu najdete v tématu Řešení konfliktů verzí závislostí.

Vytvoření nativní image pomocí GraalVM

GraalVM můžete použít k vytvoření nativní image aplikace v Javě. GraalVM předem zkompiluje kód Java do nativního strojového kódu, což může v určitých situacích přinést výrazné zvýšení výkonu. Sada Azure SDK pro Javu poskytuje potřebná metadata v každé z jejích klientských knihoven pro podporu kompilace nativních imagí GraalVM.

Abyste mohli začít, musíte nainstalovat GraalVM a připravit vývojový systém na kompilaci nativních imagí. Proces instalace pro GraalVM je jednoduchý a dokumentace k GraalVM obsahuje podrobné pokyny k instalaci GraalVM a použití GraalVM k instalaci nativní image. Pečlivě nainstalujte potřebné nativní kompilátory pro váš operační systém podle pokynů v části Požadavky.

Archetyp Azure SDK pro Javu Maven může nakonfigurovat sestavení tak, aby podporovalo kompilaci nativních imagí GraalVM, ale můžete ho také přidat do existujícího sestavení Maven. Pokyny pro Maven najdete na webu GraalVM.

Dále jste připraveni spustit sestavení nativní bitové kopie. Standardní nástroje Maven můžete použít k použití nativní image GraalVM. Pro Maven použijte následující příkaz:

mvn clean package -Pnative

Po spuštění tohoto příkazu GraalVM vypíše nativní spustitelný soubor pro platformu, na které běží. Spustitelný soubor se zobrazí v adresáři Maven /target projektu. Teď můžete spustit aplikaci s tímto spustitelným souborem a měla by fungovat podobně jako standardní aplikace v Javě.

Další kroky

Začínáme s rozšířeními Azure pro IntelliJ a Eclipse