Share via

Biblioteca de clientes do Compartilhamento de Arquivos do Azure para Java – versão 12.20.1

  • Artigo

O protocolo SMB (Bloco de Mensagens do Servidor) é o protocolo de compartilhamento de arquivos preferencial usado localmente hoje. O serviço de Compartilhamento de Arquivos do Microsoft Azure permite que os clientes aproveitem a disponibilidade e a escalabilidade do SMB de IaaS (Infraestrutura de Nuvem como Serviço) do Azure sem precisar reescrever aplicativos cliente SMB.

Os arquivos armazenados nos compartilhamentos de serviço do Compartilhamento de Arquivos do Azure podem ser acessados por meio do protocolo SMB e também por meio de APIs REST. O serviço Compartilhamento de Arquivos oferece os quatro recursos a seguir: conta de armazenamento, compartilhamentos, diretórios e arquivos. Os Compartilhamentos fornecem uma maneira de organizar conjuntos de arquivos e também podem ser montados como um compartilhamento de arquivo SMB hospedado na nuvem.

Código-fonte | Documentação | de referência da APIDocumentação | da API RESTDocumentação do produto | Amostras

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

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

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-file-share</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-storage-file-share</artifactId>
  <version>12.20.1</version>
</dependency>

Criar uma conta de armazenamento

Para criar uma Conta de Armazenamento, você pode usar o Portal do Azure ou a CLI do Azure.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Autenticar o cliente

Para interagir com o serviço de Armazenamento (Serviço de Compartilhamento de Arquivos, Compartilhamento, Diretório, MessageId, Arquivo), você precisará criar uma instância da classe Cliente de Serviço. Para tornar isso possível, você precisará da cadeia de caracteres SAS da Conta SAS (assinatura de acesso compartilhado) da conta de Armazenamento. Saiba mais em Token SAS

Obter credenciais

  • SAS Token

    • Use o snippet da CLI do Azure abaixo para obter o token SAS da conta de Armazenamento.

      az storage file generate-sas
    --name {account name}
    --expiry {date/time to expire SAS token}
    --permission {permission to grant}
    --connection-string {connection string of the storage account}

      CONNECTION_STRING=<connection-string>

az storage file generate-sas
    --name javasdksas
    --expiry 2019-06-05
    --permission rpau
    --connection-string $CONNECTION_STRING

    • Como alternativa, obtenha o Token SAS da conta no Portal do Azure.

      1. Vá até sua conta de armazenamento.
      2. Clique em "Assinatura de acesso compartilhado".
      3. Clique em "Gerar SAS e cadeia de conexão".

  • Credencial de chave compartilhada

    • Há duas maneiras de criar uma credencial de chave compartilhada, a primeira é usar o nome da conta de armazenamento e a chave da conta. A segunda é usar o cadeia de conexão de armazenamento.
      1. Use o nome da conta e a chave da conta.
        1. O nome da conta é o nome da conta de armazenamento.
        2. Vá até sua conta de armazenamento.
        3. Selecione a guia "Chaves de acesso".
        4. Copie o valor "Key" para a Chave 1 ou a Chave 2.
      2. Usar o cadeia de conexão
        1. Vá até sua conta de armazenamento.
        2. Selecione a guia "Chaves de acesso".
        3. Copie o valor "Cadeia de conexão" para a Chave 1 ou a Chave 2.

Principais conceitos

Formato de URL

Os Compartilhamentos de Arquivos podem ser endereçáveis usando o seguinte formato de URL:

https://<storage account>.file.core.windows.net/<share>

A URL a seguir endereça um fila no diagrama:

https://myaccount.file.core.windows.net/images-to-download

Sintaxe do URI de recurso

Para a conta de armazenamento, o URI de base para operações de fila inclui apenas o nome da conta:

https://myaccount.file.core.windows.net

Para o arquivo, o URI base inclui o nome da conta e o nome do diretório/arquivo:

https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile

Tratando exceções

Usa a seção gerada do shareServiceClientshareServiceClient abaixo.

try {
    shareServiceClient.createShare("myShare");
} catch (ShareStorageException e) {
    logger.error("Failed to create a share with error code: " + e.getErrorCode());
}

Nomes de recurso

A URI para referenciar um compartilhamento, diretório ou arquivo deve ser exclusiva. Dentro de uma determinada conta de armazenamento, cada compartilhamento deve ter um nome exclusivo. Cada arquivo dentro de um determinado compartilhamento ou diretório deve ter um nome exclusivo dentro desse compartilhamento ou diretório.

Se você tentar criar um compartilhamento, diretório ou arquivo com um nome que viola as regras de nomenclatura, a solicitação falhará com um código de status 400 (Solicitação Incorreta).

Compartilhar Nomes

As regras para nomes de serviço de Compartilhamento de Arquivos são mais restritivas do que as prescritas pelo protocolo SMB para nomes de compartilhamento SMB, para que os serviços blob e arquivo possam compartilhar convenções de nomenclatura semelhantes para contêineres e compartilhamentos. As restrições de nomenclatura para os compartilhamentos são os seguintes:

  1. Um nome de compartilhamento deve ter um nome DNS válido.
  2. Os nomes de compartilhamentos começam com uma letra ou um número e pode conter apenas letras, números e o caractere de traço (-).
  3. Cada caractere de traço (-) deve ser precedido imediatamente e seguido por uma letra ou número; traços consecutivos não são permitidos em nomes compartilhados.
  4. Todas as letras em um nome compartilhado deve estar em letra minúscula.
  5. Os nomes compartilhados devem ter de 3 a 63 caracteres de comprimento.

Nomes de diretório e arquivo

As regras de nomenclatura do serviço de Compartilhamento de Arquivos do Azure para nomes de diretório e arquivo são as seguintes:

  1. Os nomes de arquivo e diretório de compartilhamento são que preservam maiúsculas de minúsculas e não diferenciam maiúsculas de minúsculas.
  2. Os nomes de componentes de arquivo e diretório de compartilhamento não devem ter mais de 255 caracteres.
  3. Os nomes do Diretório de Compartilhamento não podem terminar com o caractere de barra (/). Se fornecido, será removido automaticamente.
  4. Os nomes de arquivo de compartilhamento não devem terminar com o caractere de barra (/).
  5. Os caracteres reservados de URL precisam ser escapados corretamente.
  6. Os seguintes caracteres não são permitidos: " \ / : | < > * ?
  7. Caracteres de caminho de URL ilegal não são permitidos. Pontos de código como \uE000, embora válidos em nomes de arquivo NTFS, não são caracteres Unicode válidos. Além disso, não há permissão também para alguns caracteres ASCII ou Unicode, como caracteres de controle (0x00 a 0x1F, \u0081, etc.). Para regras que regem cadeias de caracteres Unicode em HTTP/1.1 , consulte RFC 2616, Seção 2.2: Regras Básicas e RFC 3987.
  8. Os seguintes nomes de arquivo não são permitidos: LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, LPT9, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, PRN, AUX, NUL, CON, CLOCK$, caractere de ponto (.) e dois caracteres de ponto (..).

Nomes de metadados

Os metadados para um recurso de arquivos ou compartilhado são armazenados como pares com valor de nome associados a um recurso. Os diretórios não têm metadados. Os nomes de metadados devem seguir as regras de nomenclatura para identificadores C#.

Observe que os nomes de metadados preservam a forma com a qual foram criados, mas não diferenciam maiúsculas de minúsculas quando definidos ou lidos. Se dois ou mais cabeçalhos de metadados com o mesmo nome forem enviados para um recurso, o serviço do Azure File retornará o código de status 400 (Solicitação Incorreta).

Compartilhar Serviços

A API REST do Serviço de Compartilhamento de Arquivos fornece operações em contas e gerencia as propriedades do serviço de arquivo. Ele permite as operações de listagem e exclusão de compartilhamentos, obtenção e definição de propriedades do serviço de arquivo. Depois de ter o SASToken, você poderá construir o shareServiceClient com ${accountName}, ${sasToken}

String shareServiceURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareServiceClient shareServiceClient = new ShareServiceClientBuilder().endpoint(shareServiceURL)
    .sasToken(SAS_TOKEN).buildClient();

Compartilhar

O recurso do compartilhamento inclui os metadados e as propriedades desse compartilhamento. Ele permite as operações de criação, criação de instantâneo, exclusão de compartilhamentos, obtenção de propriedades de compartilhamento, definição de metadados, obtenção e definição de ACL (política de acesso). Obter e definir ACL (política de acesso) só pode ser usado pelo ShareClient com ConnectionString.

Compartilhar com SASToken

Depois de ter o SASToken, você poderá construir o cliente de compartilhamento com ${accountName}, ${shareName}, ${sasToken}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .sasToken(SAS_TOKEN).shareName(shareName).buildClient();

Compartilhar com ConnectionString

Depois de ter o ConnectionString, você poderá construir o cliente de compartilhamento com ${accountName}, ${shareName}, ${connectionString}

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareClient shareClient = new ShareClientBuilder().endpoint(shareURL)
    .connectionString(CONNECTION_STRING).shareName(shareName).buildClient();

Compartilhar com TokenCredential

Depois de ter o TokenCredential, você poderá construir o cliente de compartilhamento com ${accountName}e ShareTokenIntent${shareName} . ShareTokenIntent.BACKUP especifica solicitações destinadas a operações de tipo de backup/administrador, o que significa que todas as ACLs de arquivo/diretório são ignoradas e permissões completas são concedidas. O usuário deve ter a permissão RBAC necessária para usar ShareTokenIntent.BACKUP.

String shareURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);

ShareClient serviceClient = new ShareClientBuilder()
    .endpoint(shareURL)
    .credential(tokenCredential)
    .shareTokenIntent(ShareTokenIntent.BACKUP)
    .shareName(shareName)
    .buildClient();

Diretório

O recurso de diretório inclui as propriedades para esse diretório. Ele permite as operações de criação, listagem, exclusão de diretórios ou subdiretórios ou arquivos, obtenção de propriedades, definição de metadados, listagem e força o fechamento dos identificadores. Depois de ter o SASToken, você poderá construir o cliente de serviço de arquivo com ${accountName}, ${shareName}, ${directoryPath}, ${sasToken}

String directoryURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareDirectoryClient directoryClient = new ShareFileClientBuilder().endpoint(directoryURL)
    .sasToken(SAS_TOKEN).shareName(shareName).resourcePath(directoryPath).buildDirectoryClient();

Arquivo

O recurso de arquivo inclui as propriedades desse arquivo. Ele permite as operações de criação, upload, cópia, download, exclusão de arquivos ou intervalo dos arquivos, obtenção de propriedades, configuração de metadados, listagem e forçar o fechamento dos identificadores. Depois de ter o SASToken, você poderá construir o cliente de serviço de arquivo com ${accountName}, ${shareName}, ${directoryPath}, , ${fileName}, ${sasToken}

String fileURL = String.format("https://%s.file.core.windows.net", ACCOUNT_NAME);
ShareFileClient fileClient = new ShareFileClientBuilder().connectionString(CONNECTION_STRING)
    .endpoint(fileURL).shareName(shareName).resourcePath(directoryPath + "/" + fileName).buildFileClient();

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço de Configuração, incluindo:

Criar um compartilhamento

Crie um compartilhamento na Conta de Armazenamento. Gera StorageException se o compartilhamento não for criado. Tomando um ShareServiceClient em KeyConcept, ${shareServiceClient}.

String shareName = "testshare";
shareServiceClient.createShare(shareName);

Criar um instantâneo no Share

Tomando um ShareServiceClient em KeyConcept, ${shareServiceClient}.

String shareName = "testshare";
ShareClient shareClient = shareServiceClient.getShareClient(shareName);
shareClient.createSnapshot();

Criar um diretório

Tomando o shareClient inicializado acima, ${shareClient}.

String dirName = "testdir";
shareClient.createDirectory(dirName);

Criar um subdiretório

Tomando o diretórioClient em KeyConcept, ${directoryClient}.

String subDirName = "testsubdir";
directoryClient.createSubdirectory(subDirName);

criar um arquivo

Tomando o diretórioClient em KeyConcept, ${directoryClient} .

String fileName = "testfile";
long maxSize = 1024;
directoryClient.createFile(fileName, maxSize);

Listar todos os compartilhamentos

Tomando o shareServiceClient em KeyConcept, ${shareServiceClient}

shareServiceClient.listShares();

Listar todos os subdiretórios e arquivos

Tomando o diretórioClient em KeyConcept, ${directoryClient}

directoryClient.listFilesAndDirectories();

Listar todos os intervalos no arquivo

Tomando o fileClient em KeyConcept, ${fileClient}

fileClient.listRanges();

Excluir um compartilhamento

Tomando o shareClient em KeyConcept, ${shareClient}

shareClient.delete();

Excluir um diretório

Tomando o shareClient em KeyConcept, ${shareClient} .

String dirName = "testdir";
shareClient.deleteDirectory(dirName);

Excluir um subdiretório

Tomando o diretórioClient em KeyConcept, ${directoryClient} .

String subDirName = "testsubdir";
directoryClient.deleteSubdirectory(subDirName);

Excluir um arquivo

Tomando o diretórioClient em KeyConcept, ${directoryClient} .

String fileName = "testfile";
directoryClient.deleteFile(fileName);

Copiar um arquivo

Tomando o fileClient em KeyConcept, ${fileClient} com cadeia de caracteres de URL de origem.

String sourceURL = "https://myaccount.file.core.windows.net/myshare/myfile";
Duration pollInterval = Duration.ofSeconds(2);
SyncPoller<ShareFileCopyInfo, Void> poller = fileClient.beginCopy(sourceURL, (Map<String, String>) null, pollInterval);

Anular cópia de um arquivo

