Rozpoczynanie pracy z usługą Azure Blob Storage i językiem Java

Artykuł
10/22/2024

W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Blob Storage przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka Java. Po nawiązaniu połączenia skorzystaj z przewodników dla deweloperów , aby dowiedzieć się, jak kod może działać na kontenerach, obiektach blob i funkcjach usługi Blob Storage.

Jeśli chcesz zacząć od kompletnego przykładu, zobacz Szybki start: biblioteka klienta usługi Azure Blob Storage dla języka Java.

Przykłady kodu | | źródłowego biblioteki źródłowej pakietu referencyjnego | interfejsu API (Maven) | Prześlij opinię

Wymagania wstępne

Subskrypcja platformy Azure — utwórz jedną bezpłatnie
Konto usługi Azure Storage — tworzenie konta magazynu
Zestaw Java Development Kit (JDK) w wersji 8 lub nowszej
Narzędzie Apache Maven jest używane do zarządzania projektami w tym przykładzie

konfigurowanie projektu

Uwaga

W tym artykule użyto narzędzia kompilacji Maven do skompilowania i uruchomienia przykładowego kodu. Inne narzędzia kompilacji, takie jak Gradle, współpracują również z zestawem Azure SDK dla języka Java.

Użyj narzędzia Maven, aby utworzyć nową aplikację konsolową lub otworzyć istniejący projekt. Wykonaj następujące kroki, aby zainstalować pakiety i dodać niezbędne import dyrektywy.

Instalowanie pakietów

pom.xml Otwórz plik w edytorze tekstów. Zainstaluj pakiety, dołączając plik BOM lub uwzględniając bezpośrednią zależność.

Uwzględnij plik BOM

Dodaj element azure-sdk-bom , aby pobrać zależność od najnowszej wersji biblioteki. W poniższym fragmencie kodu zastąp {bom_version_to_target} symbol zastępczy numerem wersji. Korzystanie z zestawu azure-sdk-bom uniemożliwia określenie wersji poszczególnych zależności. Aby dowiedzieć się więcej na temat modelu BOM, zobacz ARTYKUŁ README zestawu Azure SDK 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>

Dodaj następujące elementy zależności do grupy zależności. Zależność azure-identity jest wymagana w przypadku połączeń bez hasła z usługami platformy Azure.

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

Uwzględnij zależność bezpośrednią

Aby podjąć zależność od określonej wersji biblioteki, dodaj bezpośrednią zależność do projektu:

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

Uwzględnij dyrektywy importu

Następnie otwórz plik kodu i dodaj niezbędne import dyrektywy. W tym przykładzie dodamy następujące dyrektywy w pliku 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.*;

Informacje o bibliotece klienta obiektów blob:

com.azure.storage.blob: zawiera klasy podstawowe (obiekty klienta), których można użyć do działania w usłudze, kontenerach i obiektach blob.
com.azure.storage.blob.models: zawiera klasy narzędzi, struktury i typy wyliczenia.
com.azure.storage.blob.specialized: zawiera klasy, których można użyć do wykonywania operacji specyficznych dla typu obiektu blob (na przykład: uzupełnialnych obiektów blob).

Autoryzowanie dostępu i nawiązywanie połączenia z usługą Blob Storage

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient . Można również użyć klasy BlobServiceAsyncClient do programowania asynchronicznego. Ten obiekt jest punktem wyjścia do interakcji z zasobami danych na poziomie konta magazynu. Można go użyć do działania na koncie magazynu i jego kontenerach. Możesz również użyć klienta usługi, aby utworzyć klientów kontenerów lub klientów obiektów blob, w zależności od zasobu, z którym chcesz pracować.

Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Obiekt można autoryzować BlobServiceClient przy użyciu tokenu autoryzacji entra firmy Microsoft, klucza dostępu do konta lub sygnatury dostępu współdzielonego (SAS). Aby uzyskać optymalne zabezpieczenia, firma Microsoft zaleca używanie identyfikatora Entra firmy Microsoft z tożsamościami zarządzanymi w celu autoryzowania żądań względem danych obiektów blob. Aby uzyskać więcej informacji, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu identyfikatora Entra firmy Microsoft.

