Aan de slag met Azure Blob Storage en Java

Artikel
10/22/2024

In dit artikel wordt beschreven hoe u verbinding maakt met Azure Blob Storage met behulp van de Azure Blob Storage-clientbibliotheek voor Java. Zodra u verbinding hebt gemaakt, gebruikt u de ontwikkelaarshandleidingen om te leren hoe uw code kan werken op containers, blobs en functies van de Blob Storage-service.

Als u wilt beginnen met een volledig voorbeeld, raadpleegt u quickstart: Azure Blob Storage-clientbibliotheek voor Java.

Voorbeelden van | broncode van | API-referentiepakket | (Maven) | Library geven feedback

Vereisten

Azure-abonnement: u kunt een gratis abonnement nemen
Azure Storage-account: maak een opslagaccount
Java Development Kit (JDK)-versie 8 of hoger
Apache Maven wordt in dit voorbeeld gebruikt voor projectbeheer

Uw project instellen

Notitie

In dit artikel wordt het Maven-buildhulpprogramma gebruikt om de voorbeeldcode te bouwen en uit te voeren. Andere buildhulpprogramma's, zoals Gradle, werken ook met de Azure SDK voor Java.

Gebruik Maven om een nieuwe console-app te maken of een bestaand project te openen. Volg deze stappen om pakketten te installeren en de benodigde import instructies toe te voegen.

Pakketten installeren

Open het pom.xml bestand in de teksteditor. Installeer de pakketten door het BOM-bestand op te slaan of door een directe afhankelijkheid op te slaan.

Het BOM-bestand opnemen

Voeg azure-sdk-bom toe om een afhankelijkheid te maken van de nieuwste versie van de bibliotheek. Vervang in het volgende codefragment de {bom_version_to_target} tijdelijke aanduiding door het versienummer. Als u azure-sdk-bom gebruikt, hoeft u niet de versie van elke afzonderlijke afhankelijkheid op te geven. Zie de Azure SDK BOM README voor meer informatie over de BOM.

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

Voeg de volgende afhankelijkheidselementen toe aan de groep met afhankelijkheden. De azure-identity-afhankelijkheid is nodig voor verbindingen zonder wachtwoord met Azure-services.

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

Een directe afhankelijkheid opnemen

Als u afhankelijk wilt worden van een bepaalde versie van de bibliotheek, voegt u de directe afhankelijkheid toe aan uw project:

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

Importrichtlijnen opnemen

Open vervolgens het codebestand en voeg de benodigde import instructies toe. In dit voorbeeld voegen we de volgende instructies toe in het bestand 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.*;

Informatie over de Blob-clientbibliotheek:

com.azure.storage.blob: bevat de primaire klassen (clientobjecten) die u kunt gebruiken om te werken op de service, containers en blobs.
com.azure.storage.blob.models: Bevat hulpprogrammaklassen, structuren en opsommingstypen.
com.azure.storage.blob.specialized: bevat klassen die u kunt gebruiken om bewerkingen uit te voeren die specifiek zijn voor een blobtype (bijvoorbeeld toevoeg-blobs).

Toegang autoriseren en verbinding maken met Blob Storage

Als u een app wilt verbinden met Blob Storage, maakt u een exemplaar van de BlobServiceClient-klasse . U kunt ook de BlobServiceAsyncClient-klasse gebruiken voor asynchrone programmering. Dit object is het startpunt om te communiceren met gegevensbronnen op het niveau van het opslagaccount. U kunt het gebruiken om te werken op het opslagaccount en de bijbehorende containers. U kunt de serviceclient ook gebruiken om containerclients of blob-clients te maken, afhankelijk van de resource waarmee u moet werken.

Zie Clientobjecten maken en beheren die interactie hebben met gegevensbronnen voor meer informatie over het maken en beheren van clientobjecten.

