Snabbstart: Azure Blob Storage-klientbibliotek för Java SE

Kommentar

Alternativet Bygg från grunden guidar dig genom att skapa ett projekt, installera paket, skriva kod och köra en enkel konsolapp. Välj detta alternativ för att förstå hur man skapar en app som ansluter till Azure Blob Storage. För att automatisera driftsättningsuppgifter och börja med ett färdigt projekt väljer du Börja med en mall.

Kommentar

Alternativet Start med en mall använder Azure Developer CLI för att automatisera distributionsuppgifter och ger ett färdigt projekt. Välj detta alternativ för att utforska koden utan att slutföra installationsuppgifterna. För steg-för-steg-instruktioner för att bygga appen, välj Bygg från grunden.

Kom igång med Azure Blob Storage-klientbiblioteket för Java för att hantera blobar och containrar.

I den här artikeln följer du stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

I den här artikeln använder du Azure Developer CLI för att distribuera Azure-resurser och köra en slutförd konsolapp med bara några få kommandon.

Tips

För Spring-applikationer som använder Azure Storage-resurser, överväg Spring Cloud Azure. Detta open source-projekt integrerar Spring med Azure-tjänster. För ett exempel på Blob Storage, se Upload a file to an Azure Storage Blob.

API-referensdokumentation | Källkod för bibliotek | Paket (Maven) | Exempel

Förutsättningar

Konfigurera

Det här avsnittet beskriver hur du förbereder ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för Java.

Skapa projektet

