Udostępnij za pomocą

Szybki start: rozszerzenie Quarkus dla usługi Azure Blob Storage

Rozpocznij pracę z rozszerzeniem Quarkus dla usługi Azure Blob Storage, aby zarządzać obiektami blob i kontenerami. W tym artykule wykonasz kroki, aby wypróbować przykładowy kod dla podstawowych zadań.

Dokumentacja referencyjna | Kod źródłowy biblioteki | Pakiet (Maven) | Przykład

Wymagania wstępne

Konfigurowanie

Ta sekcja przeprowadzi Cię przez proces przygotowywania projektu do pracy z rozszerzeniami Quarkus dla usługi Azure Blob Storage.

Pobieranie przykładowej aplikacji

Przykładowa aplikacja używana w tym przewodniku szybkiego startu to podstawowa aplikacja Quarkus.

Użyj narzędzia git , aby pobrać kopię aplikacji do środowiska deweloperskiego i przejść do storage-blob-quarkus katalogu.

git clone https://github.com/Azure-Samples/quarkus-azure.git
cd quarkus-azure
git checkout 2025-01-20
cd storage-blob-quarkus

Uwierzytelnij się w Azure i autoryzuj dostęp do danych blob

Żądania aplikacji do usługi Azure Blob Storage muszą być autoryzowane. Użycie DefaultAzureCredential biblioteki klienta tożsamości platformy Azure to zalecane podejście do implementowania połączeń bez hasła z usługami platformy Azure w kodzie, w tym usługi Blob Storage. To podejście obsługuje rozszerzenie Quarkus dla usług platformy Azure.

DefaultAzureCredential to implementacja łańcucha poświadczeń dostarczana przez bibliotekę klienta tożsamości platformy Azure dla języka Java. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda ma być używana w czasie wykonywania. Takie podejście umożliwia aplikacji używanie różnych metod uwierzytelniania w różnych środowiskach (lokalnych i produkcyjnych) bez implementowania kodu specyficznego dla środowiska.

Kolejność i lokalizacje poszukiwań poświadczeń przez DefaultAzureCredential można znaleźć w przeglądzie biblioteki Azure Identity.

W tym przewodniku Szybki start aplikacja uwierzytelnia się przy użyciu poświadczeń logowania interfejsu wiersza polecenia platformy Azure podczas uruchamiania lokalnego. Po wdrożeniu na platformie Azure aplikacja może następnie użyć tożsamości zarządzanej. To przejście między środowiskami nie wymaga żadnych zmian w kodzie.

Przypisywanie ról do konta użytkownika usługi Microsoft Entra

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych obiektów blob, ma odpowiednie uprawnienia. Będziesz potrzebować kontrybutora danych obiektu blob, aby odczytywać i zapisywać dane obiektów blob. Aby przypisać sobie tę rolę, musisz mieć przypisaną rolę Administratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write . Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Aby uzyskać więcej informacji na temat roli Współautor danych obiektu blob usługi Storage , zobacz Współautor danych obiektu blob usługi Storage. Aby uzyskać więcej informacji na temat dostępnych zakresów przypisań ról, zobacz Zrozumienie zakresu dla Azure RBAC.

W tym scenariuszu przypiszesz uprawnienia do swojego konta użytkownika, w odniesieniu do konta magazynowego, aby przestrzegać zasady najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do konta użytkownika zostanie przypisana rola Współautor danych obiektu blob usługi Storage , która zapewnia zarówno dostęp do odczytu, jak i zapisu do danych obiektów blob na koncie magazynu.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

  1. W portalu Azure znajdź konto usługi Storage za pomocą głównego paska wyszukiwania lub lewego panelu nawigacyjnego.

  2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (IAM) z menu po lewej stronie.

  3. Na stronie Kontrola dostępu (IAM) wybierz kartę Przypisania ról.

  4. Wybierz + Dodaj z górnego menu, a następnie Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

    Zrzut ekranu przedstawiający sposób przypisywania roli.

  5. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Współautor danych obiektu blob usługi Storage i wybierz pasujący wynik, a następnie wybierz pozycję Dalej.

  6. W obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka główna usługi, a następnie wybierz pozycję + Wybierz członków.

  7. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

  8. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Zaloguj się i połącz kod aplikacji z platformą Azure przy użyciu opcji DefaultAzureCredential

Dostęp do danych na koncie magazynowania można autoryzować, wykonując następujące czynności:

  1. Upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę na koncie magazynowym. W poniższym przykładzie pokazano, jak uwierzytelniać się za pośrednictwem interfejsu wiersza polecenia platformy Azure:

    az login

  2. Upewnij się, że podajesz punkt końcowy konta usługi Azure Blob Storage. W poniższym przykładzie pokazano, jak ustawić punkt końcowy przy użyciu zmiennej QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT środowiskowej za pośrednictwem interfejsu wiersza polecenia platformy Azure. Przed uruchomieniem polecenia zastąp <resource-group-name> i <storage-account-name> nazwami swojej grupy zasobów i konta magazynu.

    export QUARKUS_AZURE_STORAGE_BLOB_ENDPOINT=$(az storage account show \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --query 'primaryEndpoints.blob' \
    --output tsv)

Uwaga / Notatka

Po wdrożeniu na platformie Azure należy włączyć tożsamość zarządzaną dla aplikacji i skonfigurować konto magazynu tak, aby umożliwiło połączenie z tą tożsamością zarządzaną. Aby uzyskać więcej informacji na temat konfigurowania tego połączenia między usługami platformy Azure, zobacz Uwierzytelnianie aplikacji Java hostowanych na platformie Azure.

Uruchamianie aplikacji przykładowej