U kunt een BlobServiceClient object autoriseren met behulp van een Microsoft Entra-autorisatietoken, een toegangssleutel voor een account of een SAS (Shared Access Signature). Voor optimale beveiliging raadt Microsoft aan om Microsoft Entra ID met beheerde identiteiten te gebruiken om aanvragen voor blobgegevens te autoriseren. Zie Toegang tot blobs autoriseren met behulp van Microsoft Entra-id voor meer informatie.

Als u wilt autoriseren met Microsoft Entra-id, moet u een beveiligingsprincipaal gebruiken. Welk type beveiligingsprincipaal u nodig hebt, is afhankelijk van waar uw app wordt uitgevoerd. Gebruik de volgende tabel als richtlijn:

Waar de app wordt uitgevoerd	Beveiligingsprincipal	Richtlijn
Lokale machine (ontwikkelen en testen)	Service-principal	Zie Toegang autoriseren met behulp van service-principals voor ontwikkelaars voor meer informatie over het registreren van de app, het instellen van een Microsoft Entra-groep, het toewijzen van rollen en het configureren van omgevingsvariabelen.
Lokale machine (ontwikkelen en testen)	Gebruikersidentiteit	Zie Toegang autoriseren met behulp van ontwikkelaarsreferenties voor meer informatie over het instellen van een Microsoft Entra-groep, het toewijzen van rollen en aanmelden bij Azure.
Gehost in Azure	Beheerde identiteit	Zie Toegang autoriseren vanuit door Azure gehoste apps met behulp van een beheerde identiteit voor meer informatie over het inschakelen van beheerde identiteiten en het toewijzen van rollen.
Gehost buiten Azure (bijvoorbeeld on-premises apps)	Service-principal	Zie Toegang vanuit on-premises apps autoriseren met behulp van een service-principal voor toepassingen voor meer informatie over het registreren van de app, het toewijzen van rollen en het configureren van omgevingsvariabelen

Toegang autoriseren met DefaultAzureCredential

Een eenvoudige en veilige manier om toegang te verlenen en verbinding te maken met Blob Storage is door een OAuth-token te verkrijgen door een DefaultAzureCredential-exemplaar te maken. Vervolgens kunt u die referentie gebruiken om een BlobServiceClient-object te maken.

Zorg ervoor dat u over de juiste afhankelijkheden in pom.xml en de benodigde importrichtlijnen beschikt, zoals beschreven in Uw project instellen.

In het volgende voorbeeld wordt BlobServiceClientBuilder gebruikt om een BlobServiceClient object te bouwen met behulp vanDefaultAzureCredential, en ziet u hoe u indien nodig container- en blobclients maakt:

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

Gebruik BlobServiceClientBuilder om een BlobServiceClient-object te bouwen met behulp van een 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;
}

Zie de volgende artikelen voor meer informatie over het genereren en beheren van SAS-tokens:

Notitie

Voor scenario's waarin SHARED Access Signatures (SAS) worden gebruikt, raadt Microsoft aan een SAS voor gebruikersdelegering te gebruiken. Een SAS voor gebruikersdelegering wordt beveiligd met Microsoft Entra-referenties in plaats van de accountsleutel.

Maak een StorageSharedKeyCredential met behulp van de naam van het opslagaccount en de accountsleutel. Gebruik dat object vervolgens om een BlobServiceClient-object te initialiseren.

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

U kunt ook een BlobServiceClient object maken met behulp van een verbindingsreeks.

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

Zie Toegangssleutels voor opslagaccounts beheren voor informatie over het verkrijgen van accountsleutels en aanbevolen procedures voor het correct beheren en beveiligen van uw sleutels.

Belangrijk

De toegangssleutel voor het account moet voorzichtig worden gebruikt. Als uw accounttoegangssleutel verloren gaat of per ongeluk op een onveilige locatie is geplaatst, kan uw service kwetsbaar worden. Iedereen met de toegangssleutel kan aanvragen voor het opslagaccount autoriseren en heeft effectief toegang tot alle gegevens. DefaultAzureCredential biedt verbeterde beveiligingsfuncties en voordelen en is de aanbevolen benadering voor het beheren van autorisatie voor Azure-services.

