协调一组相关的网络传输数据任务的对象
Declaration
class URLSession : NSObject
Overview
URLSession和相关的类提供了一个API，用来从RUL指示的端点下载数据和将数据上传至端点。当您的应用未运行时，或者在iOS中，当您的应用被暂停时，您的应用还可以使用此API进行后台下载。您可以使用相关的URLSessionDelegate和URLSessionTaskDelegate支持身份验证并接收重定向和任务完成之类的事件。
Note
URLSession API涉及许多不同的类，它们以相当复杂的方式协同工作，如果您自己阅读参考文档，这可能并不明显。在使用API之前，请阅读“ URL加载系统”主题中的概述。基本，上载和下载部分中的文章提供了使用URLSession执行常见任务的示例。
你的应用常见了一个或多个URLSession实例，每一个实例协调一组相关的数据传输任务。例如，如果您正在创建网络浏览器，则您的应用可能会为每个标签或窗口创建一个会话，或者一个会话用于交互使用，另一个会话用于后台下载。在每个会话中，您的应用程序都会添加一系列任务，每个任务代表对特定URL的请求（必要时遵循HTTP重定向）。
Types of URL Sessions
给定URL会话中的任务共享一个公共会话配置对象，该对象定义了连接行为，例如与单个主机建立的最大同时连接数，连接是否可以使用蜂窝网络等等
URLSession具有用于基本请求的单例共享会话（没有配置对象）。它不像您创建的会话那样可自定义，但是如果您的要求非常有限，它可以作为一个很好的起点。您可以通过调用共享类方法来访问此会话。对于其他类型的会话，您可以使用以下三种配置之一创建URLSession：
- 默认会话的行为与共享会话非常相似，但是您可以对其进行配置。您还可以将委托分配给默认会话以增量获取数据。
- 临时会话与共享会话类似，但是不要将缓存，Cookie或凭据写入磁盘。
- 后台会话使您可以在应用未运行时在后台执行内容的上传和下载。
有关创建每种配置类型的详细信息，请参见URLSessionConfiguration类中的“创建会话配置对象”。
Types of URL Session Tasks
在会话中，您可以创建任务，这些任务可以有选择地将数据上传到服务器，然后以磁盘上的文件或内存中的一个或多个NSData对象的形式从服务器检索数据。URLSession API提供了四种类型的任务：
- Data task使用NSData对象发送和接收数据。Data task旨在用于对服务器的简短的，经常是交互式的请求。
- Upload tasks 和 data tasks类似，但它们还会发送数据（通常以文件的形式），在应用未运行时支持后台上传。
- Download tasks以文件的形式检索数据，支持应用未运行时在后台上传和下载。
- WebSocket tasks 使用RFC 6455中定义的WebSocket协议通过TCP和TLS交换消息。
Using a Session Delegate
会话中的任务会分享一个通用的委托对象。您实现此委托以在各种事件发生时提供和获取信息，包括以下情况：
如果您不需要委托提供的功能，则可以在创建会话时使用此API，而无需通过传递nil来提供该API。
Important
在您的应用退出或显式使会话无效之前，会话对象始终对委托保持强引用。如果您不使会话无效，则您的应用会泄漏内存，直到应用终止。
Asynchronicity and URL Sessions
与大多数网络API一样，URLSession API是高度异步的。根据调用的方法，它以两种方式之一将数据返回到您的应用程序：
- 通过在传输成功完成或出现错误时调用完成处理程序块
- 在数据到达和传输完成时，通过在会话的委托人上调用方法
除了将这些信息传递给委托人之外，URLSession还提供状态和进度属性，您可以查询它们是否需要根据任务的当前状态做出编程决策（需要注意的是，其状态可以随时更改）。
Protocal Support
URLSession本身支持data ,file, ftp, http, 和httpsURL方案。并根据用户的系统偏好设置透明地支持代理服务器和SOCKS网关。
URLSession支持http1.1/ 和 http1.2 协议。如RFC 7540所述，HTTP / 2支持需要一台支持应用程序层协议协商（ALPN）的服务器。
您还可以通过将URLProtocol子类化，添加对自己的自定义网络协议和URL方案的支持（供您的应用专用）。
App Transport Security (ATS)
iOS 9.0和macOS 10.11及更高版本将App Transport Security（ATS）用于通过URLSession建立的所有HTTP连接。ATS要求HTTP连接使用HTTPS（RFC 2818）。
Foundation Copying Behavior
会话和任务对象符合NSCopying协议，如下所示：
- 当您的应用复制会话或任务对象时，您将获得相同的对象
- 当您的应用复制配置对象时，会获得一个新副本，您可以独立修改
Thread Safety
URL Session API是线程安全的。您可以在任何线程上下文中自由创建会话和任务。当您的委托方法调用提供的完成处理程序时，工作将自动安排在正确的委托队列上
Topics
Using the Shared Session
class var shared: URLSession
共享的单例会话对象
Creating a Session
init(configuration: URLSessionConfiguration)
使用指定的会话配置创建会话
init(configuration: URLSessionConfiguration, delegate: URLSessionDelegate?, delegateQueue: OperationQueue?)
使用指定的会话配置、委托和操作队列创建会话
class URLSessionConfiguration
一个配置对象，用于定义URL会话行为和政策
var configuration: URLSessionConfiguration
此会话的配置对象的副本。
Working with a Delegate
var delegate: URLSessionDelegate?
创建此对象时分配的委托。
protocal URLSessionDelegate
一种协议，用于定义URL会话实例调用其委托以处理会话级事件（例如会话生命周期更改）的方法。
protocol URLSessionTaskDelegate
一种协议，用来定义URL会话实例调用其委托来处理任务级事件的方法。
var delegateQueeu: OperationQueue
创建此对象是提供的操作队列
Adding Data Tasks to a Session
func dataTask(with: URL) -> URLSessionDataTask
创建一个任务，该任务检索指定URL的内容。
func dataTask(with: URL, completionHandler:(Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask
创建一个任务，该任务检索指定URL的内容，然后在完成时调用处理程序。
func dataTask(with: URLRequest) -> URLSessionDataTask
创建一个任务，该任务根据指定的URL请求对象检索URL的内容。
func dataTask(with: URLRequest, completionHandler: (Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask
创建一个任务，该任务根据指定的URL请求对象检索URL内容，然后再完成时调用处理程序。
class URLSessionDataTask
URL会话任务，可将下载的数据直接返回到内存中的应用程序
protocol URLSessionDataDelegate
一种协议，用于定义URL会话实例调用其委托以处理特定于数据和上传任务的任务级事件的方法
Adding Download Tasks to a Session
func downloadTask(with: URL) -> URLSessionDownload
创建一个下载任务，该任务检索指定URL的内容并将结果保存到文件中
func downloadTask(with: URL, completionHandler: (URL? URLResponse ?, Error?) -> Void) -> URLSessionDownloadTask
创建一个下载任务，该任务检索指定URL的内容，并将结果保存到文件中，然后在完成时调用处理程序
func downloadTask(with: URLRequest) -> URLSessinDownloadTask
创建一个下载任务，该任务根据指定的URL请求对象检索URL的内容并将结果保存到文件中。
func downloadTask(with: URLRequest, completionHandler:(URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask
创建一个下载任务，该任务检索基于指定URL请求对象的URL内容，将结果保存到文件中，然后在完成后调用处理程序
func downloadTask(with: URLRequest, completionHandler: (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask
创建一个下载任务，该任务检索基于指定URL请求对象的URL内容，将结果保存在文件中，然后在完成后调用处理程序
func downloadTask(withResumeData: Data) -> URLSessionDownloadTask
创建下载任务以恢复先前取消或失败的下载
func downloadTask(withResumeData: Data, completionHandler : (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask
创建下载任务以恢复先前取消或失败的下载，然后在完成后调用处理程序。
class URLSessionDownLoadTask
URL会话任务，用于将下载的数据存储到文件中
protocol URLSessionDownloadDelegate
一种协议，定义URL会话实例调用其委托以处理特定于下载任务的任务级事件的方法。
Adding Upload Tasks to Session
func uploadTask(with: URLRequest, from: Data) -> URLSessionUploadTask
创建一个任务，该任务对指定的URL请求对象执行HTTP请求并上传提供的数据
func uploadTask(with: URLRequest, form: Data?, completionHandler: (Data?, URLResponse?, Error?) -> Void) -> URLSessionUploadTask
创建一个任务，该任务对指定的URL请求对象执行HTTP请求，上载提供的数据，并在完成时调用处理程序
func uploadTask(with: URLRequest, formFile: URL) -> URLSessionUploadTask
创建一个任务，该任务执行HTTP请求以上传指定文件
func uploadTask(with: URLResponse, formFile: URL, completionHandler : (Data?, URLResponse?, Error?) -> Void) -> URLSessionUploadTask
创建一个任务，该任务执行HTTP请求以上传指定文件，然后在完成时调用处理程序
func uploadTask(withStreamedRequest: URLRequest) -> URLSessionUploadTask
创建一个任务，该任务基于指定的URL请求执行HTTP请求以上传数据。
class URLSessionUploadTask
URL会话任务，该任务将数据上传到请求正文中的网络中。
protocol URLSessionDataDelegate
一种协议，用于定义URL会话实例调用其委托以处理特定于数据和上传任务的任务级事件的方法
Adding Stream Tasks to a Session
func streamTask(withHostName: String, port: Int) -> URLSessionStreamTask
创建一个任务，该任务建立到指定主机名和端口的双向TCP / IP连接。
func streamTask(with: NetService) -> URLSessionStreamTask
创建一个任务，该任务使用指定的网络服务建立双向的tcp/ip连接
class URLSessionStreamTask
基于流的URL会话任务
protocol URLSessionStreamDelegate
一种协议，定义URL会话实例在其委托上调用的方法以处理特定于流任务的任务级事件
Adding WebSocket Tasks to a Session
func webSocketTask(with: URL) -> URLSessionWebSocketTask
为提供的URL创建WebSocket任务
func webSocketTask(with: URLRequest) -> URLSessionWebSokcettask
为提供的URL请求创建WebSocket任务
func webSocketTask(with: URL, protocols: [String]) -> URLSessionWebSocketTask
在给定URL和协议数组的情况下创建WebSocket任务
class URLSessionWebSocketTask
通过WebSockets协议标准进行通信的URL会话任务
protocol URLSessionWebSocketDelegate
一种协议，定义URL会话实例在其委托上调用的方法以处理特定于WebSocket任务的任务级事件。
Managing the Session
func finishTasksAndInvalidate()
使会话无效，从而允许任何未完成的任务完成。
func flush(completionHandler: () -> Void)
将cookie和凭据刷新到磁盘，清除临时缓存，并确保将来的请求在新的TCP连接上发生
func getTaskWithCompletionHandler(([URLSessionDataTask], [URLSessionUploadTask], [URLSessionDownLoadTask]) -> Void)
异步调用会话中的所有数据，上载和下载任务的完成回调。
func getAllTasks(completionHandler: ([URLSessionTask]) -> Void)
异步调用会话中所有任务的完成回调
func invalidateAndCancel()
取消所有未完成的任务，然后使会话无效
func reset(completionHandler:() -> Void)
清空所有cookie，缓存和凭据存储，删除磁盘文件，将正在进行的下载刷新到磁盘，并确保将来的请求在新的套接字上发生。
var sessionDescription: String?
会话的应用程序定义的描述性标签
Handling Errors
URL Session Error Dictionary Keys
与URL会话和任务返回的错误对象结合使用的键。
Background Task Cancellation
指示为什么取消后台任务的常量。
Performing Tasks as a Combine Publisher
Processing URL Session Data Task Results with Combine
使用一系列异步运算符来接收和处理从URL提取的数据
func dataTaskPublisher(for: URLRequest) -> URLSession.DataTaskPublisher
返回发布者，该发布者包装给定URL请求的URL会话数据任务。
func dataTaskPublisher(for: URL) -> URLSession.DataTaskPublisher
返回发布者，该发布者包装给定URL的URL会话数据任务。
struct URLSession.DataTaskPublisher
提供执行URL会话数据任务结果的发布者
Initializers
Deprecated
init()
Type Methods
Deprecated
class func new() -> Self
Relationships
Inherits Form
NSObject
Conforms To
CVarArg, Equatable, Hashable
网友评论