您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

NSURLSession 官方編程指南整理:會話、任務與代理的完整脈絡

編輯:iOS 開發綜合

NSURLSession 及其相關類別,是 Apple 提供的 HTTP 資料下載 API。這套 API 透過豐富的代理方法來支援身分認證,並且能在 App 未處於執行狀態時(例如 iOS 上 App 被凍結)繼續完成下載。

使用 NSURLSession 時,客戶端會建立一系列「會話」(session),每個會話對應一組彼此相關的資料傳輸任務。舉例來說,若你要打造一個網頁瀏覽器,可以為每個分頁或視窗各配一個會話;接著在該會話中加入多個任務,每個任務代表一次指向特定 URL 的請求(或是 HTTP 重新導向後的最終 URL)。

和大多數網路 API 一樣,NSURLSession 是非同步的。如果你採用系統預設提供的代理,就必須提供一個區塊(block)來處理傳輸完成或發生錯誤時的結果;若你改用自訂代理物件,任務在接收到伺服器資料時(對檔案下載而言則是傳輸結束時)會回呼對應的代理方法。

注意:回呼區塊是自訂代理的主要替代方案。一旦你用回呼區塊的方式建立任務,代理方法就不會再被呼叫。

NSURLSession API 另外提供了狀態與進度屬性,讓你能取得任務的目前狀態與完成百分比,並把這些資訊回報給代理。它也支援取消、重設、暫停任務,以及從暫停、取消或失敗狀態重新開始。

理解 URL Session 的核心概念

一個會話中任務的行為,取決於三個因素:會話的類型(由建立時所用的 configuration 物件決定)、任務的類型,以及建立任務時 App 是否在前台執行。

會話的類型

NSURLSession 支援三種會話類型,分別由不同的 configuration 物件決定:

  • 預設會話(defaultSessionConfiguration):行為與其他下載 URL 的方式(如 NSURLConnection)大致相同,採用持久化的磁碟快取策略,並把認證資訊存進使用者的鑰匙串(keychain)。
  • 暫時性會話(ephemeralSessionConfiguration):不會把任何資訊持久化到磁碟(包含快取與認證),所有狀態只存在於與該會話關聯的記憶體中;一旦會話失效,這些資訊便全部清空。
  • 背景會話(backgroundSessionConfigurationWithIdentifier):與預設會話相似,差別在於由一條獨立的執行緒負責資料傳輸。背景會話另有若干額外限制,詳見下節「背景傳輸注意事項」。

任務的類型

在同一個會話中,NSURLSession 支援三種任務:

  • 資料任務(data task):以 NSData 物件收發資料,適合短小、與伺服器互動頻繁的請求。資料可以是分段回傳(每次給一部分),也可以透過完成回呼一次性交付。由於結果不落地成檔案,資料任務不支援背景執行。
  • 下載任務(download task):以檔案形式接收資料,支援 App 未執行時的背景下載。
  • 上傳任務(upload task):通常以檔案形式送出資料,同樣支援 App 未執行時的網路上傳。

背景傳輸注意事項

NSURLSession 允許 App 在凍結狀態下繼續傳輸資料,但這項能力只在使用背景會話配置所建立的會話中才可用。

由於真實的傳輸工作跑在一條獨立執行緒上,而重新啟動一條執行緒的成本不低,因此背景會話犧牲了一些彈性,換來以下限制:

  • 必須為每個委派提供代理(對上傳與下載類型的會話而言,代理方法與耗用內行程式碼的傳輸相同)。
  • 只支援 HTTP 與 HTTPS 協定,不支援自訂協定。
  • 重新導向會自動轉到導向後的 URL。
  • 只支援以檔案形式上傳。
  • 若背景傳輸是在 App 進入背景期間建立的,configuration 物件的 discretionary 屬性會被視為 true,表示由系統自行挑選最佳的網路連線方式;這個屬性有助於節省行動網路的頻寬。

注意:iOS 8 與 OS X 10.10 之前不支援背景資料載入。

App 重啟時的行為在 iOS 與 OS X 上略有差異:

在 iOS 中,當某個背景傳輸完成、或需要進行身分認證而此時 App 並未執行,系統會自動在背景啟動 App,並呼叫 UIApplicationDelegate 的 application:handleEventsForBackgroundURLSession:completionHandler: 方法。這次呼叫會帶入一個會話識別碼,App 應該保存這個完成區塊,用相同的識別碼建立背景配置物件,再據此建立會話,讓它持續在背景運行。當該會話處理完最後一個任務後,系統會向會話代理送出 URLSessionDidFinishEventsForBackgroundURLSession: 訊息,代理再負責呼叫並保存完成區塊。

