Exercício – Configurar e inicializar a biblioteca de clientes

Concluído

O fluxo de trabalho típico para aplicativos que usam o Armazenamento de Blobs do Azure é o seguinte:

1. Recuperar configuração: na inicialização, carregue a configuração da conta de armazenamento, normalmente uma cadeia de conexão de conta de armazenamento.

2. Inicializar o cliente: para inicializar a biblioteca de clientes do Armazenamento do Azure, use a cadeia de conexão. Essa inicialização cria os objetos que o aplicativo usa para trabalhar com a API de Armazenamento de Blobs.

3. Usar: Para operar em contêineres e blobs, faça chamadas à API usando a biblioteca de clientes.

Configurar a cadeia de conexão

Antes de executar seu aplicativo, obtenha a cadeia de conexão para a conta de armazenamento que você usa. Você pode usar qualquer interface de gerenciamento do Azure para obtê-la, incluindo o portal do Azure, a CLI do Azure e o Azure PowerShell. Ao configurar o aplicativo Web para executar seu código perto do final deste módulo, use a CLI do Azure para obter a cadeia de conexão para a conta de armazenamento que você criou anteriormente.

As cadeias de conexão da conta de armazenamento incluem a chave de conta. Considere a chave de conta como um segredo e sempre armazene-a com segurança. Aqui, você armazena a cadeia de conexão em uma configuração de aplicativo do Serviço de Aplicativo. As configurações de aplicativo do Serviço de Aplicativo são um local seguro para segredos do aplicativo. Esse design não dá suporte ao desenvolvimento local e não é uma solução robusta de ponta a ponta por conta própria.

Importante

Este exemplo de código usa uma cadeia de conexão para autorizar o acesso à sua conta de armazenamento. Essa configuração é para fins de exemplo. As cadeias de conexão e as chaves de acesso da conta devem ser usadas com cuidado no código do aplicativo. Se a chave de acesso da conta for perdida ou colocada acidentalmente em um local inseguro, o serviço poderá ficar vulnerável. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados.

Para otimizar a segurança, a Microsoft recomenda o uso do Microsoft Entra ID com identidades gerenciadas para autorizar solicitações relativas a dados de blobs, filas de espera e tabelas sempre que possível. Para saber mais, confira Autorizar o acesso a blobs usando o Microsoft Entra ID.

Inicializar o modelo de objeto do Armazenamento de Blobs

No SDK do Armazenamento do Azure para .NET, o padrão para uso do Armazenamento de Blobs é o seguinte:

1. Crie uma instância de um novo objeto BlobServiceClient e forneça a cadeia de conexão para sua conta de armazenamento.

2. Para obter um BlobContainerClient, chame GetBlobContainerClient no BlobServiceClient com o nome do contêiner com o qual você deseja interagir ou que deseja criar.

No código, essas etapas têm a aparência a seguir.

BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);

Nenhuma parte desse código de inicialização faz chamadas pela rede. Esse fato significa que algumas exceções que ocorrem devido a informações incorretas não são lançadas até mais tarde. Por exemplo, se uma cadeia de conexão formatada incorretamente for fornecida ao construtor da classe BlobServiceClient, uma exceção será gerada imediatamente. No entanto, se a cadeia de conexão apontar para uma conta de armazenamento que não existe, nenhuma exceção será gerada até que você tente realizar uma operação na conta de armazenamento.

No SDK de Armazenamento do Azure para Java, o padrão para uso do Armazenamento de Blobs consiste nas seguintes etapas:

1. Crie um BlobServiceClient instanciando um novo objeto de BlobServiceClientBuilder usando a cadeia de conexão para sua conta de armazenamento.

2. Obtenha um BlobContainerClient chamando o método getBlobContainerClient no BlobServiceClient com o nome do contêiner com o qual você deseja interagir ou criar.

No código, essas etapas têm a aparência a seguir.

BlobServiceClient blobServiceClient = BlobServiceClientBuilder()
    .connectionString(connectionString)
    .buildClient();
BlobContainerClient containerClient = blobServiceClient.getBlobContainerClient(containerName);

Nenhuma parte desse código de inicialização faz chamadas pela rede. Esse fato significa que algumas exceções que ocorrem devido a informações incorretas não são lançadas até mais tarde. Por exemplo, se uma cadeia de conexão formatada incorretamente for fornecida ao BlobServiceClientBuilder, uma exceção será gerada imediatamente. No entanto, se a cadeia de conexão apontar para uma conta de armazenamento que não existe, nenhuma exceção será gerada até que você tente realizar uma operação na conta de armazenamento.

Criar contêineres na inicialização

Para criar um contêiner quando o aplicativo for iniciado ou quando o aplicativo tentar usar um contêiner pela primeira vez, chame CreateIfNotExistsAsync em um BlobContainerClient.

CreateIfNotExistsAsync não gerará uma exceção se o contêiner já existir, mas faz uma chamada de rede para o Armazenamento de Blobs do Azure. Chame-o uma vez durante a inicialização, não toda vez que tentar usar um contêiner.

Para criar um contêiner quando seu aplicativo for iniciado ou quando ele tentar usá-lo pela primeira vez, chame exists em um BlobContainerClient para verificar se um contêiner já existe. Se ele não existir, chame create. Chame-o uma vez durante a inicialização, não toda vez que tentar usar um contêiner.

Exercício

Clonar e explorar o aplicativo não concluído

1. Primeiro, clone o aplicativo inicial do GitHub. Para obter uma cópia do código-fonte e abri-la no editor, execute os seguintes comandos na CLI do Azure Shell:

   git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
   cd mslearn-store-data-in-azure/store-app-data-with-azure-blob-storage/src/start
   code .
   

2. No editor, abra o arquivo Controllers/FilesController.cs. Não há trabalho a fazer aqui, mas veja rapidamente o que o aplicativo faz.

   Esse controlador implementa uma API com três ações:

   • Índice: (GET /api/Files) retorna uma lista de URLs, uma para cada arquivo que foi carregado. O front-end do aplicativo chama esse método para criar uma lista de hiperlinks para os arquivos carregados.
   • Carregar: (POST /api/Files) recebe um arquivo carregado e o salva.
   • Baixar: (GET /api/Files/{filename}) baixa um arquivo individual pelo nome.

   Para fazer o respectivo trabalho, cada método usa uma instância de IStorage chamada storage. Há uma implementação incompleta de IStorage em Models/BlobStorage.cs para preencher.

Adicionar o pacote NuGet

• Adicione uma referência ao SDK do Armazenamento do Microsoft Azure. Execute os seguintes comandos na CLI do Azure Shell:

  dotnet add package Azure.Storage.Blobs
  dotnet restore
  

  Esse comando garante que você esteja usando a versão mais recente da biblioteca de clientes do Armazenamento de Blobs.

Configurar

Os valores de configuração necessários são a cadeia de conexão de conta de armazenamento e o nome do contêiner que o aplicativo usa para armazenar arquivos. Neste módulo, você só executará o aplicativo no Serviço de Aplicativo do Azure. Siga as práticas recomendadas do Serviço de Aplicativo e armazene os valores nas configurações do aplicativo do Serviço de Aplicativo. Você faz isso ao criar a instância do Serviço de Aplicativo. Não há nada que você precise fazer no momento.

Quando se trata de usar a configuração, o aplicativo inicial inclui os detalhes técnicos necessários. O parâmetro do construtor IOptions<AzureStorageConfig> em BlobStorage tem duas propriedades: a cadeia de conexão de conta de armazenamento e o nome do contêiner que seu aplicativo usa para armazenar blobs. Há um código no método ConfigureServices de Startup.cs que carrega os valores da configuração quando o aplicativo é iniciado.

Inicializar

1. No editor, abra Models/BlobStorage.cs. Na parte superior do arquivo, adicione as instruções using a seguir para prepará-lo para o código que você adicionará.

   using Azure;
   using Azure.Storage.Blobs;
   using Azure.Storage.Blobs.Models;
   

2. Localize o método Initialize. Seu aplicativo chama esse método quando ele usa BlobStorage pela primeira vez. Se estiver curioso, você poderá examinar ConfigureServices em Startup.cs para ver como a chamada é feita.

   Initialize é o local em que você quer criar o contêiner, caso ele ainda não exista. Substitua a implementação atual de Initialize pelo código a seguir e salve seu trabalho usando CTRL+S.

   public Task Initialize()
   {
       BlobServiceClient blobServiceClient = new BlobServiceClient(storageConfig.ConnectionString);
       BlobContainerClient containerClient = blobServiceClient.GetBlobContainerClient(storageConfig.FileContainerName);
       return containerClient.CreateIfNotExistsAsync();
   }
   

Clonar e explorar o aplicativo não concluído

1. Primeiro, clone o aplicativo inicial do GitHub. Para obter uma cópia do código-fonte e abri-la no editor, execute os seguintes comandos na CLI do Azure Shell:

   git clone https://github.com/MicrosoftDocs/mslearn-store-data-in-azure.git
   cd mslearn-store-data-in-azure/store-java-ee-application-data-with-azure-blob-storage/start
   code .
   

2. No editor, abra o arquivo src/main/java/com/microsoft/azure/samples/jsf/IndexBean.java. Não há trabalho a fazer aqui, mas veja rapidamente o que o aplicativo faz.

   Esse bean com escopo de solicitação implementa três ações que são usadas pela página do Java Server Faces (JSF) src/main/webapp/index.xhtml:

   • listFileNames: retorna uma lista de nomes de arquivo, um para cada arquivo carregado. A página index.xhtml chama esse método para criar uma lista de hiperlinks para os arquivos carregados.
   • carregar: recebe um arquivo carregado e o salva. O conteúdo do arquivo e os metadados são injetados na propriedade uploadedFile pela estrutura JSF.
   • Baixar: baixa um arquivo individual pelo nome.

   Para fazer seu trabalho, cada método usa uma instância Storage chamada storage. Há uma implementação incompleta de Storage em src/main/java/com/microsoft/azure/samples/service/BlobStorage.java para preencher.

Adicionar o SDK de Armazenamento do Azure para referência Java

É recomendável usar a BOM do Azure para adicionar bibliotecas de clientes do Azure ao projeto. Ela fornece um modo simples e elegante de orquestrar usando várias bibliotecas de cliente do Azure, garantindo conflitos mínimos de dependência.

1. No editor, abra o arquivo pom.xml.

2. Para adicionar a BOM do Azure ao projeto, adicione a seção dependencyManagement a seguir na marca xml project.

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>com.azure</groupId>
         <artifactId>azure-sdk-bom</artifactId>
         <version>1.0.6</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>
   

3. Para adicionar o SDK de Armazenamento do Microsoft Azure para Java, adicione o dependency a seguir à seção xml project/dependencies.

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

Configurar

Os valores de configuração necessários são a cadeia de conexão da conta de armazenamento e o nome do contêiner que o aplicativo usa para armazenar arquivos. Neste módulo, você só executará o aplicativo no Serviço de Aplicativo do Azure. Siga as práticas recomendadas do Serviço de Aplicativo e armazene os valores nas configurações do aplicativo do Serviço de Aplicativo. Você faz isso quando criamos a instância do Serviço de Aplicativo. Não há nada que você precise fazer no momento.

Quando se trata de usar a configuração, as definições do aplicativo de serviço são passadas como variáveis de ambiente para o código do aplicativo. Leia-os no código de inicialização.

Inicializar

1. No editor, abra src/main/java/com/microsoft/azure/samples/service/BlobStorage.java. Na parte superior do arquivo, adicione as instruções import a seguir para prepará-lo para o código que você adicionará.

   import java.util.stream.Collectors;
   
   import com.azure.storage.blob.BlobClient;
   import com.azure.storage.blob.BlobContainerClient;
   import com.azure.storage.blob.BlobServiceClient;
   import com.azure.storage.blob.BlobServiceClientBuilder;
   import com.azure.storage.blob.models.BlobItem;
   

2. Adicione uma propriedade de classe na classe BlobStorage para manter a referência BlobContainerClient.

   private BlobContainerClient blobContainerClient;
   

   Dica

   Os clientes do Azure estão sem estado e thread-safe. É recomendável armazenar em cache as instâncias deles quando aplicável. Por exemplo, o aplicativo em que você está trabalhando usa apenas um contêiner com nome constante. Portanto, é melhor armazená-lo em cache no escopo do tempo de vida do aplicativo. BlobStorage é anotado com @Singleton, portanto, o armazenamento de referência BlobContainerClient em seu campo é recomendado.

3. Localize o método init com anotação @PostConstruct. Seu aplicativo chama esse método depois que a instância BlobStorage é criada e antes de ser usada pela primeira vez.

   init é o local onde criar seu contêiner se ele ainda não existir. Substitua a implementação atual de init pelo código a seguir e salve seu trabalho.

   @PostConstruct
   private void init() {
       String connectionString = System.getenv("STORAGE_CONNECTION_STRING");
       String containerName = System.getenv("STORAGE_CONTAINER_NAME");
       BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
           .connectionString(connectionString)
           .buildClient();
       blobContainerClient = blobServiceClient.getBlobContainerClient(containerName);
       if (!blobContainerClient.exists()) {
           blobContainerClient.create();
       }
   }