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.

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.

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

   • PowerShell
   • Bash

   mvn archetype:generate `
       --define interactiveMode=n `
       --define groupId=com.blobs.quickstart `
       --define artifactId=blob-quickstart `
       --define archetypeArtifactId=maven-archetype-quickstart `
       --define archetypeVersion=1.4
   

2. 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] ------------------------------------------------------------------------
       ```
   
   

3. Passare alla cartella blob-quickstart appena creata.

   cd blob-quickstart
   

4. 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:

1. Passare alla directory /src/main/java/com/blobs/quickstart
2. Aprire il file App.java nell'editor
3. Eliminare la riga System.out.println("Hello world!");
4. 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 di BlobServiceClient 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

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.

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

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

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

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

az storage account show-connection-string --name "<your-storage-account-name>"

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

// Retrieve the connection string for use with the application. 
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");

// Create a BlobServiceClient object using a connection string
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
    .connectionString(connectStr)
    .buildClient();

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.

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:

1. Creare un file di testo nella directory data locale.
2. Ottenere un riferimento a un oggetto BlobClient chiamando il metodo getBlobClient sul contenitore dalla sezione Creare un contenitore.
3. 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

1. Passare alla directory contenente il pom.xml file e compilare il progetto usando il comando seguente mvn :

   mvn compile
   

2. Creare un pacchetto del codice compilato nel formato distribuibile:

   mvn package
   

3. Eseguire il comando seguente mvn per eseguire l'app:

   mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
   

   Per semplificare il passaggio di esecuzione, è possibile aggiungere exec-maven-pluginpom.xml e configurare come illustrato di seguito:

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

   Con questa configurazione, è possibile eseguire l'app con il comando seguente:

   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.