在 iOS 與 OS X 中,當使用者重新開啟 App 時,App 應該立刻用上次執行時那些仍有未完成任務的會話識別碼(可能有多個)建立背景配置物件,再為它們建立會話,這些新會話同樣會在背景持續運行。

注意:必須為每個會話正確指定識別碼(於建立配置物件時指定),多個會話共用同一個識別碼會導致行為無法預期。

如果有任務在 App 凍結期間完成,代理的 URLSession:downloadTask:didFinishDownloadingToURL: 會被呼叫;同樣地,若任務需要認證,會話物件會呼叫 URLSession:task:didReceiveChallenge:completionHandler: 或 URLSession:didReceiveChallenge:completionHandler:。

背景中的上傳與下載任務會在網路恢復後自動續傳,因此你不需要額外監聽網路狀態來決定何時重試失敗的任務。想深入了解背景傳輸,可參考 Simple Background Transfer。

生命週期與代理互動

要把 NSURLSession 用好,最好先弄清楚會話的生命週期,以及它與代理物件之間的互動方式:代理何時被呼叫、伺服器回傳重新導向 URL 時如何處理、任務下載失敗時又如何收尾等等。完整的生命週期說明,請參閱 Life Cycle of a URL Session。

NSCopying 行為

會話物件與任務物件遵循 NSCopying 協議的方式是:

  • 複製會話或任務物件時,回傳的是物件本身,不會建立新物件。
  • 複製配置物件時,會回傳一個全新的、可獨立修改的配置物件。

代理類別的介面範例

Listing 1-1 Sample delegate class interface
#import <Foundation/Foundation.h>

typedef void (^CompletionHandlerType)();

@interface MySessionDelegate : NSObject <NSURLSessionDelegate, NSURLSessionTaskDelegate, NSURLSessionDataDelegate, NSURLSessionDownloadDelegate>

@property NSURLSession *backgroundSession;
@property NSURLSession *defaultSession;
@property NSURLSession *ephemeralSession;

#if TARGET_OS_IPHONE
@property NSMutableDictionary *completionHandlerDictionary;
#endif

- (void) addCompletionHandler: (CompletionHandlerType) handler forSession: (NSString *)identifier;
- (void) callCompletionHandlerForSession: (NSString *)identifier;

@end

建立並配置會話

NSURLSession 提供了大量可調選項:

  • 為快取、cookies、憑證做私有儲存,以及針對單例會話設定專屬協定。
  • 為單一請求(任務)或一組請求(會話)關聯認證資訊。
  • 透過 URL 上傳或下載檔案,並支援把中繼資料拆成隨檔案內容一起傳送的短資料。
  • 設定每個主機的最大連線數。
  • 當資源無法在指定期間內下載完成時,設定逾時時間。
  • 指定可接受的 TLS 版本區間。
  • 自訂代理。
  • 設定 cookie 的管理策略。
  • HTTP 傳輸管理。

上述設定大多集中在同一個 configuration 物件裡。初始化一個會話物件時,你需要提供:

  1. 一個用來管理會話或任務行為的 configuration 物件。
  2. 選用的代理物件,用來接收資料進度、任務進度,以及其他會話事件(例如伺服器認證、判斷某個載入請求能否轉為下載請求等)。
  3. 若未指定代理,NSURLSession 會使用系統預設的代理。這種方式很適合直接把既有的 sendAsynchronousRequest:queue:completionHandler: 換成 NSURLSession 的寫法。

注意:如果 App 需要在背景傳輸資料,就必須使用自訂代理。

會話一旦建立,除了重新建立一個新會話之外,你無法再修改它的 configuration 物件或代理。

以下範例展示了如何分別建立預設、暫時性與背景三種會話:

#if TARGET_OS_IPHONE
self.completionHandlerDictionary = [NSMutableDictionary dictionaryWithCapacity:0];
#endif

/* 建立幾個 configuration 物件 */
NSURLSessionConfiguration *backgroundConfigObject =
    [NSURLSessionConfiguration backgroundSessionConfiguration: @"myBackgroundSessionIdentifier"];
NSURLSessionConfiguration *defaultConfigObject =
    [NSURLSessionConfiguration defaultSessionConfiguration];
NSURLSessionConfiguration *ephemeralConfigObject =
    [NSURLSessionConfiguration ephemeralSessionConfiguration];

/* 為預設會話設定快取行為。
   注意:iOS 要求快取路徑必須是相對於 ~/Library/Caches 的相對路徑,
   而 OS X 則需要絕對路徑。 */
