FSharp.Data 程序集之 Http
(**
# F# Data: HTTP Utilities
.NET 库提供了强大的 API，产生和发送 HTTP WEB 请求，有两个类型，一个简单，`WebClient`(参见 [MSDN][1]) ，另一个稍微复杂，`HttpWebRequest`，(参见 [MSDN][2]) 。然而，这两个类型的使用相当困难，如果只打算运行简单的 HTTP 请求，指定参数，比如，方法、HTTP POST 数据或者额外的头。
F# Data 库提供简单的 Http 类型，有两个重载的方法：`Request` and `AsyncRequest`，用于创建同步、异步执行的请求。
[1]: http://msdn.microsoft.com/en-us/library/system.net.webclient.aspx
[2]: http://msdn.microsoft.com/en-us/library/system.net.httpwebrequest.aspx
要使用这个类，首先要引用库，F# interactive 中使用 `#r`，在项目中添加引用，然后加载 `FSharp.Net` namespace：
*)
Credentials <- NetworkCredential ("hadstj@hotmail.com","kokyWfYXaG5H63g3CvS3UW5mgnydQFvwXyc1h+p7U+I=")
#r "../../bin/FSharp.Data.dll"
open FSharp.Net
(**
## 发送简单的请求
在发送简单的 HTTP (GET) 请求，下载指定的页面，可以使用 `Http.Request` and `Http.AsyncRequest`，只需要一个参数：
*)
// 下载页面
Http.Request("http://tomasp.net")
// 异步下载页面
async { let! html = Http.AsyncRequest("http://tomasp.net")
printfn "%d" html.Length }
|> Async.Start
(**
在下面的文档中，我们只讨论 `Request` 方法，因为 `AsyncRequest` 的用法完全相同：
## 查询参数与头
指定查询参数的方法，可以是把参数包含在 URL 中 (例如 `http://...?test=foo&more=bar`)，也可以使用可靠的参数 `query` 进行传递。下面的例子，还显式指定了 GET 方法，如果不指定，会自动设置：
*)
Http.Request("http://httpbin.org/get", query=["test", "foo"], meth="GET")
(**
指定额外的头也很相似，使用可选的参数 `headers`。这个集合不仅可以包含标准的头，比如 Accept 头（当使用 `HttpWebRequest` 时，必须显式指定），还可以包含自定义的头。
下面的例子使用 [电影数据库] (http://www.themoviedb.org) API，搜索 "batman"。要运行这个例子，需要注册，并提供 API 的 key：
这里提供了一个 key，是 F# 大拿演示用的。请仅用于测试程序。
*)
// API key for http://www.themoviedb.org
let apiKey = "6ce0ef5b176501f8c07c634dfa933cff"
// HTTP 请求
Http.Request
( "http://api.themoviedb.org/3/search/movie",
query = [ "api_key", apiKey; "query", "batman" ],
headers = [ "accept", "application/json" ])
(**
## 发送请求数据
如果打算发送有 HTTP POST 数据的 POST 请求，可以使用 `body` 参数，以字符串形式指定额外的数据，也可以在 `bodyValues` 参数中以键－值对的形式指定数据。如果指定 body 数据，不需要指定 `meth` 参数，自动设置成 `GET` 方法。
下面的例子使用 [httpbin.org](http://httpbin.org) 服务，它会返回请求的详细信息：
*)
Http.Request("http://httpbin.org/post", bodyValues=["test", "foo"])
(**
通常，Content-Type 头被设置为 `application/x-www-form-urlencoded`，但是，也可以改变，只要使用可选的 `headers`参数，在头列表中添加 `content-type`：
*)
Http.Request
( "http://httpbin.org/post",
headers = ["content-type", "application/json"],
body = """ {"test": 42} """)
(**
## 在请求之间保持 cookies
如果想在请求之间保持 cookies，可以指定 `cookieContainer` 参数。
下面的例子是检索 MSDN 文档中有关 `HttpRequest` 类，只包含 C# 的代码片段，而没有 F# 的：
*)
// 为给定类的文档构建 URL
let msdnUrl className =
let root = "http://msdn.microsoft.com"
sprintf "%s/en-gb/library/%s.aspx" root className
// 得到页面，查找 F# 代码
let docInCSharp = Http.Request(msdnUrl "system.web.httprequest")
docInCSharp.Contains "<a>F#</a>"
(**
如果我们现在到另外的 MSDN 页面，在 F# 代码示例上单击，然后，返回 `HttpRequest` 类文档，它会保持相同的 `cookieContainer`，会得到 F# 的代码片段：
*)
open System.Net
let cc = CookieContainer()
// 发送请求，并切换语言
Http.Request
( msdnUrl "system.datetime",
query = ["cs-save-lang", "1"; "cs-lang","fsharp"],
cookieContainer = cc) |> ignore
// 再次请求文档，并查找 F#
let docInFSharp =
Http.Request
( msdnUrl "system.web.httprequest",
cookieContainer = cc )
docInFSharp.Contains "<a>F#</a>"
(**
如果想看到更多有关这个的信息，包括响应的头，返回的 cookie，以及响应的 URL（如果有重定向的话，它会不同于传递进去的 URL），可以使用 `RequestDetailed` 方法：
*)
let response = Http.RequestDetailed(msdnUrl "system.web.httprequest")
// 检查响应的信息
response.Cookies
response.ResponseUrl
(**
## 请求二进制数据
`Request` 方法总是把响应返回成字符串，但是，如果使用 `RequestDetailed` 方法，可以根据响应的 `content-type` 头属性，返回 `HttpResponseBody.Text` 或 `HttpResponseBody.Binary`：
*)
let logoUrl = "https://raw.github.com/fsharp/FSharp.Data/master/misc/logo.png"
match Http.RequestDetailed(logoUrl).Body with
| HttpResponseBody.Text text ->
printfn "Got text content: %s" text
| HttpResponseBody.Binary bytes ->
printfn "Got %d bytes of binary content" bytes.Length
(**
## 发送客户端证书
如果想在请求中加上客户端证书，可以使用可选的参数 `certificate`，然后传递 `X509ClientCertificate` 值。这需要引入 `System.Security.Cryptography` 中的 `X509Certificates` 命名空间。
假设证书保存在 `myCertificate.pfx`，程序可以这样写：
*)
open System.Security.Cryptography.X509Certificates
// 从文件加载证书
let clientCert =
new X509Certificate2(".myCertificate.pfx", "password")
// 发送带证书的请求
Http.Request
( "http://yourprotectedresouce.com/data",
certificate = clientCert)