De JVM-TTL configureren voor DNS-naamzoekacties

Met de Java Virtual Machine (JVM) worden antwoorden van geslaagde DNS-naamzoekacties gedurende een opgegeven periode in de cache opgeslagen, ook wel TTL (Time-to-Live) genoemd. De standaard-TTL-waarde voor veel JVM's is -1, wat betekent dat de JVM het antwoord voor onbepaalde tijd in de cache opspoort of totdat de JVM opnieuw wordt opgestart.

Omdat Azure-resources DNS-naamvermeldingen gebruiken die kunnen worden gewijzigd, raden we u aan de JVM TTL-waarde in te stellen op 10 seconden. Deze configuratie zorgt ervoor dat een bijgewerkt IP-adres voor een resource wordt geretourneerd met de volgende DNS-query.

Als u de TTL-waarde globaal wilt wijzigen voor alle toepassingen die gebruikmaken van de JVM, stelt u de networkaddress.cache.ttl eigenschap in het java.security bestand in.

networkaddress.cache.ttl=10

Voor Java 8 bevindt het java.security bestand zich in de $JAVA_HOME/jre/lib/security map. Voor Java 11 en hoger bevindt het bestand zich in de $JAVA_HOME/conf/security map.

Uw app compileren

Wanneer u apps bouwt om te werken met gegevensresources in Azure Blob Storage, communiceert uw code voornamelijk met drie resourcetypen: opslagaccounts, containers en blobs. Voor meer informatie over deze resourcetypen, hoe deze zich verhouden tot elkaar en hoe apps communiceren met resources, raadpleegt u Begrijpen hoe apps communiceren met Blob Storage-gegevensresources.

De volgende handleidingen laten zien hoe u toegang krijgt tot gegevens en specifieke acties uitvoert met behulp van de Azure Storage-clientbibliotheek voor Java:

Guide	Beschrijving
Beleid voor opnieuw proberen configureren	Implementeer beleid voor opnieuw proberen voor clientbewerkingen.
Blobs kopiëren	Kopieer een blob van de ene locatie naar de andere.
Een container maken	Blobcontainers maken.
Een SAS voor gebruikersdelegatie maken	Maak een SAS voor gebruikersdelegering voor een container of blob.
Blob-leases maken en beheren	Een vergrendeling op een blob tot stand brengen en beheren.
Containerleases maken en beheren	Een vergrendeling voor een container tot stand brengen en beheren.
Blobs verwijderen en herstellen	Verwijder blobs en als voorlopig verwijderen is ingeschakeld, herstelt u verwijderde blobs.
Containers verwijderen en herstellen	Verwijder containers en als voorlopig verwijderen is ingeschakeld, herstelt u verwijderde containers.
Blobs downloaden	Download blobs met behulp van tekenreeksen, streams en bestandspaden.
Blobs zoeken met behulp van tags	Stel tags in en haal ze op en gebruik tags om blobs te vinden.
Blobs vermelden	Geef blobs op verschillende manieren weer.
Containers weergeven	Lijst met containers in een account en de verschillende opties die beschikbaar zijn om een vermelding aan te passen.
Eigenschappen en metagegevens beheren (blobs)	Eigenschappen en metagegevens voor blobs ophalen en instellen.
Eigenschappen en metagegevens beheren (containers)	Eigenschappen en metagegevens voor containers ophalen en instellen.
Prestaties afstemmen voor gegevensoverdracht	Optimaliseer de prestaties voor gegevensoverdrachtbewerkingen.
De toegangslaag van een blob instellen of wijzigen	Stel de toegangslaag voor een blok-blob in of wijzig deze.
Blobs uploaden	Meer informatie over het uploaden van blobs met behulp van tekenreeksen, streams, bestandspaden en andere methoden.

Share via