Skapa ett Java-program med namnet blob-quickstart.

  1. I ett konsolfönster (till exempel PowerShell eller Bash) använder du Maven för att skapa en ny konsolapp med namnet blob-quickstart. Skriv följande mvn-kommando för att skapa en "Hello world!" Java-projekt.

    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. Gå igenom resultatet från projektets generering.

    [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. Växla till den nyligen skapade blob-snabbstartsmappen .

    cd blob-quickstart

  4. Inuti blob-quickstart-katalogen , skapa en annan katalog kallad data. Det är i denna mapp som blob-datafilerna skapas och lagras.

    mkdir data

Installera paketen

pom.xml Öppna filen i textredigeraren.

Lägg till azure-sdk-bom för att ta ett beroende av den senaste versionen av biblioteket. I följande kodfragment ersätter du {bom_version_to_target} platshållaren med versionsnumret. Genom att använda azure-sdk-bom behöver du inte ange versionen för varje enskilt beroende. Mer information om bommen finns i AZURE SDK BOM README.

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

Lägg sedan till följande beroendeelement i gruppen med beroenden. Du behöver azure-identity-beroendet för lösenordslösa anslutningar till Azure-tjänster.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Konfigurera appramverket

Från projektkatalogen följer du de här stegen för att skapa appens grundläggande struktur:

  1. Gå till katalogen /src/main/java/com/blobs/quickstart
  2. App.java Öppna filen i redigeringsprogrammet
  3. Ta bort raden System.out.println("Hello world!");
  4. Lägg till de direktiv som krävs import

Koden bör likna det här ramverket:

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

Genom att använda Azure Developer CLI kan du skapa ett lagringskonto och köra exempelkoden med bara några få kommandon. Du kan köra projektet i din lokala utvecklingsmiljö eller i en DevContainer.

Initiera CLI-mallen för Azure Developer och distribuera resurser

Från en tom katalog följer du de här stegen för att initiera mallen azd , etablera Azure-resurser och komma igång med koden:

  • Klona snabbstartslagringsplatsens tillgångar från GitHub och initiera mallen lokalt:

    azd init --template blob-storage-quickstart-java

    Du uppmanas att ange följande information:

    • Environment name: Azure Developer CLI använder det här värdet som prefix för alla Azure resurser som skapas. Namnet måste vara unikt för alla Azure prenumerationer och vara mellan 3 och 24 tecken långt. Namnet får endast innehålla siffror och små bokstäver.

  • Logga in på Azure:

    azd auth login

  • Etablera och distribuera resurserna till Azure:

    azd up

    Du uppmanas att ange följande information:

    • Prenumeration: Azure-prenumerationen för att distribuera dina resurser.
    • Plats: Azure-regionen för att distribuera dina resurser.

    Utrullningen kan ta några minuter att bli klar. Utdata från azd up kommandot innehåller namnet på det nyligen skapade lagringskontot, som du behöver senare för att köra koden.

Kör exempelkoden

Nu distribueras resurserna till Azure och koden är nästan redo att köras. Följ dessa steg för att uppdatera namnet på lagringskontot i koden och kör exempelkonsolappen:

  • Uppdatera lagringskontots namn:
    1. I den lokala katalogen går du till katalogen blob-quickstart/src/main/java/com/blobs/quickstart .
    2. Öppna filen med namnet App.java i redigeringsprogrammet. Leta upp <storage-account-name> platshållaren och ersätt den med det faktiska namnet på lagringskontot som skapades av azd up kommandot.
    3. Spara ändringarna.
  • Kör projektet:
    1. Gå till katalogen blob-quickstart som innehåller pom.xml filen. Kompilera projektet med hjälp av följande mvn kommando: 
      mvn compile
    2. Paketera den kompilerade koden i dess distributionsbara format: 
      mvn package
    3. Kör följande mvn kommando för att köra appen: 
      mvn exec:java
  • Observera resultatet: Den här appen skapar en testfil i din lokala datamapp och laddar upp den till en container i ett lagringskonto. I exemplet visas sedan blobarna i containern och filen laddas ned med ett nytt namn så att du kan jämföra de gamla och nya filerna.

Mer information om hur exempelkoden fungerar finns i Kodexempel.

När du är klar med att testa koden kan du läsa avsnittet Rensa resurser för att ta bort de resurser som skapades av azd up kommandot.

Objektmodell

Azure Blob Storage är optimerat för lagring av enorma mängder ostrukturerade data. Ostrukturerade data följer inte en viss datamodell eller definition, till exempel text eller binära data. I blobblagringen finns tre typer av resurser:

  • Lagringskontot
  • En container på lagringskontot
  • En blob i behållaren

Följande diagram visar relationen mellan de här resurserna.

Diagram som visar ett lagringskonto som innehåller en blobcontainer och en blob.

Använd följande Java-klasser för att interagera med dessa resurser:

  • BlobServiceClient: KlassenBlobServiceClient hanterar Azure Storage-resurser och blob-containrar. Lagringskontot tillhandahåller namnområdet på den översta nivån för Blob-tjänsten.
  • BlobServiceClientBuilder: KlassenBlobServiceClientBuilder tillhandahåller ett flytande API för att konfigurera och skapa BlobServiceClient objekt.
  • BlobContainerClient: KlassenBlobContainerClient hanterar Azure Storage-containrar och deras blobs.
  • BlobClient: Klassen BlobClient hanterar Azure Storage-blobs.
  • BlobItem: Klassen BlobItem representerar enskilda blobar som returneras från ett anrop till listBlobs.

Kodexempel

Dessa exempelkodfragment visar hur du utför följande åtgärder med Azure Blob Storage-klientbiblioteket för Java:

Viktigt!

Lägg till de beroenden och direktiv som beskrivs i Setup up innan du använder kodproverna.

Kommentar

Azure Developer CLI-mallen innehåller en fil med exempelkod som redan finns på plats. Följande exempel innehåller information om varje del av exempelkoden. Mallen implementerar den rekommenderade autentiseringsmetoden utan lösenord, enligt beskrivningen i avsnittet Autentisera till Azure . Metoden anslutningssträng visas som ett alternativ, men används inte i mallen och rekommenderas inte för produktionskod.

Autentisera till Azure och auktorisera åtkomst till blobdata

Programbegäranden till Azure Blob Storage måste vara auktoriserade. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod, inklusive Blob Storage.

Du kan också auktorisera begäranden till Azure Blob Storage med hjälp av kontoåtkomstnyckeln. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera åtkomstnyckeln på en osäker plats. Alla som har åtkomstnyckeln kan auktorisera begäranden mot lagringskontot och har effektivt åtkomst till alla data. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordslös autentisering. Båda alternativen visas i följande exempel.

DefaultAzureCredential är en klass som tillhandahålls av Azure Identity-klientbiblioteket för Java. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod.

Du hittar den ordning och de platser som DefaultAzureCredential söker efter autentiseringsuppgifter på i översikten över Azure Identity-biblioteket.

Till exempel kan din app autentiseras genom att använda dina inloggningsuppgifter i Visual Studio Code när du utvecklar lokalt. Din app kan sedan använda en hanterad identitet efter distribution till Azure. Inga kodändringar krävs för den här övergången.

Tilldela roller till ditt Microsoft Entra-användarkonto

När du utvecklar lokalt kontrollerar du att användarkontot som har åtkomst till blobdata har rätt behörigheter. Du behöver Storage Blob Data-behörighet för att läsa och skriva blobdata. Om du vill tilldela dig själv den här rollen måste du tilldelas rollen Administratör för användaråtkomst eller en annan roll som innehåller åtgärden Microsoft.Authorization/roleAssignments/write . Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure Portal, Azure CLI eller Azure PowerShell. Mer information om rollen Storage Blob Data-deltagare finns i Storage Blob Data-deltagare. Mer information om tillgängliga omfång för rolltilldelningar finns i Förstå omfånget för Azure RBAC.

I det här scenariot tilldelar du behörigheter till ditt användarkonto, begränsat till lagringskontot, för att följa principen om lägsta behörighet. Den här metoden ger användarna endast de minsta behörigheter som krävs och skapar säkrare produktionsmiljöer.

I följande exempel tilldelas rollen Storage Blob Data Contributor till ditt användarkonto, vilket ger både läs- och skrivåtkomst till blobdata i ditt lagringskonto.

Viktigt!

I de flesta fall tar det en minut eller två för rolltilldelningen att spridas i Azure, men i sällsynta fall kan det ta upp till åtta minuter. Om du får autentiseringsfel när du först kör koden väntar du en stund och försöker igen.

  1. Leta upp ditt lagringskonto i Azure Portal med hjälp av huvudsökfältet eller det vänstra navigeringsfältet.

  2. På översiktssidan för lagringskontot väljer du Åtkomstkontroll (IAM) på den vänstra menyn.

  3. På sidan Åtkomstkontroll (IAM) väljer du fliken Rolltilldelningar .

  4. Välj + Lägg till på den översta menyn och sedan Lägg till rolltilldelning från den resulterande nedrullningsbara menyn.

    En skärmbild som visar hur du tilldelar en roll.

  5. Använd sökrutan för att filtrera resultatet till önskad roll. I det här exemplet söker du efter Storage Blob Data Contributor och väljer matchande resultat och väljer sedan Nästa.

  6. Under Tilldela åtkomst till väljer du Användare, grupp eller tjänstens huvudnamn och sedan + Välj medlemmar.

  7. I dialogrutan söker du efter ditt Microsoft Entra-användarnamn (vanligtvis din user@domain e-postadress) och väljer sedan Välj längst ned i dialogrutan.

  8. Välj Granska + tilldela för att gå till den sista sidan, och välj sedan Granska + tilldela igen för att slutföra processen.

Logga in och anslut din appkod till Azure med hjälp av DefaultAzureCredential

Auktorisera åtkomst till data i ditt lagringskonto genom att följa dessa steg:

  1. Autentisera genom att använda samma Microsoft Entra-konto som du tilldelade lagringskontorollen. Använd Azure CLI, Visual Studio Code eller Azure PowerShell.

    Logga in på Azure via Azure CLI med hjälp av följande kommando:

    az login

  2. För att använda DefaultAzureCredential, lägg till beroendet azure-identity i pom.xml:

    <dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
</dependency>

  3. Lägg till den här koden i main metoden. När koden körs på din lokala arbetsstation använder den utvecklaruppgifterna från det prioriterade verktyget du är inloggad på för att autentisera mot Azure, såsom Azure CLI eller 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();

  4. Uppdatera lagringskontots namn i URI:n för din BlobServiceClient. Hitta lagringskontots namn på översiktssidan i Azure-portalen.

    En skärmbild som visar hur du hittar lagringskontots namn.

    Kommentar

    När du distribuerar till Azure kan samma kod användas för att auktorisera begäranden till Azure Storage från ett program som körs i Azure. Du måste dock aktivera hanterad identitet i din app i Azure. Konfigurera sedan ditt lagringskonto så att den hanterade identiteten kan ansluta. Detaljerade anvisningar om hur du konfigurerar den här anslutningen mellan Azure-tjänster finns i självstudiekursen Autentisering från Azure-värdade appar.

Skapa en container

Skapa en ny container i ditt lagringskonto genom att anropa metoden createBlobContainer för blobServiceClient objektet. I det här exemplet lägger koden till ett GUID-värde i containernamnet för att säkerställa att det är unikt.

Lägg till den här koden i slutet av main metoden:

// 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);

För mer information och exempel, se Create a blob container with Java.

Viktigt!

Containernamn måste använda gemener. Mer information om namngivning av containrar och blobar finns i Namngivning och referens av containrar, blobar och metadata.

Ladda upp blobar till en container

Ladda upp en blob till en container genom att anropa metoden uploadFromFile . Exempelkoden skapar en textfil i den lokala datakatalogen som ska laddas upp till containern.

Lägg till den här koden i slutet av main metoden:

// 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);

För mer information och exempel, se Upload a blob with Java.

Visa blobar i en container

Lista blobarna i containern genom att anropa listBlobs-metoden . I det här fallet lade du bara till en blob i containern, så listningsoperationen returnerar bara den bloben.

Lägg till den här koden i slutet av main metoden:

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

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

För mer information och exempel, se Lista blobs med Java.

Ladda ned blobbar

Ladda ned den tidigare skapade bloben genom att anropa metoden downloadToFile . Exempelkoden lägger till ett suffix av DOWNLOAD i filnamnet så att du kan se båda filerna i det lokala filsystemet.

Lägg till den här koden i slutet av main metoden:

// 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);

För mer information och exempel, se Ladda ner en blob med Java.

Ta bort en container

Följande kod rensar upp de resurser som appen skapade genom att ta bort hela behållaren med hjälp av delete-metoden . Den tar också bort de lokala filer som skapats av appen.

Appen pausar för användarindata genom att anropa System.console().readLine() innan den tar bort bloben, containern och de lokala filerna. Denna paus ger dig en chans att verifiera att appen skapade resurserna korrekt innan den raderar dem.

Lägg till den här koden i slutet av main metoden:

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");

För mer information och exempel, se Ta bort och återställ en blobcontainer med Java.

Kör koden

Den här appen skapar en testfil i din lokala mapp och laddar upp den till Blob Storage. I exemplet visas sedan blobarna i containern och filen laddas ned med ett nytt namn så att du kan jämföra de gamla och nya filerna.

Följ dessa steg för att kompilera, paketera och köra koden:

  1. Navigera till katalogen som innehåller pom.xml filen och kompilera projektet med hjälp av följande mvn kommando: 
    mvn compile
  2. Paketera den kompilerade koden i dess distributionsbara format: 
    mvn package
  3. Kör följande mvn kommando för att köra appen: 
    mvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
    För att förenkla körsteget, lägg till exec-maven-pluginpom.xml och konfigurera det enligt följande kod: 
    <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>
    Med denna konfiguration kör appen med följande kommando: 
    mvn exec:java

Utdata från appen liknar följande exempel (UUID-värden utelämnas för läsbarhet):

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

Innan du påbörjar rensningsprocessen kontrollerar du datamappen för de två filerna. Du kan jämföra dem och observera att de är identiska.

Rensa resurser

När du har verifierat filerna och testat klart trycker du på Retur för att ta bort testfilerna tillsammans med containern som du skapade i lagringskontot. Du kan också använda Azure CLI för att ta bort resurser.

När du är klar med snabbstarten rensar du de resurser som du skapade genom att köra följande kommando:

azd down

Du får en prompt om att bekräfta raderingen av resurserna. Ange y för att bekräfta.

Gå vidare

Azure Storage-exempel och utvecklarhandböcker för JavaSnabbstart: Quarkus-tillägg för Azure Blob StorageAnvänd Spring Boot för att ladda upp en fil till Azure Blob Storage

  • Last updated on