AZSClient 0.2.6

AZSClient 0.2.6

测试已测试
Lang语言 Obj-CObjective C
许可 MIT
发布上次发布2018年3月

Michael CurdJosh FriedmanAdam SorrinZe Qian Zhang维护。



AZSClient 0.2.6

  • Microsoft Azure Storage

Azure Storage Client Library for iOS

概述

此库旨在帮助您构建使用Microsoft Azure Storage的iOS应用程序。
目前,该库处于预览阶段,感谢您查看!在本库稳定之前,我们将从社区获得尽可能多的反馈。如有问题,请在GitHub上提交问题。

该库目前支持几乎所有Blob操作(以下有一些例外)。其他服务(表、队列、文件)将根据需求提供。

要使用此库,您需要以下内容:

  • iOS 8+
  • Xcode 7+

如何入门

推荐使用Cocoapod方式使用该库,可在此处找到。

Podfile

platform :ios, '8.0'

target 'TargetName' do
  pod 'AZSClient'
end

框架

另一种使用库的方式是手动构建框架

  1. 首先,下载或克隆azure-storage-ios repo
  2. 进入azure-storage-ios -> Lib -> Azure Storage Client Library,并在Xcode中打开AZSClient.xcodeproj
  3. 在Xcode的左上角,将活动方案从"Azure Storage Client Library"更改为"Framework"。
  4. 构建项目(⌘+B)。这将在您的桌面上创建一个AZSClient.framework文件。

然后,您可以通过以下方式将框架文件导入到应用程序中:

  1. 创建一个新项目或在Xcode中打开现有项目。
  2. AZSClient.framework拖放到Xcode项目导航器中。
  3. 选择如有必要复制项目,然后点击完成
  4. 在左侧导航中选择您的项目,然后点击项目编辑器顶部的普通选项卡。
  5. 链接的框架和库部分下,点击添加按钮(+)。
  6. 在已提供的库列表中搜索libxml2.2.tbd并将其添加到项目中。

导入说明

#import <AZSClient/AZSClient.h>

如果您使用Swift,您需要创建一个桥接头并将其添加到

  1. 创建一个头文件Bridging-Header.h,并添加上述导入语句。
  2. 转到构建设置选项卡,并搜索Objective-C桥接头
  3. 双击Objective-C桥接头字段,并添加头文件的路径:ProjectName/Bridging-Header.h
  4. 构建项目(⌘+B)以验证桥接头已被Xcode选中。
  5. 然后可以在任何Swift文件中直接使用库,不需要导入语句。

以下是一个创建和删除blob的小型代码示例:

-(void)createAndDeleteBlob
{
    // Create a semaphore to prevent the method from exiting before all of the async operations finish.
    // In most real applications, you wouldn't do this, it makes this whole series of operations synchronous.
    dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
    
    // Create a storage account object from a connection string.
    AZSCloudStorageAccount *account = [AZSCloudStorageAccount accountFromConnectionString:@"myConnectionString"];
    
    // Create a blob service client object.
    AZSCloudBlobClient *blobClient = [account getBlobClient];
    
    // Create a local container object with a unique name.
    NSString *containerName = [[NSString stringWithFormat:@"sampleioscontainer%@",[[[NSUUID UUID] UUIDString] stringByReplacingOccurrencesOfString:@"-" withString:@""]] lowercaseString];
    AZSCloudBlobContainer *blobContainer = [blobClient containerReferenceFromName:containerName];
    
    // Create the container on the service and check to see if there was an error.
    [blobContainer createContainerWithCompletionHandler:^(NSError* error){
        if (error != nil){
            NSLog(@"Error in creating container.");
        }
        
        // Create a local blob object
        AZSCloudBlockBlob *blockBlob = [blobContainer blockBlobReferenceFromName:@"blockBlob"];
        
        // Get some sample text for the blob
        NSString *blobText = @"Sample blob text";
        
        // Upload the text to the blob.
        [blockBlob uploadFromText:blobText completionHandler:^(NSError *error) {
            if (error != nil){
                NSLog(@"Error in uploading blob.");
            }
            
            // Download the blob's contents to a new text string.
            [blockBlob downloadToTextWithCompletionHandler:^(NSError *error, NSString *resultText) {
                if (error != nil){
                    NSLog(@"Error in downloading blob.");
                }
                
                // Validate that the uploaded/downloaded string is correct.
                if (![blobText isEqualToString:resultText])
                {
                    NSLog(@"Error - the text in the blob does not match.");
                }
                
                // Delete the container from the service.
                [blobContainer deleteContainerWithCompletionHandler:^(NSError* error){
                    if (error != nil){
                        NSLog(@"Error in deleting container.");
                    }
                    
                    dispatch_semaphore_signal(semaphore);
                }];
            }];
        }];
    }];
    
    // Pause the method until the above operations complete.
    dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER);
}

