Guida introduttiva: libreria client Archiviazione BLOB di Azure per Java
Introduzione alla libreria client Archiviazione BLOB di Azure per Java per gestire BLOB e contenitori. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.
Suggerimento
Se si usa Archiviazione di Azure risorse in un'applicazione Spring, è consigliabile prendere in considerazione Spring Cloud Azure come alternativa. Spring Cloud Azure è un progetto open source che offre un'integrazione spring senza problemi con i servizi di Azure. Per altre informazioni su Spring Cloud Azure e per un esempio relativo all'uso di blob Archiviazione, vedere Caricare un file in un BLOB Archiviazione di Azure.
Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (Maven) | Esempi
Prerequisiti
- Account Azure con una sottoscrizione attiva: creare gratuitamente un account.
- Archiviazione di Azure account: creare un account di archiviazione.
- Java Development Kit (JDK) versione 8 o successiva.
- Apache Maven.
Configurazione
Questa sezione illustra come preparare un progetto da usare con la libreria client Archiviazione BLOB di Azure per Java.
Creare il progetto
Creare un'applicazione Java denominata blob-quickstart.
In una finestra della console, ad esempio PowerShell o Bash, usare Maven per creare una nuova app console con il nome blob-quickstart. Digitare il comando mvn seguente per creare un "Hello world!" Progetto Java.
mvn archetype:generate ` --define interactiveMode=n ` --define groupId=com.blobs.quickstart ` --define artifactId=blob-quickstart ` --define archetypeArtifactId=maven-archetype-quickstart ` --define archetypeVersion=1.4
L'output della generazione del progetto avrà un aspetto simile al seguente:
[INFO] Scanning for projects... [INFO] [INFO] ------------------< org.apache.maven:standalone-pom >------------------- [INFO] Building Maven Stub Project (No POM) 1 [INFO] --------------------------------[ pom ]--------------------------------- [INFO] [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>> [INFO] [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<< [INFO] [INFO] [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom --- [INFO] Generating project in Batch mode [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.blobs.quickstart [INFO] Parameter: artifactId, Value: blob-quickstart [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.blobs.quickstart [INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.blobs.quickstart [INFO] Parameter: groupId, Value: com.blobs.quickstart [INFO] Parameter: artifactId, Value: blob-quickstart [INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 7.056 s [INFO] Finished at: 2019-10-23T11:09:21-07:00 [INFO] ------------------------------------------------------------------------ ```
Passare alla cartella blob-quickstart appena creata.
cd blob-quickstart
Nella directory blob-quickstart creare un'altra directory denominata dati. Questa cartella è la posizione in cui verranno creati e archiviati i file di dati BLOB.
mkdir data
Installare i pacchetti
Aprire il file nell'editor pom.xml
di testo.
Aggiungere azure-sdk-bom per acquisire una dipendenza dalla versione più recente della libreria. Nel frammento di codice seguente sostituire il {bom_version_to_target}
segnaposto con il numero di versione. L'uso di azure-sdk-bom impedisce di specificare la versione di ogni singola dipendenza. Per altre informazioni sulla distinta base, vedere il file LEGGIMI DBA di Azure 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>
Aggiungere quindi gli elementi di dipendenza seguenti al gruppo di dipendenze. La dipendenza azure-identity è necessaria per le connessioni senza password ai servizi di Azure.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>
Configurare il framework dell'app
Nella directory del progetto seguire la procedura per creare la struttura di base dell'app:
- Passare alla directory /src/main/java/com/blobs/quickstart
- Aprire il file
App.java
nell'editor - Eliminare la riga
System.out.println("Hello world!");
- Aggiungere le direttive necessarie
import
Il codice dovrebbe essere simile a questo framework:
package com.blobs.quickstart;
/**
* Azure Blob Storage quickstart
*/
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;
public class App
{
public static void main(String[] args) throws IOException
{
// Quickstart code goes here
}
}
Modello a oggetti
Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati. I dati non strutturati non rispettano un particolare modello di dati o una definizione, ad esempio dati di testo o binari. L'archiviazione BLOB offre tre tipi di risorse:
- L'account di archiviazione
- Un contenitore nell'account di archiviazione
- Un oggetto BLOB in un contenitore
Il diagramma seguente mostra la relazione tra queste risorse.
Per interagire con queste risorse, usare le classi Java seguenti:
- BlobServiceClient: la
BlobServiceClient
classe consente di modificare Archiviazione di Azure risorse e contenitori BLOB. L'account di archiviazione rappresenta lo spazio dei nomi di primo livello per il servizio BLOB. - BlobServiceClientBuilder: la
BlobServiceClientBuilder
classe fornisce un'API fluent builder per facilitare la configurazione e la creazione di istanze diBlobServiceClient
oggetti. - BlobContainerClient: la
BlobContainerClient
classe consente di modificare Archiviazione di Azure contenitori e i relativi BLOB. - BlobClient: la
BlobClient
classe consente di modificare Archiviazione di Azure BLOB. - BlobItem: la
BlobItem
classe rappresenta i singoli BLOB restituiti da una chiamata a listBlobs.
Esempi di codice
Questi frammenti di codice di esempio illustrano come eseguire le azioni seguenti con la libreria client Archiviazione BLOB di Azure per Java:
- Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB
- Creare un contenitore
- Caricare BLOB in un contenitore
- Elencare i BLOB in un contenitore
- Scaricare BLOB
- Eliminare un contenitore
Importante
Assicurarsi di disporre delle dipendenze corrette in pom.xml e delle direttive necessarie per il funzionamento degli esempi di codice, come descritto nella sezione relativa alla configurazione .
Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB
Le richieste dell'applicazione a Archiviazione BLOB di Azure devono essere autorizzate. L'uso della DefaultAzureCredential
classe fornita dalla libreria client di Identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice, incluso l'Archiviazione BLOB.
È anche possibile autorizzare le richieste di Archiviazione BLOB di Azure usando la chiave di accesso dell'account. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso è in grado di autorizzare le richieste all'account di archiviazione e può accedere in modo efficace a tutti i dati. DefaultAzureCredential
offre vantaggi di gestione e sicurezza migliorati rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono illustrate nell'esempio seguente.
DefaultAzureCredential
è una classe fornita dalla libreria client di Azure Identity 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.
Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso di Visual Studio Code con durante lo sviluppo in locale. L'app può quindi usare un'identità gestita dopo la distribuzione in Azure. Per questa transizione non sono necessarie modifiche al codice.
Assegnare ruoli all'account utente di Microsoft Entra
Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. È necessario Archiviazione Collaboratore ai dati BLOB per leggere e scrivere dati BLOB. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Accesso utente Amministrazione istrator o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli 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 altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina di panoramica dell'ambito.
In questo scenario si assegneranno le autorizzazioni all'account utente, con ambito all'account di archiviazione, 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 BLOB Archiviazione all'account utente, che fornisce sia l'accesso in lettura che in 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.
Nella 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 Archiviazione Collaboratore dati BLOB e selezionare il risultato corrispondente e 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 Seleziona nella parte inferiore della finestra di dialogo.
Selezionare Rivedi e assegna per passare alla pagina finale e quindi rivedi e assegna per completare il processo.
Accedere e connettere il codice dell'app ad Azure usando DefaultAzureCredential
È 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. È possibile eseguire l'autenticazione tramite l'interfaccia della riga di comando di Azure, Visual Studio Code o Azure PowerShell.
Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:
az login
Per usare
DefaultAzureCredential
, assicurarsi che la dipendenza azure-identity venga aggiunta inpom.xml
:<dependency> <groupId>com.azure</groupId> <artifactId>azure-identity</artifactId> </dependency>
Aggiungere questo codice al
Main
metodo . Quando il codice viene eseguito nella workstation locale, userà le credenziali per sviluppatori dello strumento con priorità a cui si è connessi per l'autenticazione in Azure, ad esempio l'interfaccia della riga di comando di Azure o Visual Studio Code./* * The default credential first checks environment variables for configuration * If environment configuration is incomplete, it will try managed identity */ DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); // Azure SDK client builders accept the credential as a parameter // TODO: Replace <storage-account-name> with your actual storage account name BlobServiceClient blobServiceClient = new BlobServiceClientBuilder() .endpoint("https://<storage-account-name>.blob.core.windows.net/") .credential(defaultCredential) .buildClient();
Assicurarsi di aggiornare il nome dell'account di archiviazione nell'URI dell'oggetto
BlobServiceClient
. Il nome dell'account di archiviazione è disponibile nella pagina di panoramica del portale di Azure.Nota
Quando viene distribuito in Azure, questo stesso codice può essere usato per autorizzare le richieste a Archiviazione di Azure da un'applicazione in esecuzione in Azure. È tuttavia necessario abilitare l'identità gestita nell'app in Azure. Configurare quindi l'account di archiviazione per consentire la connessione a tale identità gestita. Per istruzioni dettagliate sulla configurazione di questa connessione tra i servizi di Azure, vedere l'esercitazione Sull'autenticazione dalle app ospitate in Azure.
Creazione di un contenitore
Decidere un nome per il nuovo contenitore. Il codice seguente aggiunge un valore UUID al nome del contenitore per assicurarsi che sia univoco.
Importante
I nomi dei contenitori devono essere in minuscolo. Per altre informazioni sulla denominazione di contenitori e BLOB, vedere Naming and Referencing Containers, Blobs, and Metadata (Assegnazione di nome e riferimento a contenitori, BLOB e metadati).
Successivamente, creare un'istanza della classe BlobContainerClient, quindi chiamare il metodo create per creare effettivamente il contenitore nell'account di archiviazione.
Aggiungere questo codice alla fine del metodo Main
:
// 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);
Per altre informazioni sulla creazione di un contenitore e per esplorare altri esempi di codice, vedere Creare un contenitore BLOB con Java.
Caricare BLOB in un contenitore
Aggiungere questo codice alla fine del metodo Main
:
// Create a local file in the ./data/ directory for uploading and downloading
String localPath = "./data/";
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);
Il frammento di codice completa i passaggi seguenti:
- Creare un file di testo nella directory data locale.
- Ottenere un riferimento a un oggetto BlobClient chiamando il metodo getBlobClient sul contenitore dalla sezione Creare un contenitore.
- Caricare il file di testo locale nel BLOB chiamando il metodo uploadFromFile. Questo metodo crea il BLOB se non esiste già, ma non lo sovrascrive se lo fa.
Per altre informazioni sul caricamento di BLOB e per esplorare altri esempi di codice, vedere Caricare un BLOB con Java.
Elencare i BLOB in un contenitore
Elencare i BLOB presenti nel contenitore chiamando il metodo listBlobs. In questo caso, al contenitore è stato aggiunto un unico BLOB, quindi l'operazione di recupero dell'elenco restituisce solo tale BLOB.
Aggiungere questo codice alla fine del metodo Main
:
System.out.println("\nListing blobs...");
// List the blob(s) in the container.
for (BlobItem blobItem : blobContainerClient.listBlobs()) {
System.out.println("\t" + blobItem.getName());
}
Per altre informazioni sull'elenco dei BLOB e per esplorare altri esempi di codice, vedere Elencare i BLOB con Java.
Scaricare BLOB
Scaricare il BLOB creato in precedenza chiamando il metodo downloadToFile. Il codice di esempio aggiunge il suffisso "DOWNLOAD" al nome del file in modo da consentire la visualizzazione di entrambi i file nel file system locale.
Aggiungere questo codice alla fine del metodo Main
:
// 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);
Per altre informazioni sul download di BLOB e per esplorare altri esempi di codice, vedere Scaricare un BLOB con Java.
Eliminare un contenitore
Il codice seguente pulisce le risorse create dall'app eliminando l'intero contenitore tramite il metodo delete. Elimina anche i file locali creati dall'app.
L'app viene sospesa per l'input dell'utente chiamando System.console().readLine()
prima dell'eliminazione di BLOB, contenitore e file locali. Questa è una buona probabilità di verificare che le risorse siano state create correttamente, prima che vengano eliminate.
Aggiungere questo codice alla fine del metodo Main
:
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");
Per altre informazioni sull'eliminazione di un contenitore e per esplorare altri esempi di codice, vedere Eliminare e ripristinare un contenitore BLOB con Java.
Eseguire il codice
Questa app crea un file di test nella cartella locale e lo carica nell'archiviazione BLOB. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.
Seguire i passaggi per compilare, creare un pacchetto ed eseguire il codice
- Passare alla directory contenente il
pom.xml
file e compilare il progetto usando il comando seguentemvn
:mvn compile
- Creare un pacchetto del codice compilato nel formato distribuibile:
mvn package
- Eseguire il comando seguente
mvn
per eseguire l'app:
Per semplificare il passaggio di esecuzione, è possibile aggiungeremvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
exec-maven-plugin
pom.xml
e configurare come illustrato di seguito:
Con questa configurazione, è possibile eseguire l'app con il comando seguente:<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>1.4.0</version> <configuration> <mainClass>com.blobs.quickstart.App</mainClass> <cleanupDaemonThreads>false</cleanupDaemonThreads> </configuration> </plugin>
mvn exec:java
L'output dell'app è simile all'esempio seguente (i valori UUID omessi per la leggibilità):
Azure Blob Storage - Java quickstart sample
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.
Pulire le risorse
Dopo aver verificato i file e aver completato il test, premere INVIO per eliminare i file di test insieme al contenitore creato nell'account di archiviazione. È anche possibile usare l'interfaccia della riga di comando di Azure per eliminare le risorse.
Passaggi successivi
In questa guida introduttiva si è appreso come caricare, scaricare ed elencare i BLOB con Java.
Per visualizzare le app di esempio di Archiviazione BLOB, procedere con:
- Per altre informazioni, vedere le librerie client Archiviazione BLOB di Azure per Java.
- Per esercitazioni, esempi, guide introduttive e altre documentazione, vedere Azure per sviluppatori Java.