FSharp.Data 程序集之 Http

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)