Skip to main content

使用 CORS 与 JSONP 发出跨源请求

可以使用跨源资源共享 (CORS) 与 JSONP 回拨跨域发出 API 请求。

关于跨源请求

跨源请求是向除发起请求的域以外的其他域发出的请求。 出于安全原因,多数 Web 浏览器会阻止跨源请求。 但你可以使用跨源资源共享 (CORS) 和 JSONP 回拨发出跨源请求。

跨域资源共享 (CORS)

REST API 支持来自任何源的 AJAX 请求的跨源资源共享 (CORS)。 有关详细信息,请参阅“CORS W3C 建议”和 HTML 5 安全指南

下面是从浏览器点击 http://example.com 发送的请求示例:

$ curl -I http(s)://HOSTNAME/api/v3 -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

以下是 CORS 预检请求的示例:

$ curl -I http(s)://HOSTNAME/api/v3 -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

JSON-P 回调

可以向任何 GET 调用发送 ?callback 参数,以便将结果包装在 JSON 函数中。 当浏览器希望将 GitHub Enterprise Server 内容嵌入网页并避免跨域问题时,通常使用此方法。 响应包括与常规 API 相同的数据输出,加上相关的 HTTP 标头信息。

$ curl http(s)://HOSTNAME/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["http(s)://HOSTNAME/api/v3?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

您可以编写一个 JavaScript 处理程序来处理回调。 以下是一个最小的处理程序示例,你可以尝试:

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'http(s)://HOSTNAME/api/v3?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

所有标头都具有与 HTTP 标头相同的字符串值,但 Link 除外。 Link 标头已预先解析,并以 [url, options] 元组的数组形式出现。

例如,链接如下所示:

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

在回拨输出中将如下所示:

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}