#if TARGET_OS_IPHONE
NSString *cachePath = @"/MyCacheDirectory";
NSArray *myPathList = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES);
NSString *myPath = [myPathList objectAtIndex:0];
NSString *bundleIdentifier = [[NSBundle mainBundle] bundleIdentifier];
NSString *fullCachePath = [[myPath stringByAppendingPathComponent:bundleIdentifier]
                           stringByAppendingPathComponent:cachePath];
NSLog(@"Cache path: %@\n", fullCachePath);
#else
NSString *cachePath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"/nsurlsessiondemo.cache"];
NSLog(@"Cache path: %@\n", cachePath);
#endif

NSURLCache *myCache = [[NSURLCache alloc] initWithMemoryCapacity: 16384
                                                    diskCapacity: 268435456
                                                        diskPath: cachePath];
defaultConfigObject.URLCache = myCache;
defaultConfigObject.requestCachePolicy = NSURLRequestUseProtocolCachePolicy;

/* 為每個 configuration 各建立一個會話 */
self.defaultSession = [NSURLSession sessionWithConfiguration: defaultConfigObject
                                                   delegate: self
                                              delegateQueue: [NSOperationQueue mainQueue]];
self.backgroundSession = [NSURLSession sessionWithConfiguration: backgroundConfigObject
                                                      delegate: self
                                                 delegateQueue: [NSOperationQueue mainQueue]];
self.ephemeralSession = [NSURLSession sessionWithConfiguration: ephemeralConfigObject
                                                     delegate: self
                                                delegateQueue: [NSOperationQueue mainQueue]];

除了背景配置物件之外,其餘的 configuration 物件都可以重複拿來建立多個會話。背景配置之所以不能重用,是因為兩個背景會話不能共用同一個識別碼。

你可以在任何時候安全地修改一個 configuration 物件。因為建立會話時,configuration 是以深拷貝方式傳入的,所以改動只會影響之後新建的會話,不會波及既有的會話。舉例來說,你可能想再開一個只在 Wi-Fi 環境下才允許連線的會話:

Listing 1-3 用同一個 configuration 物件建立第二個會話
ephemeralConfigObject.allowsCellularAccess = NO;

NSURLSession *ephemeralSessionWiFiOnly =
    [NSURLSession sessionWithConfiguration: ephemeralConfigObject
                                  delegate: self
                             delegateQueue: [NSOperationQueue mainQueue]];

用系統提供的代理抓取資源

最簡單的用法,就是拿 NSURLSession 取代原本的 sendAsynchronousRequest:queue:completionHandler:。這種做法只需要兩步:

  1. 建立 configuration 物件,再據此建立會話物件。
  2. 提供一個完成處理器,負責處理資料接收完之後要做的事。

有了系統代理,你甚至一行程式碼就能抓取指定 URL 的內容。以下是最精簡的實作:

注意:系統代理只提供有限的可客製化空間。若需求超出基本的 URL 載入,例如自訂認證或背景下載,就必須自行實作完整的代理,詳見 URL Session 的生命週期。

Listing 1-4 使用系統代理請求資源
NSURLSession *delegateFreeSession =
    [NSURLSession sessionWithConfiguration: defaultConfigObject
                                  delegate: nil
                             delegateQueue: [NSOperationQueue mainQueue]];

[[delegateFreeSession dataTaskWithURL: [NSURL URLWithString: @"https://www.example.com/"]
                     completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
    NSLog(@"Got response %@ with error %@.\n", response, error);
    NSLog(@"DATA:\n%@\nEND DATA\n",
          [[NSString alloc] initWithData: data encoding: NSUTF8StringEncoding]);
}] resume];

用自訂代理取得資料

若改用自訂代理,代理至少要實作以下兩個方法:

  1. URLSession:dataTask:didReceiveData::週期性地提供任務回傳的資料區塊。
  2. URLSession:task:didCompleteWithError::告知資料是否已全部接收完成。

如果 App 需要在 URLSession:dataTask:didReceiveData: 回傳之後繼續使用這些資料,就必須自行負責資料的儲存。

舉例來說,一個網頁瀏覽器可能需要拿先前收到的資料來渲染目前這批內容。做法是準備一個 NSMutableData 物件,再用 appendData: 把新收到的部分接到既有內容後面。

Listing 1-5 建立並啟動一個 data task
NSURL *url = [NSURL URLWithString: @"https://www.example.com/"];
NSURLSessionDataTask *dataTask = [self.defaultSession dataTaskWithURL: url];
[dataTask resume];

下載檔案

