Kom igång med Azure Blob Storage och Java

Artikel
10/22/2024

Den här artikeln visar hur du ansluter till Azure Blob Storage med hjälp av Azure Blob Storage-klientbiblioteket för Java. När du är ansluten använder du utvecklarguiderna för att lära dig hur din kod kan fungera på containrar, blobar och funktioner i Blob Storage-tjänsten.

Om du vill börja med ett komplett exempel kan du läsa Snabbstart: Azure Blob Storage-klientbibliotek för Java.

API-referenspaket (Maven) | Exempel på källkod | | för bibliotek Ge feedback |

Förutsättningar

Azure-prenumeration – skapa en kostnadsfritt
Azure Storage-konto – skapa ett lagringskonto
Java Development Kit (JDK) version 8 eller senare
Apache Maven används för projekthantering i det här exemplet

Konfigurera projektet

Kommentar

Den här artikeln använder verktyget Maven-kompilering för att skapa och köra exempelkoden. Andra byggverktyg, till exempel Gradle, fungerar också med Azure SDK för Java.

Använd Maven för att skapa en ny konsolapp eller öppna ett befintligt projekt. Följ de här stegen för att installera paket och lägga till nödvändiga import direktiv.

Installera paket

pom.xml Öppna filen i textredigeraren. Installera paketen genom att inkludera BOM-filen eller inkludera ett direkt beroende.

Inkludera BOM-filen

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. Med hjälp av azure-sdk-bom behöver du inte ange versionen av 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 till följande beroendeelement i gruppen med beroenden. Azure-identitetsberoendet behövs 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-storage-common</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

Inkludera ett direkt beroende

Om du vill vara beroende av en viss version av biblioteket lägger du till det direkta beroendet i projektet:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>{package_version_to_target}</version>
</dependency>
<dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-storage-common</artifactId>
      <version>{package_version_to_target}</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{package_version_to_target}</version>
</dependency>

Inkludera importdirektiv

Öppna sedan kodfilen och lägg till de direktiv som krävs import . I det här exemplet lägger vi till följande direktiv i filen App.java :

import com.azure.core.credential.*;
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import com.azure.storage.blob.specialized.*;
import com.azure.storage.common.*;

Information om Blob-klientbiblioteket:

com.azure.storage.blob: Innehåller de primära klasser (klientobjekt) som du kan använda för att arbeta med tjänsten, containrar och blobar.
com.azure.storage.blob.models: Innehåller verktygsklasser, strukturer och uppräkningstyper.
com.azure.storage.blob.specialized: Innehåller klasser som du kan använda för att utföra åtgärder som är specifika för en blobtyp (till exempel tilläggsblobar).

Auktorisera åtkomst och ansluta till Blob Storage

Om du vill ansluta en app till Blob Storage skapar du en instans av klassen BlobServiceClient . Du kan också använda klassen BlobServiceAsyncClient för asynkron programmering. Det här objektet är startpunkten för att interagera med dataresurser på lagringskontonivå. Du kan använda den för att arbeta med lagringskontot och dess containrar. Du kan också använda tjänstklienten för att skapa containerklienter eller blobklienter, beroende på vilken resurs du behöver arbeta med.

Mer information om hur du skapar och hanterar klientobjekt finns i Skapa och hantera klientobjekt som interagerar med dataresurser.

Du kan auktorisera ett BlobServiceClient objekt med hjälp av en Microsoft Entra-auktoriseringstoken, en kontoåtkomstnyckel eller en signatur för delad åtkomst (SAS). För optimal säkerhet rekommenderar Microsoft att du använder Microsoft Entra-ID med hanterade identiteter för att auktorisera begäranden mot blobdata. Mer information finns i Auktorisera åtkomst till blobar med hjälp av Microsoft Entra-ID.

Om du vill auktorisera med Microsoft Entra-ID måste du använda ett säkerhetsobjekt. Vilken typ av säkerhetsobjekt du behöver beror på var appen körs. Använd följande tabell som en guide:

Var appen körs	Säkerhetsobjekt	Vägledning
Lokal dator (utveckla och testa)	Tjänstens huvudnamn	Information om hur du registrerar appen, konfigurerar en Microsoft Entra-grupp, tilldelar roller och konfigurerar miljövariabler finns i Auktorisera åtkomst med utvecklartjänstens huvudnamn.
Lokal dator (utveckla och testa)	Användaridentitet	Information om hur du konfigurerar en Microsoft Entra-grupp, tilldelar roller och loggar in på Azure finns i Auktorisera åtkomst med autentiseringsuppgifter för utvecklare.
Värdhanterad i Azure	Hanterad identitet	Information om hur du aktiverar hanterad identitet och tilldelar roller finns i Auktorisera åtkomst från Azure-värdbaserade appar med hjälp av en hanterad identitet.
Värdhanterad utanför Azure (till exempel lokala appar)	Tjänstens huvudnamn	Information om hur du registrerar appen, tilldelar roller och konfigurerar miljövariabler finns i Auktorisera åtkomst från lokala appar med hjälp av ett huvudnamn för programtjänsten

Auktorisera åtkomst med defaultAzureCredential

Ett enkelt och säkert sätt att auktorisera åtkomst och ansluta till Blob Storage är att hämta en OAuth-token genom att skapa en DefaultAzureCredential-instans . Du kan sedan använda autentiseringsuppgifterna för att skapa ett BlobServiceClient-objekt .

Kontrollera att du har rätt beroenden i pom.xml och nödvändiga importdirektiv enligt beskrivningen i Konfigurera projektet.

