Introduzione ad Azure SDK e Apache Maven

Articolo
01/20/2025

Questo articolo illustra come usare Apache Maven per creare applicazioni con Azure SDK per Java. In questo articolo si configura un nuovo progetto con Maven, si compilano progetti con Maven e si usano gli strumenti di immagine nativa graalVM per creare file binari nativi specifici della piattaforma.

Il progetto Azure SDK per Java include un archetipo Maven che può accelerare l'avvio di un nuovo progetto. L'SDK di Azure per l'archetipo di Java Maven crea una nuova applicazione, con file e una struttura di directory che segue le procedure ottimali. In particolare, l'archetipo di Maven di Azure SDK for Java crea un nuovo progetto Maven con le seguenti funzionalità:

Una dipendenza dalla versione più recente azure-sdk-bom BOM, che garantisce che tutte le dipendenze per Azure SDK per Java siano allineate e offre la migliore esperienza per sviluppatori possibile.
Supporto predefinito per la compilazione di immagini native GraalVM.
Supporto per la generazione di un nuovo progetto con un set specificato di librerie client di Azure SDK per Java.
Integrazione con gli strumenti di compilazione di Azure SDK per Java, che fornisce l'analisi in fase di compilazione del progetto per garantire che vengano seguite molte procedure consigliate.

Prerequisiti

Java Developer Kit, versione 8 o successiva. Per un'esperienza ottimale, è consigliabile usare la versione 17.
Apache Maven

Creare un nuovo progetto Maven

L'archetipo Azure SDK per Java Maven viene pubblicato in Maven Central. Ciò significa che è possibile usare direttamente l'archetipo per eseguire il bootstrap di una nuova applicazione con il comando seguente:

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

Dopo aver immesso questo comando, una serie di richieste chiede dettagli sul tuo progetto in modo che l'archetipo possa generare l'output corretto per te. Nella tabella seguente vengono descritte le proprietà per cui è necessario specificare i valori:

Nome	Descrizione
`groupId`	(Obbligatorio) Il Maven `groupId` da usare nel file POM creato per il progetto che è stato generato.
`artifactId`	(Obbligatorio) Il Maven `artifactId` da usare nel file POM creato per il progetto generato.
`package`	(Facoltativo) Nome del pacchetto in cui inserire il codice generato. Dedotto dal `groupId` se non è specificato.
`azureLibraries`	(Facoltativo) Elenco delimitato da virgole delle librerie di Azure SDK per Java, usando i loro ID degli artefatti Maven. Per un elenco di tali ID artefatti, vedere Rilasci di Azure SDK.
`enableGraalVM`	(Facoltativo) `false` per indicare che il file POM maven generato non deve includere il supporto per la compilazione dell'applicazione in un'immagine nativa usando GraalVM; in caso contrario, `true`. Il valore predefinito è `true`.
`javaVersion`	(Facoltativo) Versione minima di JDK di destinazione durante la compilazione del progetto generato, ad esempio `8`, `11`o `17`. Il valore predefinito è la versione LTS più recente (attualmente `17`). Il valore minimo è `8`.
`junitVersion`	(Facoltativo) Versione di JUnit da includere come dipendenza. Il valore predefinito è `5`. Valori validi `4` e `5`.

In alternativa, è possibile specificare questi valori quando si chiama il comando archetipo illustrato in precedenza. Questo approccio è utile, ad esempio, a scopo di automazione. È possibile specificare i valori come parametri usando la sintassi Maven standard dell'aggiunta di -D al nome del parametro, ad esempio:

-DjavaVersion=17

Supporto della versione Java

Come procedura consigliata, è consigliabile usare una versione Java LTS durante la distribuzione nell'ambiente di produzione. Per impostazione predefinita, l'archetipo Maven di Azure SDK seleziona la versione LTS più recente, che attualmente imposta una baseline Java 17. Tuttavia, è possibile eseguire l'override del comportamento predefinito impostando il parametro javaVersion.

Usare lo strumento di compilazione azure SDK per Java

Il progetto Azure SDK per Java include uno strumento di compilazione Maven che è possibile includere nei progetti. Questo strumento viene eseguito localmente e non trasmette dati a Microsoft. È possibile configurare lo strumento per generare un report o interrompere la compilazione quando vengono soddisfatte determinate condizioni, utile per garantire la conformità a numerose procedure consigliate, ad esempio le procedure seguenti:

Convalida del corretto utilizzo del BOM azure-sdk-for-java, incluso l'impiego della versione più recente, e del suo utilizzo per definire le versioni delle dipendenze nelle librerie client dell'Azure SDK per Java. Per altre informazioni, vedere la sezione Aggiungere Azure SDK per Java a un progetto esistente.
Verifica che non vengano utilizzate le versioni storiche delle librerie client di Azure quando esistono versioni più recenti e migliorate.

Il report fornisce anche informazioni dettagliate sull'uso delle API beta.

È possibile configurare lo strumento di compilazione in un file POM del progetto Maven, come illustrato nell'esempio seguente. Assicurarsi di sostituire il segnaposto {latest_version} con la versione più recente disponibile online.

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

Dopo aver aggiunto lo strumento di compilazione in un progetto Maven, è possibile eseguire lo strumento chiamando mvn compile azure:run. A seconda della configurazione fornita, è possibile prevedere che vengano visualizzati errori di compilazione o file di report generati che possono informare l'utente sui potenziali problemi prima che diventino più gravi. È consigliabile eseguire questo strumento come parte della pipeline CI/CD. Man mano che lo strumento di compilazione si evolve, verranno pubblicate nuove versioni ed è consigliabile che gli sviluppatori controllare frequentemente le nuove versioni e aggiornare in base alle esigenze.

È possibile configurare lo strumento di compilazione per abilitare o disabilitare funzionalità specifiche. Per questa configurazione, aggiungere una sezione configuration nel codice XML illustrato in precedenza. In questa sezione configurare le impostazioni illustrate nella tabella seguente. Qualsiasi configurazione non indicata in modo esplicito accetta il valore predefinito specificato nella tabella.

Nome della proprietà	Valore predefinito	Descrizione
`validateAzureSdkBomUsed`	vero	Assicura che il progetto abbia il azure-sdk-for-java BOM a cui si fa riferimento in modo appropriato, in modo che le dipendenze della libreria client di Azure SDK per Java possano prendere le versioni dal BOM.
`validateLatestBomVersionUsed`	vero	Garantisce che le dipendenze vengano mantenute aggiornate segnalando (o non riuscita la compilazione) se esiste un azure-sdk-for-java BOM. È sempre possibile trovare la versione più recente online.
`validateBomVersionsAreUsed`	vero	Garantisce che, quando una dipendenza è disponibile dal azure-sdk-for-java BOM, la versione non venga sovrascritta manualmente.
`validateNoDeprecatedMicrosoftLibraryUsed`	vero	Garantisce che il progetto non usi le librerie di Azure di generazione precedente. L'uso delle librerie di nuova e precedente generazione in un singolo progetto è improbabile che causi problemi, ma comporta un'esperienza di sviluppo non ottimale.
`validateNoBetaLibraryUsed`	falso	Alcune librerie client di Azure SDK per Java hanno versioni beta, con stringhe di versione nel formato `x.y.z-beta.n`. L'abilitazione di questa funzionalità garantisce che non vengano usate librerie beta.
`validateNoBetaApiUsed`	vero	Le librerie client di Azure SDK per Java talvolta hanno versioni GA con metodi annotati con `@Beta`. Questo controllo cerca di verificare se vengono usati metodi di questo tipo.
`sendToMicrosoft`	vero	Specifica se inviare il report di compilazione a Microsoft per scopi di telemetria. Ciò consente al team di sviluppo di definire le priorità per la documentazione, gli esempi e le API di praticità migliorate. Non viene inviato alcun contenuto identificabile dall'utente.
`reportFile`	-	(Facoltativo) Specifica il percorso in cui scrivere il report di compilazione, in formato JSON. Se non specificato, nel terminale non viene scritto alcun report e viene visualizzato un riepilogo della compilazione o degli errori di compilazione appropriati.

Aggiungere Azure SDK per Java a un progetto esistente

Per semplificare la gestione delle versioni delle dipendenze, il team di Azure SDK per Java pubblica il bom client di Azure SDK per Java ogni mese. Questo file DBA include tutti i pacchetti client azure SDK disponibili a livello generale per Java con la versione compatibile delle dipendenze.

