Avvio rapido: estensione Quarkus per Archiviazione BLOB di Azure

Inizia con l'estensione Quarkus per l'Archiviazione Blob di Azure per gestire blob e contenitori. In questo articolo vengono eseguiti i passaggi per provare il codice di esempio per le attività di base.

Documentazione di riferimento | Codice sorgente | della libreriaPacchetto (Maven) | Esempio

Prerequisiti

Account Azure con una sottoscrizione attiva: creare gratuitamente un account.
Interfaccia della riga di comando di Azure: installa la versione 2.62.0 o successiva per eseguire i comandi CLI di Azure.
Account di archiviazione di Azure: creare un account di archiviazione.
Java Development Kit (JDK) versione 17 o successiva.
Apache Maven.

Configurazione

Questa sezione illustra come preparare un progetto per l'uso delle estensioni Quarkus per Archiviazione BLOB di Azure.

Scaricare l'applicazione di esempio

L'applicazione di esempio usata in questa guida introduttiva è un'applicazione Quarkus di base.

Usare Git per scaricare una copia dell'applicazione nell'ambiente di sviluppo e passare alla storage-blob-quarkus directory .

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB

Le richieste dell'applicazione ad Azure Blob Storage richiedono autorizzazione. L'uso di DefaultAzureCredential e della libreria client di identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice, inclusa l'archiviazione BLOB. L'estensione Quarkus per i servizi di Azure supporta questo approccio.

DefaultAzureCredential è un'implementazione della catena di credenziali fornita dalla libreria client di Identità di Azure per Java. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

L'ordine e le posizioni in cui DefaultAzureCredential cercare le credenziali sono disponibili nella panoramica della libreria di identità di Azure.

In questa guida rapida, l'app esegue l'autenticazione utilizzando le credenziali di accesso della CLI di Azure durante l'esecuzione in locale. Dopo la distribuzione in Azure, l'app può quindi usare un'identità gestita. Questa transizione tra ambienti non richiede modifiche al codice.

Assegnare ruoli all'account utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account che accede ai dati di tipo BLOB disponga delle autorizzazioni corrette. Per leggere e scrivere dati BLOB, è necessario disporre del ruolo Collaboratore ai dati dei BLOB di archiviazione. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Amministratore accesso utenti o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli del Controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per ulteriori informazioni sul ruolo di Collaboratore ai dati BLOB, vedere Collaboratore ai dati BLOB. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere Comprendere l'ambito per Azure RBAC.

In questo scenario si assegneranno le autorizzazioni all'account utente con ambito corrispondente all'account utente, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo Collaboratore ai dati dei BLOB di archiviazione all'account utente, in modo da fornire l'accesso in lettura e scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

Nel portale di Azure, individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.
Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.
Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.
Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.
Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Collaboratore ai dati dei BLOB di archiviazione e selezionare il risultato corrispondente, quindi scegliere Avanti.
In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.
Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.
Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Per assegnare un ruolo a livello di risorsa usando l'interfaccia della riga di comando di Azure, è prima necessario recuperare l'ID risorsa usando il az storage account show comando . È possibile filtrare le proprietà di output usando il parametro --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Copiare l'output Id ottenuto con il comando precedente. È quindi possibile assegnare ruoli usando il comando az role dell'interfaccia della riga di comando di Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Per assegnare un ruolo a livello di risorsa usando Azure PowerShell, è prima necessario recuperare l'ID risorsa usando il comando Get-AzResource.

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Copiare il valore Id ottenuto con il comando precedente. È quindi possibile assegnare ruoli usando il comando New-AzRoleAssignment in PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

È possibile autorizzare l'accesso ai dati nell'account di archiviazione seguendo questa procedura:

Assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo nell'account di archiviazione. L'esempio seguente illustra come eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure:
```
az login
```
Assicurati di fornire l'endpoint del tuo account Azure Blob Storage. L'esempio seguente illustra come impostare l'endpoint usando la variabile QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT di ambiente tramite l'interfaccia della riga di comando di Azure. Sostituire <resource-group-name> e <storage-account-name> con il gruppo di risorse e i nomi degli account di archiviazione prima di eseguire il comando :
```
export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)
```

Annotazioni

Quando viene distribuita in Azure, è necessario abilitare l'identità gestita nell'app e configurare l'account di archiviazione per consentire la connessione dell'identità gestita. Per altre informazioni sulla configurazione di questa connessione tra i servizi di Azure, vedere Autenticare le applicazioni Java ospitate in Azure.

Esegui l'esempio

L'esempio di codice esegue le azioni seguenti:

Inserisce un oggetto client già autorizzato per l'accesso ai dati utilizzando l'estensione Quarkus per Azure Blob Storage tramite DefaultAzureCredential.
Crea un contenitore in un account di archiviazione.
Carica un blob nel contenitore.
Elenca i blob nel contenitore.
Scarica i dati blob nel file system locale.
Elimina le risorse BLOB e contenitore create dall'app.
Elimina l'origine locale e i file scaricati.

Eseguire l'applicazione in modalità JVM usando il comando seguente:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

L'output dell'app è simile all'esempio seguente (i valori UUID omessi per la leggibilità):

Uploading to Blob storage as blob:
        https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Prima di iniziare il processo di pulizia, controllare la cartella dei dati per i due file. È possibile confrontarli e osservare che sono identici.