I följande exempel används BlobServiceClientBuilder för att skapa ett BlobServiceClient objekt med , DefaultAzureCredentialoch visar hur du skapar container- och blobklienter om det behövs:

// 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(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

Använd BlobServiceClientBuilder för att skapa ett BlobServiceClient-objekt med hjälp av en SAS-token:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {
    // TODO: Replace <storage-account-name> with your actual storage account name
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint("https://<storage-account-name>.blob.core.windows.net/")
            .sasToken(sasToken)
            .buildClient();

    return blobServiceClient;
}

Mer information om hur du genererar och hanterar SAS-token finns i följande artiklar:

Grant limited access to Azure Storage resources using shared access signatures (SAS) (Bevilja begränsad åtkomst till Azure Storage-resurser med hjälp av signaturer för delad åtkomst (SAS))
Skapa ett KONTO-SAS med Java
Skapa en tjänst-SAS med Java
Skapa en SAS för användardelegering med Java

Kommentar

För scenarier där signaturer för delad åtkomst (SAS) används rekommenderar Microsoft att du använder en SAS för användardelegering. En SAS för användardelegering skyddas med Microsoft Entra-autentiseringsuppgifter i stället för kontonyckeln.

Skapa en StorageSharedKeyCredential med hjälp av lagringskontots namn och kontonyckel. Använd sedan objektet för att initiera ett BlobServiceClient-objekt .

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Azure SDK client builders accept the credential as a parameter
    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))
            .credential(credential)
            .buildClient();

    return blobServiceClient;        
}

Du kan också skapa ett BlobServiceClient objekt med hjälp av en anslutningssträng.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {
    // 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/")
            .connectionString(connectionString)
            .buildClient();

    return blobServiceClient;        
}

Information om hur du hämtar kontonycklar och riktlinjer för bästa praxis för korrekt hantering och skydd av dina nycklar finns i Hantera åtkomstnycklar för lagringskonton.

Viktigt!

Kontoåtkomstnyckeln bör användas med försiktighet. Om din kontoåtkomstnyckel går förlorad eller oavsiktligt placeras på en osäker plats kan tjänsten bli sårbar. Alla som har åtkomstnyckeln kan auktorisera begäranden mot lagringskontot och har effektivt åtkomst till alla data. DefaultAzureCredential ger förbättrade säkerhetsfunktioner och fördelar och är den rekommenderade metoden för att hantera auktorisering till Azure-tjänster.

Konfigurera JVM TTL för DNS-namnsökningar

Java Virtual Machine (JVM) cachelagrar svar från lyckade DNS-namnsökningar under en angiven tidsperiod, som kallas TTL (time to live). Standardvärdet för TTL för många JVM:er är -1, vilket innebär att JVM cachelagrar svaret på obestämd tid eller tills JVM startas om.

Eftersom Azure-resurser använder DNS-namnposter som kan ändras rekommenderar vi att du anger JVM TTL-värdet till 10 sekunder. Den här konfigurationen säkerställer att en uppdaterad IP-adress för en resurs returneras med nästa DNS-fråga.

Om du vill ändra TTL-värdet globalt för alla program med hjälp av JVM anger du networkaddress.cache.ttl egenskapen i java.security filen.

networkaddress.cache.ttl=10

För Java 8 java.security finns filen i $JAVA_HOME/jre/lib/security katalogen. För Java 11 och senare finns filen i $JAVA_HOME/conf/security katalogen.

Skapa appen

När du skapar appar för att arbeta med dataresurser i Azure Blob Storage interagerar koden främst med tre resurstyper: lagringskonton, containrar och blobar. Mer information om dessa resurstyper, hur de relaterar till varandra och hur appar interagerar med resurser finns i Förstå hur appar interagerar med Blob Storage-dataresurser.

Följande guider visar hur du får åtkomst till data och utför specifika åtgärder med hjälp av Azure Storage-klientbiblioteket för Java:

Guide	beskrivning
Konfigurera en återförsöksprincip	Implementera återförsöksprinciper för klientåtgärder.
Kopiera blobar	Kopiera en blob från en plats till en annan.
Skapa en container	Skapa blobcontainrar.
Skapa en SAS för användardelegering	Skapa en SAS för användardelegering för en container eller blob.
Skapa och hantera bloblån	Upprätta och hantera ett lås på en blob.
Skapa och hantera containerlån	Upprätta och hantera ett lås på en container.
Ta bort och återställa blobar	Ta bort blobar och återställ borttagna blobar om mjuk borttagning är aktiverat.
Ta bort och återställa containrar	Ta bort containrar och återställ borttagna containrar om mjuk borttagning är aktiverat.
Ladda ned blobar	Ladda ned blobar med hjälp av strängar, strömmar och filsökvägar.
Hitta blobar med taggar	Ange och hämta taggar samt använd taggar för att hitta blobar.
Lista blobar	Lista blobar på olika sätt.
Lista containrar	Visa en lista över containrar i ett konto och de olika alternativ som är tillgängliga för att anpassa en lista.
Hantera egenskaper och metadata (blobar)	Hämta och ange egenskaper och metadata för blobar.
Hantera egenskaper och metadata (containrar)	Hämta och ange egenskaper och metadata för containrar.
Prestandajustering för dataöverföringar	Optimera prestanda för dataöverföringsåtgärder.
Ange eller ändra åtkomstnivån för en blob	Ange eller ändra åtkomstnivån för en blockblob.
Ladda upp blobar	Lär dig hur du laddar upp blobar med hjälp av strängar, strömmar, filsökvägar och andra metoder.

Dela via