Como usar o armazenamento de Blob no iOS

Artigo
11/20/2018

Este artigo mostra como executar cenários comuns usando o Armazenamento de Blobs do Microsoft Azure. Os exemplos são escritos em Objective-C e usam a Azure Storage Client Library for iOS(Biblioteca do Cliente de Armazenamento do Azure para iOS). Os cenários abrangidos incluem carregar, listar, baixar e excluir blobs. Para obter mais informações sobre blobs, consulte a seção Próximas etapas . Você também pode baixar o aplicativo de exemplo para ver rapidamente o uso do Armazenamento do Azure em um aplicativo do iOS.

Para saber mais sobre armazenamento de Blobs, consulte Introdução ao armazenamento de Blobs do Azure.

Criar uma conta de armazenamento do Azure

A maneira mais fácil de criar sua primeira conta de armazenamento do Azure é usando o portal do Azure. Para saber mais, consulte Criar uma conta de armazenamento.

Você também pode criar uma conta de armazenamento do Azure usando o Azure PowerShell, a CLI do Azure ou o Provedor de Recursos de Armazenamento do Azure para .NET.

Se você preferir não criar uma conta de armazenamento no Azure neste momento, também pode usar o emulador de armazenamento Azurite para executar e testar seu código em um ambiente local. Para obter mais informações, consulte Usar o emulador Azurite para desenvolvimento local do armazenamento do Azure.

Importar a biblioteca do iOS de Armazenamento do Azure para seu aplicativo

Você pode importar a biblioteca do iOS de Armazenamento do Azure para seu aplicativo usando o CocoaPod para Armazenamento do Azure ou importando o arquivo Framework . O CocoaPod é a maneira recomendada, pois ele facilita a integração à biblioteca, enquanto a importação do arquivo de estrutura é menos intrusiva para seu projeto existente.

Para usar essa biblioteca, você precisará do seguinte:

iOS 8+
Xcode 7+

CocoaPod

Se você ainda não fez isso, instale os CocoaPods em seu computador abrindo uma janela de terminal e executando o seguinte comando
```
sudo gem install cocoapods
```
Em seguida, no diretório do projeto (o diretório que contém o arquivo .xcodeproj), crie um novo arquivo chamado Podfile (sem extensão de arquivo). Adicione o seguinte a Podfile e salve.
```
platform :ios, '8.0'

target 'TargetName' do
  pod 'AZSClient'
end
```
Na janela do terminal, navegue até o diretório do projeto e execute o seguinte comando
```
pod install
```
Se o seu .xcodeproj estiver aberto no Xcode, feche-o. No diretório do projeto, abra o arquivo de projeto recém-criado que terá a extensão .xcworkspace. Esse é o arquivo no qual você trabalhará a partir de agora.

Framework

A outra maneira de usar a biblioteca é criar a estrutura manualmente:

Primeiro, baixe ou clone o repositório azure-storage-ios.
Vá para azure-storage-ios ->Lib ->Biblioteca de cliente de Armazenamento do Azure e abra AZSClient.xcodeproj no Xcode.
No canto superior esquerdo do Xcode, altere o esquema ativo de "Biblioteca de Cliente de Armazenamento do Azure" para "Estrutura".
Compile o projeto (⌘+B). Isso criará um arquivo AZSClient.framework na Área de Trabalho.

Você pode importar o arquivo de estrutura em seu aplicativo fazendo o seguinte:

Crie um novo projeto ou abra um projeto existente no Xcode.
Arraste e solte o AZSClient.framework em seu navegador de projeto Xcode.
Selecione Copiar itens se necessário e clique em Concluir.
Clique no projeto no painel de navegação esquerdo e clique na guia Geral na parte superior do editor de projeto.
Na seção Estruturas e Bibliotecas Vinculadas , clique no botão Adicionar (+).
Na lista de bibliotecas já fornecida, pesquise libxml2.2.tbd e adicione-a ao projeto.

Importar a Biblioteca

// Include the following import statement to use blob APIs.
#import <AZSClient/AZSClient.h>

Se você estiver usando Swift, precisará criar um cabeçalho ponte e importar <AZSClient/AZSClient.h> para lá:

Crie um arquivo de cabeçalho Bridging-Header.h e adicione a instrução de importação acima.
Vá para a guia Configurações de Build e pesquise por Cabeçalho Ponte do Objective-C.
Clique duas vezes no campo de Cabeçalho Ponte do Objective-C e adicione o caminho para o arquivo de cabeçalho:ProjectName/Bridging-Header.h
Compile o projeto (⌘+B) para verificar se o cabeçalho ponte foi recebido pelo Xcode.
Comece a usar a biblioteca diretamente em qualquer arquivo Swift, instruções de importação não são necessárias.