Per usare le versioni delle dipendenze per una libreria client di Azure SDK per Java presente nella distinta base (BOM), includere il frammento di codice seguente nel file di pom.xml del progetto. Sostituire il segnaposto {bom_version_to_target} con la versione più recente del BOM AWS SDK per Java. Sostituire il segnaposto {artifactId} con il nome del pacchetto azure service SDK.

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

È possibile trovare tutte le versioni dell'elenco componenti (BOM) del client Azure SDK per Java all'indirizzo azure-sdk-bom. È consigliabile usare la versione più recente per sfruttare le funzionalità più recenti delle librerie client di Azure SDK per Java.

L'uso di Maven per definire le dipendenze del progetto può semplificare la gestione dei progetti. Con il BOM di Azure SDK e con l'archetipo Maven di Azure SDK, è possibile accelerare il progetto, essendo più sicuri riguardo al versionamento delle dipendenze a lungo termine. È consigliabile usare la BOM per mantenere le dipendenze allineate e aggiornate.

Oltre ad aggiungere il BOM (Bill of Materials) di Azure SDK, consigliamo anche di includere lo strumento di compilazione Azure SDK per Java. Questo strumento consente di diagnosticare molti problemi comunemente riscontrati durante la compilazione di applicazioni, come descritto in precedenza in questo articolo.

Includere un pacchetto al di fuori della distinta base

La BOM del cliente Azure SDK per Java include solo librerie generalmente disponibili. Se si vuole dipendere da un pacchetto ancora in versione beta o da una versione di libreria diversa da quella inclusa nel BOM, è possibile specificare la versione delle dipendenze Maven insieme a groupId e artifactId nella sezione delle dipendenze. È possibile scegliere di avere dipendenze che usano le versioni bom e le dipendenze con versioni sottoposte a override nello stesso file POM del progetto, come illustrato nell'esempio seguente:

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

Se si usa questo approccio e si specificano le versioni direttamente nel progetto, è possibile che si verifichino conflitti di versione delle dipendenze. Questi conflitti si verificano perché pacchetti diversi possono dipendere da versioni diverse delle dipendenze comuni e queste versioni potrebbero non essere compatibili tra loro. Quando si verificano conflitti, è possibile riscontrare un comportamento indesiderato in fase di compilazione o runtime. È consigliabile basarsi sulle versioni presenti nella distinta base di Azure SDK, a meno che non sia necessario. Per altre informazioni sulla gestione delle dipendenze quando si usa Azure SDK per Java, vedere Risolvere i conflitti di versione delle dipendenze.

Creare un'immagine nativa con GraalVM

È possibile usare GraalVM per creare un'immagine nativa di un'applicazione Java. GraalVM compila il codice Java in anticipo nel codice del computer nativo, che può produrre miglioramenti significativi delle prestazioni in determinate situazioni. L'Azure SDK per Java fornisce i metadati necessari in ciascuna delle sue librerie client per supportare la compilazione di immagini native GraalVM.

Per iniziare, è necessario installare GraalVM e preparare il sistema di sviluppo per la compilazione di immagini native. Il processo di installazione di GraalVM è semplice e la documentazione di GraalVM fornisce istruzioni dettagliate per l'installazione di GraalVM e usando GraalVM per installare l'immagine nativa. Seguire attentamente la sezione prerequisiti per installare i compilatori nativi necessari per il sistema operativo.

Il archetipo Azure SDK per Java Maven può configurare il tuo build per supportare la compilazione di immagini native con GraalVM, ma è anche possibile aggiungere tale supporto a una build Maven esistente. È possibile trovare le istruzioni per Maven sul sito Web GraalVM.

A questo punto, sei pronto per eseguire una creazione di immagini native. È possibile usare gli strumenti Maven standard per usare l'immagine nativa GraalVM. Per Maven, usare il comando seguente:

mvn clean package -Pnative

Dopo aver eseguito questo comando, GraalVM restituisce un eseguibile nativo per la piattaforma in cui è in esecuzione. L'eseguibile viene visualizzato nella directory Maven /target del tuo progetto. È ora possibile eseguire l'applicazione con questo file eseguibile e dovrebbe essere eseguita in modo analogo a un'applicazione Java standard.

Passaggi successivi

Introduzione alle estensioni di Azure per IntelliJ ed Eclipse

Condividi tramite