通常情况下,Storage Client中的所有进行服务调用的方法都是异步的,大致遵循NSURLSession的风格。当您调用与Storage Service交互的Storage Client方法时,您需要传递一个完成处理程序块来处理操作的结果。服务调用将在操作完成之前返回。

更详细的示例可以在测试代码中找到;更好的示例即将到来。
即将推出:API文档、入门指南和可下载的框架文件。当它们可用时,此页面将更新相关链接。

功能

  • 创建/列出/删除/租赁容器。
  • 创建/列出/读取/更新/删除/租赁/异步复制Blobs。
    • 使用NSStream、NSString、NSData或本地文件从/向Blobs读写。
    • 针对特定Blob类型的操作(如块操作的块Blobs等)
  • 容器和Blobs属性和元数据。
  • 获取/设置服务属性(存储分析性和CORS规则的属性)。
  • Blob虚拟目录。
  • 使用共享密钥身份验证或SAS身份验证。
  • 访问条件、自动重试和重试策略,以及日志记录。

缺少的功能

以下功能即将推出

  • 如果您想将Blob的内容下载到流中,可以使用AZSCloudBlob上的DownloadToStream方法实现。但是,目前还不能直接从blob读取的输入流打开。
  • 即将发布的版本中将更改一些内部细节。如果您查看库的内部结构(或分叉它),请做好准备。其中大部分将与清理相关。

我们希望得到反馈的特定领域

  • NSOperation支持。我们已经收到使用NSOperation作为库主要使用方法的请求 - 例如'UploadFromText'等方法将返回一个NSOperation,该操作可以然后在操作队列中安排。但是,这种方法似乎有几个缺点,包括错误处理和数据返回。例如,想象尝试实现一个“CreateIfNotExists”方法,使用“Exists”和“Create”。如果它们都返回一个NSOperation,您可以将“Create”操作依赖于“Exists”操作,但是如果在“Exists”返回错误或资源已存在的情况下,“Create”操作需要表现不同。如果您有建议,请讨论在维基百科中,或打开一个问题。
  • Azure Storage客户端目前在后台使用NSURLSession执行HTTP请求。当前,客户端没有向用户公开委托队列或各种会话配置选项,除了将在RequestOptions对象中公开的内容之外。您想控制这个吗?

日志记录

如果您遇到库的问题,启用日志记录可能会有所帮助。以下是一些注意事项:

  • 所有日志记录都是通过AZSOperationContext完成的。您可以设置全局日志记录器(在AZSOperationContext类的静态上),以及/或针对每个AZSOperationContext设置一个日志记录器(如果可用,全局和实例日志记录器都将记录)。默认情况下,库支持ASL日志记录,只需将aslclient传递到setGlobalLogger:或setLogger:withCondition:之一。您还可以定义自己的日志记录函数,使用setLogFunction:和setGlobalLogFunction:.这将调用输入块,让您可以按自己的喜好记录。
  • 请注意,该库是线程安全的。如果你使用全局的ASL日志记录器,该库会为你妥善处理。如果你使用setLogger:withCondition:,在向指定的日志记录器记录之前,库将锁定输入条件。在设置时,将日志记录器与正确的NSCondition对象关联是很重要的,否则无法满足aslclient的单线程要求。如果你传递自己的日志函数,你应该预计它们将在一个多线程的上下文中被调用,并且你需要自己处理任何需要的锁定。
  • 你需要在全局或实例日志记录器上设置最小日志级别。AZSLogLevelInfo在大多数情况下都足够了。(它会记录库发起的所有REST调用以及签名详情。)请注意,库不会隐藏任何认证信息,所以你的日志可能包含敏感数据,这使得潜在问题的诊断变得更加容易。

内部架构

如果你想查看库的内部架构,请自便,但请注意,我们将在接下来的几个版本中做出迭代,剧变可能会发生。
如果你想运行测试,你需要在test_configurations.json文件中提供自己的凭据。你还需要更改方案以实际构建和运行测试,并且你可能需要启用代码签名。