Configurar seu aplicativo para acessar o Armazenamento de Blob

Há duas maneiras de autenticar o aplicativo para acessar os serviços de Armazenamento:

Chave Compartilhada: Use a Chave Compartilhada somente para fins de teste
SAS (Assinatura de Acesso Compartilhado): Use a SAS para aplicativos de produção

Chave compartilhada

A autenticação de Chave Compartilhada significa que o aplicativo usará seu nome da conta e chave de conta para acessar os serviços de Armazenamento. Para mostrar rapidamente como usar essa biblioteca, vamos usar a autenticação de Chave Compartilhada nesta introdução.

Aviso

Use autenticação de chave compartilhada somente para fins de teste! Seu nome de conta e chave de conta, que dão acesso completo de leitura/gravação à conta de Armazenamento associada, serão distribuídos a todas as pessoas que baixarem o aplicativo. Isso não é uma prática recomendada, pois você corre o risco de ter sua chave comprometida por clientes não confiáveis.

Ao usar a autenticação de Chave Compartilhada, você criará uma cadeia de conexão. A cadeia de conexão é composta dos seguintes itens:

O DefaultEndpointsProtocol -você pode escolher HTTP ou HTTPS. No entanto, é altamente recomendável usar HTTPS.
O Nome da Conta - o nome de sua conta de armazenamento
A Chave da Conta - no Portal do Azure, navegue até a conta de armazenamento e clique no ícone Chaves para encontrar essa informação.
(Opcional) EndpointSuffix - é usado para serviços de armazenamento em regiões com sufixos de ponto de extremidade diferentes, como o Azure China ou a Governança do Azure.

Veja um exemplo de cadeia de conexão usando a autenticação de Chave Compartilhada:

"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here"

SAS (Assinaturas de Acesso Compartilhado)

Para um aplicativo móvel, o método recomendado para autenticar uma solicitação por um cliente em relação ao serviço de Armazenamento do Azure é usando uma SAS (Assinatura de Acesso Compartilhado). A SAS permite conceder a um cliente acesso a um recurso por um período de tempo especificado, com um conjunto de permissões especificado. Como proprietário da conta de armazenamento, você precisará gerar uma SAS a ser consumida por seus clientes móveis. Para gerar a SAS, provavelmente você desejará escrever um serviço separado que gere a SAS a ser distribuída a seus clientes. Para fins de teste, você pode usar o Gerenciador de Armazenamento do Microsoft Azure ou o Portal do Azure para gerar um SAS. Ao criar a SAS, você pode especificar o intervalo de tempo em que a SAS é válida e as permissões que a SAS concede ao cliente.

O exemplo a seguir mostra como usar o Gerenciador de Armazenamento do Microsoft Azure para gerar uma SAS.

Se você ainda não fez isso, Instale o Gerenciador de Armazenamento do Microsoft Azure
Conecte-se à sua assinatura.
Clique em sua conta de armazenamento e clique na guia "Ações" na parte inferior esquerda. Clique em "Get Shared Access Signature" (Obter Assinatura de Acesso Compartilhado) para gerar uma "cadeia de conexão" para a SAS.
Aqui está um exemplo de uma cadeia de conexão de SAS que concede permissões leitura e gravação no serviço, contêiner e nível de objeto para o serviço Blob da conta de armazenamento.

"SharedAccessSignature=sv=2015-04-05&ss=b&srt=sco&sp=rw&se=2016-07-21T18%3A00%3A00Z&sig=3ABdLOJZosCp0o491T%2BqZGKIhafF1nlM3MzESDDD3Gg%3D;BlobEndpoint=https://youraccount.blob.core.windows.net"

Como você pode ver, ao usar um SAS, você não expõe a chave de sua conta em seu aplicativo. Saiba mais sobre a SAS e quais são as melhores práticas de uso dela consultando Assinaturas de Acesso Compartilhado: noções básicas do modelo de SAS.

Operações assíncronas

Observação

Todos os métodos que realizam uma solicitação ao serviço são operações assíncronas. Nos exemplos de código, você verá que esses métodos têm um manipulador de conclusão. O código no manipulador de conclusão será executado após a solicitação ser concluída. O código depois do manipulador de conclusão será executado enquanto a solicitação está sendo feita.

Criar um contêiner

Todos os blobs no Armazenamento do Azure devem residir em um contêiner. O exemplo a seguir mostra como criar um contêiner, chamado newcontainer, em sua Conta de armazenamento, se ele ainda não existir. Ao escolher um nome para o contêiner, leve em conta as regras de nomenclatura mencionadas acima.

