NSURLSession 是 iOS 目前官方推薦的網路請求方式。舊的 NSURLConnection 自 iOS 9 起已被標記為不建議使用,兩者的差異在於:NSURLConnection 你得自己管執行緒與事件來源,NSURLSession 則把請求抽象成「任務」,交給 session 統一調度,並原生支援背景傳輸與斷點續傳。
使用 NSURLSession 的兩個基本步驟:建立任務、執行任務。任務通常透過 NSURLSessionTask 的子類來建立。
// 方法一:全域共享的 session,無法設定 delegate
NSURLSession *session = [NSURLSession sharedSession];
// 方法二:透過 configuration 建立,可設定 delegate 與操作佇列
NSURLSession *session =
[NSURLSession sessionWithConfiguration:configuration
delegate:delegate
delegateQueue:queue];
NSURLSessionConfiguration 用來描述這組連線的行為參數,例如逾時秒數、是否允許行動網路、快取原則、額外 HTTP 標頭等。相較之下,sharedSession 雖然方便,但沒有 delegate 就無法取得串流層級的進度與認證事件,正式專案通常會自建 session。
taskIdentifier:任務識別碼,唯一標示一個任務。originalRequest / currentRequest:初始請求與目前實際送出的請求(重導向時兩者會不同)。response:伺服器回應物件。countOfBytesReceived / countOfBytesExpectedToReceive:已接收與預期接收的位元組數。countOfBytesSent / countOfBytesExpectedToSend:已送出與預期送出的位元組數。taskDescription:任務描述,可放任意字串方便除錯。state:任務狀態(Running、Suspended、Canceling、Completed)。error:錯誤資訊。priority:任務優先級,介於 0 到 1 之間。- (void)cancel; // 取消任務 - (void)suspend; // 暫停 - (void)resume; // 繼續或啟動
priority 的建議取值為 NSURLSessionTaskPriorityDefault、NSURLSessionTaskPriorityLow、NSURLSessionTaskPriorityHigh。
cancelByProducingResumeData:,取消時可取得 resume data 供日後續傳。繼承關係為:NSURLSessionDelegate ← NSURLSessionTaskDelegate ← NSURLSessionDataDelegate。
// 收到回應時必須「授權」才會繼續接收資料
- (void)URLSession:(NSURLSession *)session
dataTask:(NSURLSessionDataTask *)dataTask
didReceiveResponse:(NSURLResponse *)response
completionHandler:(void (^)(NSURLSessionResponseDisposition disposition))completionHandler {
completionHandler(NSURLSessionResponseAllow);
}
// 收到資料,通常為 JSON
- (void)URLSession:(NSURLSession *)session
dataTask:(NSURLSessionDataTask *)dataTask
didReceiveData:(NSData *)data {
}
// 請求結束(成功或失敗)
- (void)URLSession:(NSURLSession *)session
task:(NSURLSessionTask *)task
didCompleteWithError:(NSError *)error {
}
特別注意 didReceiveResponse 中的 completionHandler。忘了呼叫它,資料不會繼續下來,這是最常見的「請求卡住」原因。
// 寫入暫存檔時回呼,可計算進度
- (void)URLSession:(NSURLSession *)session
downloadTask:(NSURLSessionDownloadTask *)downloadTask
didWriteData:(int64_t)bytesWritten
totalBytesWritten:(int64_t)totalBytesWritten
totalBytesExpectedToWrite:(int64_t)totalBytesExpectedToWrite {
}
// 斷點續傳
- (void)URLSession:(NSURLSession *)session
downloadTask:(NSURLSessionDownloadTask *)downloadTask
didResumeAtOffset:(int64_t)fileOffset
expectedTotalBytes:(int64_t)expectedTotalBytes {
}
// 下載完成,location 位於 tmp,需自行搬移
- (void)URLSession:(NSURLSession *)session
downloadTask:(NSURLSessionDownloadTask *)downloadTask
didFinishDownloadingToURL:(NSURL *)location {
}
最簡潔,不需要實作 delegate,適合一次性的簡單請求。
NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionTask *task =
[session downloadTaskWithURL:(此處為請求的 URL)
completionHandler:^(NSURL *location, NSURLResponse *response, NSError *error) {
// 任務完成後在此處理結果
}];
[task resume];
能取得更細粒度的事件,適合需要追蹤進度、處理認證、或支援背景傳輸的場景。
NSURLSession *session =
[NSURLSession sessionWithConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration]
delegate:self
delegateQueue:[[NSOperationQueue alloc] init]];
NSURLSessionTask *task = [session dataTaskWithRequest:(此處為 NSURLRequest 物件)];
[task resume];
最後提醒一個關鍵細節:建立任務之後一定要呼叫 resume。NSURLSessionTask 建立時處於 Suspended 狀態,不 resume 就不會送出任何請求。這個「看起來寫對了卻沒反應」的狀況,幾乎每個新手都會遇到一次。