Facoltativamente, è possibile eseguire l'esempio in modalità nativa. A tale scopo, è necessario che GraalVM sia installato o usare un'immagine del generatore per compilare l'eseguibile nativo. Per altre informazioni, vedere Compilazione di un eseguibile nativo. Questa guida introduttiva rapida utilizza Docker come ambiente di runtime del contenitore per creare un eseguibile nativo per Linux. Se Docker non è stato installato, è possibile scaricarlo dal sito Web Docker.

Eseguire il comando seguente per compilare ed eseguire l'eseguibile nativo in un ambiente Linux:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Comprendere il codice di esempio

Verrà quindi illustrato il codice di esempio per comprendere il funzionamento.

Inserire un oggetto client con accesso autorizzato

L'uso di qualsiasi risorsa di Azure con l'SDK inizia con la creazione di un oggetto client. L'estensione Quarkus per Archiviazione BLOB di Azure inserisce automaticamente un oggetto client con accesso autorizzato tramite DefaultAzureCredential.

Per inserire correttamente un oggetto client, è prima necessario aggiungere le estensioni quarkus-arc e quarkus-azure-storage-blob al file pom.xml come dipendenze:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

L'estensione quarkus-arc è necessaria per usare l'annotazione @Inject per inserire l'oggetto client nel codice dell'applicazione. Le quarkus-bom dipendenze e quarkus-azure-services-bom vengono usate per gestire le versioni della piattaforma Quarkus e l'estensione Quarkus per i servizi di Azure.

È quindi possibile inserire l'oggetto client nel codice dell'applicazione usando l'annotazione @Inject :

@Inject
BlobServiceClient blobServiceClient;

È sufficiente scrivere codice per ottenere un oggetto client usando l'estensione Quarkus per Archiviazione BLOB di Azure. Per assicurarsi che l'oggetto client sia autorizzato ad accedere all'account di archiviazione in fase di esecuzione, è necessario seguire la procedura descritta nella sezione precedente Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB prima di eseguire l'applicazione.

Gestire BLOB e contenitori

L'esempio di codice seguente illustra come creare un contenitore, caricare un BLOB, elencare i BLOB in un contenitore e scaricare un BLOB.

Annotazioni

La scrittura nel file system locale è considerata una procedura non valida nelle applicazioni native del cloud. Tuttavia, l'esempio usa il file system locale per illustrare l'uso dell'archiviazione BLOB in modo che sia facile da verificare per l'utente. Quando si porta un'applicazione in produzione, esaminare le opzioni di archiviazione e scegliere l'opzione migliore per le proprie esigenze. Per altre informazioni, vedere Esaminare le opzioni di archiviazione.

// Create a unique name for the container
String containerName = "quickstartblobs" + java.util.UUID.randomUUID();

// Create the container and return a container client object
BlobContainerClient blobContainerClient = blobServiceClient.createBlobContainer(containerName);

// Create the ./data/ directory and a file for uploading and downloading
String localPath = "./data/";
new File(localPath).mkdirs();
String fileName = "quickstart" + java.util.UUID.randomUUID() + ".txt";

// Get a reference to a blob
BlobClient blobClient = blobContainerClient.getBlobClient(fileName);

// Write text to the file
FileWriter writer = null;
try
{
    writer = new FileWriter(localPath + fileName, true);
    writer.write("Hello, World!");
    writer.close();
}
catch (IOException ex)
{
    System.out.println(ex.getMessage());
}

System.out.println("\nUploading to Blob storage as blob:\n\t" + blobClient.getBlobUrl());

// Upload the blob
blobClient.uploadFromFile(localPath + fileName);

System.out.println("\nListing blobs...");

// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
    System.out.println("\t" + blobItem.getName());
}

// Download the blob to a local file

// Append the string "DOWNLOAD" before the .txt extension for comparison purposes
String downloadFileName = fileName.replace(".txt", "DOWNLOAD.txt");

System.out.println("\nDownloading blob to\n\t " + localPath + downloadFileName);

blobClient.downloadToFile(localPath + downloadFileName);

File downloadedFile = new File(localPath + downloadFileName);
File localFile = new File(localPath + fileName);

// Clean up resources
System.out.println("\nPress the Enter key to begin clean up");
System.console().readLine();

System.out.println("Deleting blob container...");
blobContainerClient.delete();

System.out.println("Deleting the local source and downloaded files...");
localFile.delete();
downloadedFile.delete();

System.out.println("Done");

Queste operazioni sono simili a quelle descritte in Avvio rapido: Libreria client di Archiviazione BLOB di Azure per Java SE. Per informazioni più dettagliate sul codice, vedere le sezioni seguenti in questa guida introduttiva:

Pulizia

È possibile scegliere di seguire i collegamenti nella sezione Passaggi successivi per distribuire l'applicazione Quarkus in Azure. In alternativa, è possibile pulire l'account di archiviazione eliminando il gruppo di risorse. Per altre informazioni, vedere Gruppo di risorse e eliminazione di risorse di Azure Resource Manager.

Passaggi successivi

Esempi di Archiviazione di Azure e guide per sviluppatori per Java Distribuire un'applicazione Java con Quarkus in un cluster del servizio Azure Kubernetes Distribuire un'applicazione Java con Quarkus in App Azure Container

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-09