Tomando o fileClient em KeyConcept, ${fileClient} com a resposta de informações de cópia retornada acima ${copyId}=[copyInfoResponse](#copy-a-file)de .

fileClient.abortCopy("copyId");

Carregar dados no armazenamento

Tomando o fileClient em KeyConcept, ${fileClient} com dados de "padrão" .

String uploadText = "default";
InputStream data = new ByteArrayInputStream(uploadText.getBytes(StandardCharsets.UTF_8));
fileClient.upload(data, uploadText.length());

Carregar dados maiores que 4 MB no armazenamento

Tomando o fileClient em KeyConcept, ${fileClient} com dados de "padrão" .

byte[] data = "Hello, data sample!".getBytes(StandardCharsets.UTF_8);

long chunkSize = 4 * 1024 * 1024L;
if (data.length > chunkSize) {
    for (int offset = 0; offset < data.length; offset += chunkSize) {
        try {
            // the last chunk size is smaller than the others
            chunkSize = Math.min(data.length - offset, chunkSize);

            // select the chunk in the byte array
            byte[] subArray = Arrays.copyOfRange(data, offset, (int) (offset + chunkSize));

            // upload the chunk
            fileClient.uploadWithResponse(new ByteArrayInputStream(subArray), chunkSize, (long) offset, null, Context.NONE);
        } catch (RuntimeException e) {
            logger.error("Failed to upload the file", e);
            if (Boolean.TRUE.equals(fileClient.exists())) {
                fileClient.delete();
            }
            throw e;
        }
    }
} else {
    fileClient.upload(new ByteArrayInputStream(data), data.length);
}

Carregar arquivo no armazenamento

Tomando o fileClient em KeyConcept, ${fileClient} .

String filePath = "${myLocalFilePath}";
fileClient.uploadFromFile(filePath);

Baixar dados do intervalo de arquivos

Tomando o fileClient em KeyConcept, ${fileClient} com o intervalo de 1024 a 2048.

ShareFileRange fileRange = new ShareFileRange(0L, 2048L);
OutputStream stream = new ByteArrayOutputStream();
fileClient.downloadWithResponse(stream, fileRange, false, null, Context.NONE);

Baixar arquivo do armazenamento

Tomando o fileClient em KeyConcept ${fileClient} e baixe para o arquivo de filePath.

String filePath = "${myLocalFilePath}";
fileClient.downloadToFile(filePath);

Obter propriedades de serviço de compartilhamento

Tomando um ShareServiceClient em KeyConcept, ${shareServiceClient} .

shareServiceClient.getProperties();

Definir propriedades de um serviço de compartilhamento

Tomando um ShareServiceClient em KeyConcept, ${shareServiceClient} .

ShareServiceProperties properties = shareServiceClient.getProperties();

properties.getMinuteMetrics().setEnabled(true).setIncludeApis(true);
properties.getHourMetrics().setEnabled(true).setIncludeApis(true);

shareServiceClient.setProperties(properties);

Definir metadados de compartilhamento

Tomando o shareClient em KeyConcept, ${shareClient} .

Map<String, String> metadata = Collections.singletonMap("directory", "metadata");
shareClient.setMetadata(metadata);

Obter uma política de acesso de compartilhamento

Tomando o shareClient em KeyConcept, ${shareClient} .

shareClient.getAccessPolicy();

Definir uma política de acesso de compartilhamento

Tomando o shareClient em KeyConcept, ${shareClient} .

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
    .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
    .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));
ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);
shareClient.setAccessPolicy(Collections.singletonList(permission));

Obter identificadores no arquivo de diretório

Tomando o diretórioClient em KeyConcept, ${directoryClient}

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);

Forçar alças de fechamento na ID do identificador

Tomando o diretórioClient em KeyConcept e ${directoryClient} a ID do identificador retornado acima ${handleId}=[handleItems](#get-handles-on-directory-file)

PagedIterable<HandleItem> handleItems = directoryClient.listHandles(null, true, Duration.ofSeconds(30), Context.NONE);
String handleId = handleItems.iterator().next().getHandleId();
directoryClient.forceCloseHandleWithResponse(handleId, Duration.ofSeconds(30), Context.NONE);

Definir cota no compartilhamento

Tomando o shareClient em KeyConcept, ${shareClient} .

int quotaOnGB = 1;
shareClient.setPropertiesWithResponse(new ShareSetPropertiesOptions().setQuotaInGb(quotaOnGB), null, Context.NONE);

Definir httpheaders de arquivo

Tomando o fileClient em KeyConcept, ${fileClient} .

ShareFileHttpHeaders httpHeaders = new ShareFileHttpHeaders().setContentType("text/plain");
fileClient.setProperties(1024, httpHeaders, null, null);

Solução de problemas

Geral

Quando você interage com o arquivo usando essa biblioteca de clientes Java, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST. Por exemplo, se você tentar recuperar um compartilhamento que não existe em sua Conta de Armazenamento, um 404 erro será retornado, indicando Not Found.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

  1. Bifurcar
  2. Criar seu branch de recurso (git checkout -b my-new-feature)
  3. Confirmar suas alterações (git commit -am 'Add some feature')
  4. Enviar por push para o branch (git push origin my-new-feature)
  5. Criar nova solicitação de pull

Impressões