Aby autoryzować za pomocą identyfikatora Entra firmy Microsoft, musisz użyć podmiotu zabezpieczeń. Jakiego typu podmiot zabezpieczeń potrzebujesz, zależy od tego, gdzie działa aplikacja. Skorzystaj z poniższej tabeli jako przewodnika:

Gdzie działa aplikacja	Podmiot zabezpieczeń	Wskazówki
Maszyna lokalna (programowanie i testowanie)	Jednostka usługi	Aby dowiedzieć się, jak zarejestrować aplikację, skonfigurować grupę Firmy Microsoft Entra, przypisać role i skonfigurować zmienne środowiskowe, zobacz Autoryzowanie dostępu przy użyciu jednostek usługi dewelopera.
Maszyna lokalna (programowanie i testowanie)	Tożsamość użytkownika	Aby dowiedzieć się, jak skonfigurować grupę entra firmy Microsoft, przypisać role i zalogować się na platformie Azure, zobacz Autoryzowanie dostępu przy użyciu poświadczeń dewelopera.
Hostowane na platformie Azure	Tożsamość zarządzana	Aby dowiedzieć się, jak włączyć tożsamość zarządzaną i przypisać role, zobacz Autoryzowanie dostępu z aplikacji hostowanych na platformie Azure przy użyciu tożsamości zarządzanej.
Hostowane poza platformą Azure (na przykład aplikacje lokalne)	Jednostka usługi	Aby dowiedzieć się, jak zarejestrować aplikację, przypisać role i skonfigurować zmienne środowiskowe, zobacz Autoryzowanie dostępu z aplikacji lokalnych przy użyciu jednostki usługi aplikacji

Autoryzowanie dostępu przy użyciu elementu DefaultAzureCredential

Łatwym i bezpiecznym sposobem autoryzowania dostępu i nawiązywania połączenia z usługą Blob Storage jest uzyskanie tokenu OAuth przez utworzenie wystąpienia DefaultAzureCredential . Następnie możesz użyć tego poświadczenia, aby utworzyć obiekt BlobServiceClient .

Upewnij się, że masz poprawne zależności w pom.xml i niezbędne dyrektywy importu, zgodnie z opisem w temacie Konfigurowanie projektu.

W poniższym przykładzie użyto obiektu BlobServiceClientBuilder do skompilowania BlobServiceClient obiektu przy użyciu metody DefaultAzureCredentiali pokazano, jak utworzyć klientów kontenerów i obiektów blob, w razie potrzeby:

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

Użyj obiektu BlobServiceClientBuilder , aby skompilować obiekt BlobServiceClient przy użyciu tokenu SAS:

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

Aby dowiedzieć się więcej na temat generowania tokenów SAS i zarządzania nimi, zobacz następujące artykuły:

Uwaga

W przypadku scenariuszy, w których są używane sygnatury dostępu współdzielonego (SAS), firma Microsoft zaleca używanie sygnatury dostępu współdzielonego delegowania użytkowników. Sygnatura dostępu współdzielonego delegowania użytkownika jest zabezpieczona przy użyciu poświadczeń usługi Microsoft Entra zamiast klucza konta.

Utwórz wartość StorageSharedKeyCredential przy użyciu nazwy konta magazynu i klucza konta. Następnie użyj tego obiektu, aby zainicjować obiekt BlobServiceClient .

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

Obiekt można również utworzyć BlobServiceClient przy użyciu parametry połączenia.

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

Aby uzyskać informacje na temat uzyskiwania kluczy konta i wytycznych dotyczących najlepszych rozwiązań dotyczących prawidłowego zarządzania kluczami i ich ochrony, zobacz Zarządzanie kluczami dostępu do konta magazynu.

Ważne

Klucz dostępu do konta powinien być używany ostrożnie. Jeśli klucz dostępu do twojego konta zostanie utracony lub przypadkowo umieszczony w niezabezpieczonej lokalizacji, usługa może stać się podatna na zagrożenia. Każdy, kto ma klucz dostępu, może autoryzować żądania względem konta magazynu i efektywnie ma dostęp do wszystkich danych. DefaultAzureCredential zapewnia ulepszone funkcje zabezpieczeń i korzyści i jest zalecanym podejściem do zarządzania autoryzacją w usługach platformy Azure.

Konfigurowanie czasu wygaśnięcia JVM dla odnośników nazw DNS