-(void)createContainer{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"newcontainer"];

    // Create container in your Storage account if the container doesn't already exist
    [blobContainer createContainerIfNotExistsWithCompletionHandler:^(NSError *error, BOOL exists) {
        if (error){
            NSLog(@"Error in creating container.");
        }
    }];
}

Você pode confirmar que isso funciona observando o Gerenciador de Armazenamento do Microsoft Azure e verificando se newcontainer está na lista de contêineres para sua conta de armazenamento.

Definir permissões de contêiner

As permissões do contêiner são configuradas para acesso privado por padrão. No entanto, os contêineres fornecem algumas opções diferentes para acesso ao contêiner:

Privado: Dados de blob e contêiner podem ser lidos apenas pelo proprietário da conta.
Blob: Os dados do blob nesse contêiner podem ser lidos por meio de solicitação anônima, mas os dados do contêiner não estão disponíveis. Os clientes não podem enumerar os blobs no contêiner por meio de uma solicitação anônima.
Contêiner: Dados de blob e contêiner podem ser lidos por solicitação anônima. Os clientes podem enumerar os blobs no contêiner por meio de uma solicitação anônima, mas não podem enumerar os contêineres em uma conta de armazenamento.

O exemplo a seguir mostra como criar um contêiner com permissões de acesso de Contêiner que permitirão o acesso público e somente leitura para todos os usuários na Internet:

-(void)createContainerWithPublicAccess{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    // Create container in your Storage account if the container doesn't already exist
    [blobContainer createContainerIfNotExistsWithAccessType:AZSContainerPublicAccessTypeContainer requestOptions:nil operationContext:nil completionHandler:^(NSError *error, BOOL exists){
        if (error){
            NSLog(@"Error in creating container.");
        }
    }];
}

Carregar um blob em um contêiner

Conforme mencionado na seção Conceitos do serviço de Blob, o Armazenamento de Blob oferece três tipos diferentes de blobs: blobs de bloco, blobs de acréscimo e blobs de página. A biblioteca do iOS de armazenamento do Azure dá suporte a todos os três tipos de blobs. Na maioria dos casos, o blob de blocos é o tipo recomendado.

O exemplo a seguir mostra como carregar um blob de bloco de um NSString. Se um blob com o mesmo nome já existir no contêiner, o conteúdo desse blob será substituído.

-(void)uploadBlobToContainer{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    [blobContainer createContainerIfNotExistsWithAccessType:AZSContainerPublicAccessTypeContainer requestOptions:nil operationContext:nil completionHandler:^(NSError *error, BOOL exists)
        {
            if (error){
                NSLog(@"Error in creating container.");
            }
            else{
                // Create a local blob object
                AZSCloudBlockBlob *blockBlob = [blobContainer blockBlobReferenceFromName:@"sampleblob"];

                // Upload blob to Storage
                [blockBlob uploadFromText:@"This text will be uploaded to Blob Storage." completionHandler:^(NSError *error) {
                    if (error){
                        NSLog(@"Error in creating blob.");
                    }
                }];
            }
        }];
}

Você pode confirmar que isso funciona observando o Gerenciador de Armazenamento do Microsoft Azure e verificando se o contêiner containerpublic, contém o blob sampleblob. Neste exemplo, usamos um contêiner público, de modo que você também pode verificar se esse aplicativo funcionou indo para o URI de blobs:

https://nameofyourstorageaccount.blob.core.windows.net/containerpublic/sampleblob

Além de carregar um blob de blocos de um NSString, existem métodos semelhantes para NSData, NSInputStream ou um arquivo local.

Listar os blobs em um contêiner

O exemplo a seguir mostra como listar todos os blobs em um contêiner. Ao executar essa operação, leve em conta os seguintes parâmetros:

continuationToken - O token de continuação representa onde a operação de listagem deve começar. Se nenhum token for fornecido, ele listará os blobs desde o início. Qualquer número de blobs pode ser listado, desde zero até um máximo definido. Mesmo que esse método retorne zero resultado, se results.continuationToken não for nulo, poderá haver mais blobs no serviço que não foram listados.
prefixo -Você pode especificar o prefixo a ser usado para a listagem de blobs. Somente os blobs que começarem com esse prefixo serão listados.
useFlatBlobListing – conforme mencionado na seção Nomeando e referenciando contêineres e blobs, embora o serviço Blob seja um esquema de armazenamento simples, você pode criar uma hierarquia virtual nomeando blobs com informações de caminho. No entanto, atualmente não há suporte para listagem não plana. Este recurso estará disponível em breve. Por enquanto, esse valor deve ser YES.
blobListingDetails - Você pode especificar os itens a serem incluídos ao listar blobs
- AZSBlobListingDetailsNone: Lista somente blobs confirmados e não retornam metadados do blob.
- AZSBlobListingDetailsSnapshots: Lista de blobs confirmados e instantâneos de blob.
- AZSBlobListingDetailsMetadata: Recupera metadados de blob para cada blob retornado na listagem.
- AZSBlobListingDetailsUncommittedBlobs: Lista de blobs confirmados e não confirmados.
- AZSBlobListingDetailsCopy: Inclui propriedades de cópia na listagem.
- AZSBlobListingDetailsAll: Lista todos os blobs confirmados disponíveis, blobs não confirmados e instantâneos e retorna todos os metadados e status de cópia para esses blobs.
maxResults - O número máximo de resultados a serem retornados para a operação. Use -1 para não definir um limite.
completionHandler - O bloco de código a ser executado com os resultados da operação de listagem.

Neste exemplo, um método auxiliar é usado para chamar recursivamente o método de listagem de blobs sempre que um token de continuação é retornado.

-(void)listBlobsInContainer{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    //List all blobs in container
    [self listBlobsInContainerHelper:blobContainer continuationToken:nil prefix:nil blobListingDetails:AZSBlobListingDetailsAll maxResults:-1 completionHandler:^(NSError *error) {
        if (error != nil){
            NSLog(@"Error in creating container.");
        }
    }];
}

//List blobs helper method
-(void)listBlobsInContainerHelper:(AZSCloudBlobContainer *)container continuationToken:(AZSContinuationToken *)continuationToken prefix:(NSString *)prefix blobListingDetails:(AZSBlobListingDetails)blobListingDetails maxResults:(NSUInteger)maxResults completionHandler:(void (^)(NSError *))completionHandler
{
    [container listBlobsSegmentedWithContinuationToken:continuationToken prefix:prefix useFlatBlobListing:YES blobListingDetails:blobListingDetails maxResults:maxResults completionHandler:^(NSError *error, AZSBlobResultSegment *results) {
        if (error)
        {
            completionHandler(error);
        }
        else
        {
            for (int i = 0; i < results.blobs.count; i++) {
                NSLog(@"%@",[(AZSCloudBlockBlob *)results.blobs[i] blobName]);
            }
            if (results.continuationToken)
            {
                [self listBlobsInContainerHelper:container continuationToken:results.continuationToken prefix:prefix blobListingDetails:blobListingDetails maxResults:maxResults completionHandler:completionHandler];
            }
            else
            {
                completionHandler(nil);
            }
        }
    }];
}

Baixar um blob

O exemplo a seguir mostra como baixar um blob para um objeto NSString.

-(void)downloadBlobToString{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    // Create a local blob object
    AZSCloudBlockBlob *blockBlob = [blobContainer blockBlobReferenceFromName:@"sampleblob"];

    // Download blob
    [blockBlob downloadToTextWithCompletionHandler:^(NSError *error, NSString *text) {
        if (error) {
            NSLog(@"Error in downloading blob");
        }
        else{
            NSLog(@"%@",text);
        }
    }];
}

Excluir um blob

O exemplo a seguir mostra como excluir um blob.

-(void)deleteBlob{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    // Create a local blob object
    AZSCloudBlockBlob *blockBlob = [blobContainer blockBlobReferenceFromName:@"sampleblob1"];

    // Delete blob
    [blockBlob deleteWithCompletionHandler:^(NSError *error) {
        if (error) {
            NSLog(@"Error in deleting blob.");
        }
    }];
}

Excluir um contêiner de blob

O exemplo a seguir mostra como excluir um contêiner.

-(void)deleteContainer{
    NSError *accountCreationError;

    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"DefaultEndpointsProtocol=https;AccountName=your_account_name_here;AccountKey=your_account_key_here" error:&accountCreationError];

    if(accountCreationError){
        NSLog(@"Error in creating account.");
    }

    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];

    // Create a local container object.
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:@"containerpublic"];

    // Delete container
    [blobContainer deleteContainerIfExistsWithCompletionHandler:^(NSError *error, BOOL success) {
        if(error){
            NSLog(@"Error in deleting container");
        }
    }];
}

Próximas etapas

Agora que você aprendeu como usar o Armazenamento de Blobs do iOS, siga esses links para saber mais sobre a biblioteca do iOS e o serviço de armazenamento.

Se você tiver dúvidas sobre esta biblioteca, fique à vontade para postar em nossa página de perguntas P e R da Microsoft ou Stack Overflow. Se você tiver sugestões de recursos para o Armazenamento do Azure, poste nos Comentários do Armazenamento do Azure.