下載檔案和接收資料在概念上類似。App 應該實作以下代理方法:

  1. URLSession:downloadTask:didFinishDownloadingToURL::提供下載內容的暫存位置。注意:在這個方法回傳之前,你必須把檔案讀開或直接搬到家目錄,因為方法一返回,暫存檔就會被刪除。
  2. URLSession:downloadTask:didWriteData:totalBytesWritten:totalBytesExpectedToWrite::回報下載進度。
  3. URLSession:downloadTask:didResumeAtOffset:expectedTotalBytes::告知 App 正在嘗試恢復先前失敗的下載。
  4. URLSession:task:didCompleteWithError::告知 App 下載失敗。

把下載任務放進背景會話,App 不在執行時下載仍會繼續;若放在預設或暫時性會話,App 重啟後下載會從頭再來。

傳輸過程中如果使用者按下暫停,App 可以呼叫 cancelByProducingResumeData: 取消任務,接著把已傳輸的資料當成參數,傳給 downloadTaskWithResumeData: 或 downloadTaskWithResumeData:completionHandler:,建立一個新任務續傳。

Listing 1-6 下載任務範例
NSURL *url = [NSURL URLWithString: @"https://developer.apple.com/library/ios/documentation/"
              "Cocoa/Reference/Foundation/ObjC_classic/FoundationObjC.pdf"];
NSURLSessionDownloadTask *downloadTask = [self.backgroundSession downloadTaskWithURL: url];
[downloadTask resume];
Listing 1-7 下載任務的代理方法

- (void)URLSession:(NSURLSession *)session
        downloadTask:(NSURLSessionDownloadTask *)downloadTask
didFinishDownloadingToURL:(NSURL *)location {
    NSLog(@"Session %@ download task %@ finished downloading to URL %@\n",
          session, downloadTask, location);

    NSError *err = nil;
    NSFileManager *fileManager = [NSFileManager defaultManager];
    NSString *cacheDir = [[NSHomeDirectory() stringByAppendingPathComponent:@"Library"]
                          stringByAppendingPathComponent:@"Caches"];
    NSURL *cacheDirURL = [NSURL fileURLWithPath:cacheDir];
    if ([fileManager moveItemAtURL:location toURL:cacheDirURL error: &err]) {
        /* 在這裡保存新 URL 的參考 */
    } else {
        /* 處理錯誤 */
    }
}

- (void)URLSession:(NSURLSession *)session
        downloadTask:(NSURLSessionDownloadTask *)downloadTask
       didWriteData:(int64_t)bytesWritten
 totalBytesWritten:(int64_t)totalBytesWritten
totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite {
    NSLog(@"Session %@ download task %@ wrote an additional %lld bytes "
          @"(total %lld bytes) out of an expected %lld bytes.\n",
          session, downloadTask, bytesWritten, totalBytesWritten,
          totalBytesExpectedToWrite);
}

- (void)URLSession:(NSURLSession *)session
        downloadTask:(NSURLSessionDownloadTask *)downloadTask
   didResumeAtOffset:(int64_t)fileOffset
  expectedTotalBytes:(int64_t)expectedTotalBytes {
    NSLog(@"Session %@ download task %@ resumed at offset %lld bytes "
          @"out of an expected %lld bytes.\n",
          session, downloadTask, fileOffset, expectedTotalBytes);
}

上傳請求本文

App 可以用三種方式提供 HTTP POST 的請求本文:NSData 物件、檔案、以及資料流。一般建議如下:

  • 用 NSData 物件:資料已經在記憶體中,而且不會被莫名其妙地銷毀。
  • 用 檔案:要上傳的內容本來就存在磁碟上,或者屬於背景傳輸,又或者把內容寫成檔案有助於釋放記憶體。
  • 用 資料流:資料來自網路,或是要把既有的 NSURLConnection 串流程式碼遷移過來。

無論選哪種方式,只要 App 提供了自訂代理,就該實作 URLSession:task:didSendBodyData:totalBytesSent:totalBytesExpectedToSend: 來取得上傳進度。此外,若使用資料流作為請求本文,還必須實作 URLSession:task:needNewBodyStream:,詳見 Uploading Body Content Using a Stream。

用 NSData 物件上傳

呼叫 uploadTaskWithRequest:fromData: 或 uploadTaskWithRequest:fromData:completionHandler: 建立上傳任務,並把 NSData 物件傳入 fromData 參數。會話物件會依 NSData 的長度自動填入請求標頭的 Content-Length;至於伺服器可能需要的其他標頭(例如 content type),則要由 App 自己在 URL request 物件中提供。

用檔案上傳