Maszyna wirtualna Java (JVM) buforuje odpowiedzi z pomyślnych wyszukiwań nazw DNS przez określony okres, znany jako czas wygaśnięcia (TTL). Domyślna wartość czasu wygaśnięcia dla wielu maszyn JVM to -1, co oznacza, że JVM buforuje odpowiedź na czas nieokreślony lub do momentu ponownego uruchomienia maszyny JVM.

Ponieważ zasoby platformy Azure używają wpisów nazw DNS, które mogą ulec zmianie, zalecamy ustawienie wartości czasu wygaśnięcia JVM na 10 sekund. Ta konfiguracja gwarantuje, że zaktualizowany adres IP zasobu zostanie zwrócony przy użyciu następnego zapytania DNS.

Aby zmienić wartość czasu wygaśnięcia globalnie dla wszystkich aplikacji przy użyciu maszyny JVM, ustaw networkaddress.cache.ttl właściwość w java.security pliku.

networkaddress.cache.ttl=10

W przypadku języka Java 8 java.security plik znajduje się w $JAVA_HOME/jre/lib/security katalogu . W przypadku języka Java 11 lub nowszego $JAVA_HOME/conf/security plik znajduje się w katalogu .

Kompilowanie aplikacji

Podczas tworzenia aplikacji do pracy z zasobami danych w usłudze Azure Blob Storage kod wchodzi głównie w interakcję z trzema typami zasobów: kontami magazynu, kontenerami i obiektami blob. Aby dowiedzieć się więcej o tych typach zasobów, sposobie ich powiązania ze sobą i sposobie interakcji aplikacji z zasobami, zobacz Omówienie sposobu interakcji aplikacji z zasobami danych usługi Blob Storage.

W poniższych przewodnikach przedstawiono sposób uzyskiwania dostępu do danych i wykonywania określonych akcji przy użyciu biblioteki klienta usługi Azure Storage dla języka Java:

Przewodnik	opis
Konfigurowanie zasad ponawiania prób	Zaimplementuj zasady ponawiania dla operacji klienta.
Kopiowanie obiektów blob	Skopiuj obiekt blob z jednej lokalizacji do innej.
Tworzenie kontenera	Tworzenie kontenerów obiektów blob.
Tworzenie sygnatury dostępu współdzielonego delegowania użytkownika	Utwórz sygnaturę dostępu współdzielonego delegowania użytkownika dla kontenera lub obiektu blob.
Tworzenie dzierżaw obiektów blob i zarządzanie nimi	Ustanów blokadę obiektu blob i zarządzaj nią.
Tworzenie dzierżaw kontenerów i zarządzanie nimi	Ustanawianie blokady kontenera i zarządzanie nią.
Usuwanie i przywracanie obiektów blob	Usuń obiekty blob i jeśli włączono usuwanie nietrwałe, przywróć usunięte obiekty blob.
Usuwanie i przywracanie kontenerów	Usuń kontenery, a jeśli włączono usuwanie nietrwałe, przywróć usunięte kontenery.
Pobieranie obiektów blob	Pobierz obiekty blob przy użyciu ciągów, strumieni i ścieżek plików.
Znajdowanie obiektów blob przy użyciu tagów	Ustawianie i pobieranie tagów oraz używanie tagów do znajdowania obiektów blob.
Wyświetlanie listy obiektów blob	Wyświetlanie listy obiektów blob na różne sposoby.
Wyświetlanie listy kontenerów	Wyświetlanie listy kontenerów na koncie i różnych dostępnych opcji dostosowywania listy.
Zarządzanie właściwościami i metadanymi (obiektami blob)	Pobieranie i ustawianie właściwości i metadanych dla obiektów blob.
Zarządzanie właściwościami i metadanymi (kontenerami)	Pobieranie i ustawianie właściwości i metadanych dla kontenerów.
Dostrajanie wydajności na potrzeby transferów danych	Optymalizowanie wydajności operacji transferu danych.
Ustawianie lub zmienianie warstwy dostępu obiektu blob	Ustaw lub zmień warstwę dostępu dla blokowego obiektu blob.
Przekazywanie obiektów blob	Dowiedz się, jak przekazywać obiekty blob przy użyciu ciągów, strumieni, ścieżek plików i innych metod.

Udostępnij za pośrednictwem