Przykładowy kod wykonuje następujące akcje:

  • Wprowadza obiekt klienta, który jest już autoryzowany do dostępu do danych za pośrednictwem DefaultAzureCredential rozszerzenia Quarkus dla usługi Azure Blob Storage.
  • Tworzy kontener na koncie przechowywania.
  • Przesyła obiekt blob do kontenera.
  • Wyświetla listę obiektów blob w kontenerze.
  • Pobiera dane obiektu blob do lokalnego systemu plików.
  • Usuwa zasoby obiektu blob i kontenera utworzone przez aplikację.
  • Usuwa lokalne źródło i pobrane pliki.

Uruchom aplikację w trybie JVM, używając następującego polecenia:

mvn package
java -jar ./target/quarkus-app/quarkus-run.jar

Dane wyjściowe aplikacji są podobne do następujących przykładów (wartości UUID pominięte w celu zapewnienia czytelności):

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

Przed rozpoczęciem procesu oczyszczania sprawdź folder danych dla dwóch plików. Można je porównać i zaobserwować, że są identyczne.

Opcjonalnie możesz uruchomić przykład w trybie natywnym. Aby to zrobić, musisz mieć zainstalowaną maszynę GraalVM lub użyć obrazu konstruktora do utworzenia natywnego pliku wykonywalnego. Aby uzyskać więcej informacji, zobacz Tworzenie natywnego pliku wykonywalnego. Ten przewodnik Szybki start używa platformy Docker jako środowiska uruchomieniowego kontenera do tworzenia natywnego pliku wykonywalnego systemu Linux. Jeśli nie zainstalowano platformy Docker, możesz pobrać ją z witryny internetowej platformy Docker.

Uruchom następujące polecenie, aby skompilować i wykonać natywny plik wykonywalny w środowisku systemu Linux:

mvn package -Dnative -Dquarkus.native.container-build
./target/storage-blob-1.0.0-SNAPSHOT-runner

Omówienie przykładowego kodu

Następnie zapoznasz się z przykładowym kodem, aby dowiedzieć się, jak to działa.

Wstrzykiwanie obiektu klienta z autoryzowanym dostępem

Praca z dowolnym zasobem platformy Azure przy użyciu zestawu SDK rozpoczyna się od utworzenia obiektu klienta. Rozszerzenie Quarkus dla usługi Azure Blob Storage automatycznie wprowadza obiekt klienta z autoryzowanym dostępem przy użyciu polecenia DefaultAzureCredential.

Aby pomyślnie wstrzyknąć obiekt klienta, najpierw należy dodać rozszerzenia quarkus-arc i quarkus-azure-storage-blob do pliku pom.xml jako zależności:

<properties>
    <quarkus.platform.version>3.17.7</quarkus.platform.version>
    <quarkus.azure.services.version>1.1.1</quarkus.azure.services.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>${quarkus.platform.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.quarkiverse.azureservices</groupId>
            <artifactId>quarkus-azure-services-bom</artifactId>
            <version>${quarkus.azure.services.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-arc</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkiverse.azureservices</groupId>
        <artifactId>quarkus-azure-storage-blob</artifactId>
    </dependency>
</dependencies>

Rozszerzenie quarkus-arc jest wymagane do użycia tej @Inject adnotacji w celu wstrzyknięcia obiektu klienta do Twojego kodu aplikacji. Zależności quarkus-bom i quarkus-azure-services-bom służą do zarządzania wersjami platformy Quarkus i rozszerzenia Quarkus dla usług platformy Azure.

Następnie możesz wstrzyknąć obiekt klienta do kodu aplikacji przy użyciu @Inject adnotacji:

@Inject
BlobServiceClient blobServiceClient;

To wszystko, czego potrzebujesz, aby uzyskać obiekt klienta przy użyciu rozszerzenia Quarkus dla usługi Azure Blob Storage. Aby upewnić się, że obiekt klienta jest uprawniony do dostępu do konta magazynu w czasie działania, przed uruchomieniem aplikacji należy wykonać kroki opisane w poprzedniej sekcji Uwierzytelnianie na platformie Azure i autoryzacja dostępu do danych obiektów blob.

Zarządzanie obiektami blob i kontenerami

W poniższym przykładzie kodu pokazano, jak utworzyć kontener, przesłać obiekt blob, wymienić obiekty blob w kontenerze i pobrać obiekt blob.

Uwaga / Notatka

Zapisywanie w lokalnym systemie plików jest uznawane za złe rozwiązanie w aplikacjach natywnych dla chmury. Jednak w przykładzie użyto lokalnego systemu plików, aby zilustrować użycie przechowywania blob w sposób łatwy do sprawdzenia przez użytkownika. Podczas przechodzenia aplikacji do środowiska produkcyjnego przejrzyj opcje magazynowania i wybierz najlepszą opcję dla Twoich potrzeb. Aby uzyskać więcej informacji, zobacz Przegląd dostępnych opcji magazynowania.

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

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

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

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

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

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

Te operacje są podobne do tych opisanych w przewodniku Szybki start: biblioteka klienta usługi Azure Blob Storage dla środowiska Java SE. Aby uzyskać bardziej szczegółowe wyjaśnienia kodu, zobacz następujące sekcje w tym przewodniku Szybki start:

Czyszczenie

Możesz skorzystać z linków w sekcji Następne kroki , aby wdrożyć aplikację Quarkus na platformie Azure. Możesz też wyczyścić konto magazynowe, usuwając grupę zasobów. Aby uzyskać więcej informacji, zobacz Azure Resource Manager - Grupa zasobów i usuwanie zasobów.

Dalsze kroki

Przykłady usługi Azure Storage i przewodniki dla deweloperów dla języka JavaWdrażanie aplikacji Java z Quarkus w klastrze Azure Kubernetes ServiceWdrażanie aplikacji Java z Quarkus w Azure Container Apps

  • Last updated on