呼叫 uploadTaskWithRequest:fromFile: 或 uploadTaskWithRequest:fromFile:completionHandler:,並提供一個檔案路徑。會話物件會自動計算 Content-Length;若 App 沒有提供 Content-Type,系統也會自動補上一個。同樣地,其他伺服器需要的標頭仍要由 App 自行設定。

用資料流上傳

呼叫 uploadTaskWithStreamedRequest: 建立上傳任務,並提供一個關聯到資料流的 request 物件。使用資料流時,App 必須自己在 request 中提供伺服器需要的標頭,例如 content-type 與 content-length。

另外,由於會話物件無法保證一定能從同一個資料流重新讀取內容,App 需要實作 URLSession:task:needNewBodyStream::當這個方法被呼叫時,App 要取得或建立一個全新的資料流,再呼叫提供的完成區塊。

注意:因為必須實作 URLSession:task:needNewBodyStream:,這種形式不支援使用系統預設代理。

用下載任務來上傳檔案

建立下載任務時,App 需要提供一個 NSData 物件或資料流作為 NSURLRequest 的參數。若採用資料流,同樣要實作 URLSession:task:needNewBodyStream: 以處理認證失敗的情況。

處理認證與自訂 TLS 鏈驗證

當遠端伺服器回傳需要認證的狀態碼,或認證需要特定環境(例如 SSL 客戶端憑證)時,NSURLSession 會呼叫對應的認證代理方法:

  • 會話層級:遇到 NSURLAuthenticationMethodNTLM、NSURLAuthenticationMethodNegotiate、NSURLAuthenticationMethodClientCertificate 或 NSURLAuthenticationMethodServerTrust 時,會話物件會呼叫 URLSession:didReceiveChallenge:completionHandler:。若 App 沒有提供會話代理,則改由任務代理的 URLSession:task:didReceiveChallenge:completionHandler: 接手。
  • 非會話層級:NSURLSession 會呼叫 URLSession:task:didReceiveChallenge:completionHandler:。如果 App 提供了會話代理且需要自行處理認證,就必須在任務層級處理,因為此時 URLSession:didReceiveChallenge:completionHandler: 不會被呼叫。

以串流形式上傳時若發生認證失敗,任務不會再重讀同一個資料流。取而代之的是,NSURLSession 會透過 URLSession:task:needNewBodyStream: 向代理索取一個新的 NSInputStream 物件,用來重新發起請求。關於 NSURLSession 授權代理方法的更多細節,可參考 Authentication Challenges and TLS Chain Validation。

處理 iOS 的背景活動

在 iOS 上使用 NSURLSession,當一個下載任務完成時,App 會被自動喚醒。App 代理方法 application:handleEventsForBackgroundURLSession:completionHandler: 負責重建合適的會話、保存完成處理區塊,並在會話物件呼叫 URLSessionDidFinishEventsForBackgroundURLSession: 時把區塊執行掉。

Listing 1-8 iOS 背景下載的會話代理方法
#if TARGET_OS_IPHONE
- (void)URLSessionDidFinishEventsForBackgroundURLSession:(NSURLSession *)session {
    NSLog(@"Background URL session %@ finished events.\n", session);
    if (session.configuration.identifier) {
        [self callCompletionHandlerForSession: session.configuration.identifier];
    }
}

- (void) addCompletionHandler: (CompletionHandlerType) handler
                   forSession: (NSString *)identifier {
    if ([self.completionHandlerDictionary objectForKey: identifier]) {
        NSLog(@"Error: Got multiple handlers for a single session identifier. "
              @"This should not happen.\n");
    }
    [self.completionHandlerDictionary setObject:handler forKey: identifier];
}

- (void) callCompletionHandlerForSession: (NSString *)identifier {
    CompletionHandlerType handler =
        [self.completionHandlerDictionary objectForKey: identifier];
    if (handler) {
        [self.completionHandlerDictionary removeObjectForKey: identifier];
        NSLog(@"Calling completion handler.\n");
        handler();
    }
}
#endif
Listing 1-9 iOS 背景下載的 App 代理方法
- (void)application:(UIApplication *)application
handleEventsForBackgroundURLSession:(NSString *)identifier
  completionHandler:(void (^)())completionHandler {
    NSURLSessionConfiguration *backgroundConfigObject =
        [NSURLSessionConfiguration backgroundSessionConfiguration: identifier];
    NSURLSession *backgroundSession =
        [NSURLSession sessionWithConfiguration: backgroundConfigObject
                                      delegate: self.mySessionDelegate
                                 delegateQueue: [NSOperationQueue mainQueue]];
    NSLog(@"Rejoining session %@\n", identifier);
    [self.mySessionDelegate addCompletionHandler: completionHandler
                                      forSession: identifier];
}
  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved