Bibliotecas do Armazenamento Azure para Java
As bibliotecas de Armazenamento do Azure para Java fornecem classes para trabalhar com dados em sua conta de armazenamento do Azure e com a própria conta de armazenamento. Para obter mais informações sobre o Armazenamento do Azure, consulte Introdução ao Armazenamento do Azure.
Biblioteca de clientes para acesso a dados
A biblioteca de clientes do Armazenamento do Azure para Java dá suporte ao armazenamento de Blobs, armazenamento de filas, Arquivos do Azure e Azure Data Lake Storage Gen2 (biblioteca de visualização).
Adicionar o pacote ao seu projeto
Adicione as seguintes dependências ao arquivo Maven pom.xml conforme apropriado:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
<version>12.4.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-queue</artifactId>
<version>12.3.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-file-share</artifactId>
<version>12.2.0</version>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-file-datalake</artifactId>
<version>12.0.0-preview.6</version>
</dependency>
Para obter mais informações sobre como adicionar uma dependência em Java, consulte Adicionar uma dependência.
Exemplo de uso
O exemplo a seguir cria um contêiner de armazenamento e carrega um arquivo local no contêiner de armazenamento.
String yourSasToken = "<insert-your-sas-token>";
/* Create a new BlobServiceClient with a SAS Token */
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
.endpoint("https://your-storage-account-url.storage.windows.net")
.sasToken(yourSasToken)
.buildClient();
/* Create a new container client */
try {
containerClient = blobServiceClient.createBlobContainer("my-container-name");
} catch (BlobStorageException ex) {
// The container may already exist, so don't throw an error
if (!ex.getErrorCode().equals(BlobErrorCode.CONTAINER_ALREADY_EXISTS)) {
throw ex;
}
}
/* Upload the file to the container */
BlobClient blobClient = containerClient.getBlobClient("my-remote-file.jpg");
blobClient.uploadFromFile("my-local-file.jpg");
Para obter mais exemplos, examine o LEIAME da Biblioteca de Clientes.
Pacotes disponíveis
A tabela a seguir descreve as versões recomendadas da biblioteca de clientes de armazenamento para Java.
| Versão da biblioteca | Serviços com suporte | Maven | Referência/Javadoc | Origem, Leiame, Exemplos |
|---|---|---|---|---|
| Versão 12 | Blob, Fila, Arquivo e Data Lake |
Blob Fila Arquivo Data Lake |
Blob Fila Arquivo Data Lake |
Blob (Início Rápido) Fila Arquivo Data Lake |
| Versão 8 | Blob, Fila, Arquivo e Tabela | Todos os serviços | Referência da versão 8 | Todos os serviços (Início Rápido) |
Consulte a página Versões do SDK do Azure para obter detalhes sobre como instalar e usar os pacotes de visualização.
Biblioteca de clientes para gerenciamento de recursos
Use o provedor de recursos do Armazenamento do Azure para gerenciar contas de armazenamento, chaves de conta, camadas de acesso e muito mais. Para usar a biblioteca do provedor de recursos, adicione uma dependência ao arquivo Maven pom.xml . A versão mais recente da biblioteca do provedor de recursos está disponível no Maven.
Para obter mais informações sobre a biblioteca do provedor de recursos, consulte a Referência de gerenciamento . O código-fonte da biblioteca do provedor de recursos está disponível no repositório do SDK do Java do Azure.
O exemplo a seguir cria uma nova conta de armazenamento em sua assinatura e recupera suas chaves de acesso.
StorageAccount storageAccount = azureResourceManager.storageAccounts().define(storageAccountName)
.withRegion(Region.US_EAST)
.withNewResourceGroup(rgName)
.create();
// get a list of storage account keys related to the account
List<StorageAccountKey> storageAccountKeys = storageAccount.getKeys();
for (StorageAccountKey key : storageAccountKeys) {
System.out.println("Key name: " + key.keyName() + " with value "+ key.value());
}
Problemas conhecidos
Versões mais antigas do SDK de Armazenamento do Azure para Java (v12) têm um ou mais problemas críticos conhecidos, que são detalhados abaixo. Esses problemas podem afetar a gravação ou a leitura de dados de sua conta de Armazenamento do Azure. Se você estiver usando uma versão mais antiga de uma biblioteca de clientes, recomendamos que você atualize para a versão mais recente.
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 a 12.10.0, 12.19.0 a 12.22.0 | 12.22.1 | Atualizar para a versão mais recente |
| Data Lake do Arquivo do Azure | 12.0 a 12.7.0 | 12.8.0 | Atualizar para a versão mais recente |
| Compartilhamento de Arquivo do Azure | 12.0 a 12.4.1 | 12.5.0 | Atualizar para a versão mais recente |
| Fila de Armazenamento do Azure | 12.0 a 12.6.0 | 12.7.0 | Atualizar para a versão mais recente |
| criptografia Armazenamento de Blobs do Azure | 12.0 a 12.16.1 | 12.17.0 | Atualizar para a versão mais recente |
Se você tiver dúvidas ou precisar de ajuda adicional, crie um tíquete de suporte usando as seguintes opções:
- Tipo de problema: técnico
- Tipo de serviço: Armazenamento de Blobs
- Resumo: #JavaSDKv12
- Tipo de problema: desenvolvimento
- Subtipo de problema: biblioteca de cliente ou SDK
Lista de problemas conhecidos
-
Problema de substituição de buffer com
BlobOutputStream - Dados inválidos carregados durante novas tentativas
-
Carregar o retorno incorreto como bem-sucedido quando
IOExceptionocorrer -
Dados incorretos sendo baixados com
downloadToFile - Substituir parâmetro não honrado ao carregar um arquivo grande, resultando em substituição incorreta
- Operação de substituição invertida para o parâmetro de substituição, resultando em substituição incorreta
- Conteúdo da mensagem apagado incorretamente quando apenas o tempo limite de visibilidade é definido
- Criptografia do lado do cliente atualizada para usar o AES-GCM devido a vulnerabilidades de segurança no modo CBC
- Dados incorretos sendo baixados com downloadToFile() quando solicitações REST subjacentes são repetidas
- Mensagem de erro InvalidHeaderValue ao usar a versão beta do SDK
1. Problema de substituição de buffer com BlobOutputStream
Descrição do problema
Se um BlobOutputStream objeto for usado para carregar blobs, em alguns cenários esse uso poderá resultar em um objeto inválido sendo gravado em Armazenamento de Blobs do Azure.
BlobOutputStream o objeto pode ser obtido por meio de BlockBlobClient.getBlobOutputStream().
Carregar um arquivo maior que o valor de MaxSingleUploadSize usar o write() método da BlobOutputStream classe resulta em um objeto inválido sendo gravado em Armazenamento de Blobs do Azure. O valor padrão de MaxSingleUploadSize é 256 MiB. Você pode alterar esse valor chamando o setMaxSingleUploadSizeLong() método da ParallelTransferOptions classe .
Depois que o tamanho dos dados de entrada cruza o MaxSingleUploadSize, o write() método de BlobOutputStream retorna antes de fazer uma cópia profunda dos dados de entrada. Se o aplicativo de invocação substituir a matriz de bytes de dados de entrada por outros dados antes que a cópia profunda ocorra, os dados inválidos poderão ser gravados no blob.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 a 12.10.0 | 12.10.1 | Atualização para a versão mais recente ou mínima 12.22.1 |
Etapas recomendadas
- Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
- Verifique se o código do aplicativo está chamando
BlockBlobClient.getBlobOutputStream(). Se você encontrá-lo, seu aplicativo será afetado.
Além disso, você pode identificar os blobs potencialmente afetados devido a esse problema em sua conta de Armazenamento do Azure. Siga as etapas abaixo para identificar blobs potencialmente afetados:
- Verifique se o aplicativo está usando
BlobOutputStreampara carregar blobs (obtidos por meio deBlockBlobClient.getBlobOutputStream()). Caso contrário, esse problema não afetará seu aplicativo. No entanto, ainda recomendamos que você atualize seu aplicativo para usar a versão 12.22.1 ou posterior. - Obtenha o
MaxSingleUploadSizevalor do aplicativo (256 MiB por padrão). Examine seu código quanto aosetMaxSingleUploadSizeLong()método da classe e obtenha oParallelTransferOptionsvalor fornecido para essa propriedade. - Identificar a janela de tempo quando seu aplicativo usou a versão da biblioteca de clientes com esse problema (12.0 a 12.10.0)
- Identifique todos os blobs carregados nesta janela de tempo. Você pode obter uma lista de blobs chamando a operação com o
List BlobsPowerShell do PowerShell, a CLI do Azure ou outra ferramenta. Você também pode aproveitar o recurso de inventário de blobs.
Seguir estas etapas indicará blobs que são potencialmente afetados pelo problema crítico e podem ser inválidos. Inspecione esses blobs para determinar quais podem ser inválidos.
Voltar à lista de problemas conhecidos
2. Dados inválidos carregados durante novas tentativas
Descrição do problema
As bibliotecas de cliente listadas abaixo têm um bug que pode carregar dados incorretos durante novas tentativas após uma solicitação de serviço com falha (por exemplo, uma repetição causada por uma resposta HTTP 500).
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 a 12.6.1 | 12.7.0 | Atualização para a versão mais recente ou mínima 12.22.1 |
| Data Lake do Arquivo do Azure | 12.0 a 12.1.2 | 12.2.0 | Atualização para a versão mais recente ou mínimo 12.8.0 |
| Compartilhamento de Arquivo do Azure | 12.0 a 12.4.1 | 12.5.0 | Atualização para a versão mais recente ou mínimo 12.5.0 |
Etapas recomendadas
- Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Observação: o Azure não tem a capacidade de recuperar objetos gravados incorretamente. Como qualquer impacto potencial ocorre antes do upload, o Azure não tem uma cópia válida de nenhum objeto afetado. Se você tiver o arquivo original, ele poderá ser recarregado para sua conta de armazenamento.
Voltar à lista de problemas conhecidos
3. Carregar incorretamente retornando como bem-sucedido quando IOException ocorrer
Descrição do problema
Todas as sobrecargas de void BlobClient.upload() e void BlobClient.uploadWithResponse() capturam silenciosamente respostas de erro do serviço de armazenamento. O método deve retornar ou gerar como indicador de êxito/erro. A exceção, que deveria ter sido registrada e propagada, em vez disso, seria gravada diretamente no erro padrão e depois engolida, apesar de ter sido o único indicador de falha para a API. Portanto, o método retorna com êxito, fazendo com que o chamador pense que a operação foi concluída. Isso faz com que o blob não tenha sido gravado no armazenamento, apesar da biblioteca indicar êxito.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 a 12.4.0 | 12.5.0 | Atualização para a versão mais recente ou mínima 12.22.1 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
4. Dados incorretos sendo baixados com downloadToFile
Descrição do problema
A gravação de buffer assíncrono tem uma condição de corrida em que o buffer entre o fluxo de rede e o fluxo de arquivos pode ser reutilizado para dados de entrada antes de ser liberado para o arquivo. Isso faz com que o arquivo baixado seja corrompido, onde alguns dados se repetem imediatamente, substituindo os dados válidos em seu lugar. O objeto no Armazenamento ainda está correto.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 a 12.2.0 | 12.3.0 | Atualização para a versão mais recente ou mínima 12.22.1 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
5. Substituir parâmetro não respeitado ao carregar um arquivo grande, resultando em substituição incorreta
Descrição do problema
O sinalizador de substituição não está sendo respeitado nos casos em que há outro trabalho de upload paralelo em andamento. Isso resulta na não substituição de um objeto no Armazenamento quando pretendido.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.0 | 12.1.0 | Atualização para a versão mais recente ou mínima 12.22.1 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
6. Operação de substituição invertida para o parâmetro de substituição, resultando em substituição incorreta
Descrição do problema
O parâmetro de substituição e a operação de substituição são revertidos nas DataLakeFileClient.flush(long) funções e DataLakeFileClient.flush(long, bool) . Nenhum outro comportamento da biblioteca chama esses métodos. Isso resulta na substituição de um objeto no Armazenamento quando o usuário não pretendia e falha ao substituir quando pretendido.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Data Lake do Arquivo do Azure | 12.0 a 12.7.0 | 12.8.0 | Atualização para a versão mais recente ou mínimo 12.8.0 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
7. Conteúdo da mensagem apagado incorretamente quando apenas o tempo limite de visibilidade é definido
Descrição do problema
O conteúdo da mensagem da fila é apagado por erro quando apenas o tempo limite de visibilidade foi definido ou atualizado.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Fila de Armazenamento do Azure | 12.0 a 12.6.0 | 12.7.0 | Atualização para a versão mais recente ou mínima 12.7.0 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
8. Criptografia do lado do cliente atualizada para usar o AES-GCM devido a vulnerabilidades de segurança no modo CBC
Descrição do problema
Para atenuar uma vulnerabilidade de segurança encontrada no modo CBC, o SDK do Java v12 lançou uma nova versão da criptografia do lado do cliente chamada v2, que usa AES-GCM para criptografia do lado do cliente em vez do modo CBC. Os SDKs atualizados são compatíveis com versões anteriores e fornecem a capacidade de ler e gravar dados criptografados com a versão v1 . Para obter detalhes completos, leia Armazenamento do Azure atualizando a criptografia do lado do cliente no SDK para resolver a vulnerabilidade de segurança. A seção 2 da postagem no blog descreve as etapas a serem tomadas para ver se esse problema afeta você.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Criptografia Armazenamento de Blobs do Azure | 12.0 a 12.16.1 | 12.17.0 | Atualizar para a versão mais recente |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima. Leia Armazenamento do Azure atualizando a criptografia do lado do cliente no SDK para resolver a vulnerabilidade de segurança para a ação recomendada.
Voltar à lista de problemas conhecidos
9. Dados incorretos sendo baixados com downloadToFile() quando solicitações REST subjacentes são repetidas
Descrição do problema
A biblioteca do SDK do Azure para Armazenamento Java tinha um bug em que os dados incorretos podiam ser gravados em um arquivo com o downloadToFile() método quando algumas das solicitações REST de Armazenamento subjacentes apresentaram falha de rede no meio do caminho. Esse bug foi introduzido originalmente no verão de 2022 e foi corrigido em maio de 2023 retornando ao comportamento anterior. As versões afetadas são 12.19.0 a 12.22.0. O patch está na versão 12.22.1.
Detalhes do problema
| Biblioteca do cliente | Versões afetadas | Versão mínima segura | Ação recomendada |
|---|---|---|---|
| Blob de Armazenamento do Azure | 12.19.0 a 12.22.0 | 12.22.1 | Atualização para a versão mais recente ou mínima 12.22.1 |
Etapas recomendadas
Atualize as versões da biblioteca de clientes de acordo com a tabela acima.
Voltar à lista de problemas conhecidos
10. Mensagem de erro InvalidHeaderValue ao usar a versão beta do SDK
Em cenários raros, os aplicativos que atualizaram para a versão beta mais recente ou geralmente disponível do SDK podem receber uma InvalidHeaderValue mensagem de erro. Esse problema pode ocorrer ao usar qualquer uma das bibliotecas de Armazenamento. A mensagem de erro é semelhante ao seguinte exemplo:
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
Se você atualizou para a versão beta mais recente ou geralmente disponível do SDK e tiver esse erro, é recomendável fazer downgrade para a versão anterior geralmente disponível do SDK para ver se o problema é resolvido. Se o problema persistir ou se a recomendação não for viável, abra um tíquete de suporte para explorar outras opções.
Azure SDK for Java