开放平台版本管理

Facebook 开放平台支持版本管理，因此应用创建工具会定期推出更新。本文档对 SDK 和 API 如何受版本影响以及如何使用您请求的版本作出说明。

版本管理

并非所有 API 和 SDK 的版本管理系统都相同。例如，与 iOS 版 Facebook SDK 相比，图谱 API 版本管理的步调和编号方式都不一样。所有 Facebook SDK 都支持与我们的各版 API 互动的功能。多个版本的 API 或 SDK 可以共存，每个版本具有不同的功能。

最新图谱 API 版本是哪个？

最新图谱 API 版本为 v21.0

为什么我们需要采用不同版本？

使用版本管理模式的目的在于，让构建应用的开发者能够提前了解 API 和 SDK 的更改。多个版本有助于网页开发，但对移动开发至关重要，因为在手机中使用您的应用的人可能需要很长时间才会升级（也可能永远不会升级）。

每个版本自发布之日起至少会 2 年不变，对于您的应用将能够使用多长时间，以及过多长时间才必须将其更新为新版本，从而使您可以有连续不断的一段时间。

版本计划

每个版本至少将运行两年。一个版本在后续版本发布之日起两年后将不再可用。例如，如果 API 版本 v2.3 于 2015 年 3 月 25 日发布，API 版本 v2.4 于 2015 年 8 月 7 日发布，则 v2.3 将在 v2.4 发布两年后的 2017 年 8 月 7 日到期。

一旦 API 版本不再可用，对其执行的任何调用将默认指向下一个最早的可用版本。以下是时间线示例：

对 SDK 而言，由于它是可供下载的软件包，因此各个版本始终可用。然而，SDK 所依赖的 API 或方法可能不再运行，所以您应将生命周期结束后的 SDK 视为不再有效。

您可以前往我们的更新日志页面，查找有关版本时间线、更改和发布日期的具体信息。

版本中的所有内容是否完全保持不变？

Facebook 保留就相关安全或隐私问题，在短期内对任何 API 作出更改的权利。这些更改不常发生，但确实会发生。

如果我不对 API 指定版本会发生什么情况？

我们将未指定版本的 API 调用称作无版本号调用。例如，假设当前的版本为 v4.0。调用方式如下：

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

同样的无版本号调用方式如下：

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

无版本号调用会使用设置 > 高级下的升级 API 版本图卡应用面板中设置的版本。在以下示例中，应用仪表板中设置的版本为 v2.10，其无版本号调用等效于：

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

我们建议您尽可能始终指定版本号。

限制条件

您无法对 Facebook JavaScript SDK 进行无版本号 API 调用。

我的应用能否调用当前版本之前的 API？

您可以在 API 调用中指定旧版本，只要旧版本可用并且您的应用已调用相应版本。例如，如果您的应用在 v2.0 发布后创建并使用 v2.0 进行调用，则即使在发布新版本之后，您的应用仍可以调用 v2.0，直到该版本过期。如果您在 v2.0 发布之后创建应用，但未在 v2.2 发布之前进行任何调用，您的应用将无法用 v2.0 或 v2.1 进行调用。您的应用将只能用 v2.2 和更新的版本进行调用。

市场营销 API 版本管理

市场营销 API 具有专属的版本管理模式。其版本号和计划与图谱 API 有所不同。

详细了解市场营销 API 版本管理

发出指定版本的请求

图谱 API

您可以通过指定版本路径使用几乎所有图谱 API，无论其属于核心抑或扩展分组。请参阅我们的图谱 API 快速入门指南，查看有关使用图谱 API 版本的完整指南。

对话框

指定版本号的路径不仅适用于 API 端点，还适用于对话框和社交插件。例如，如果您要为网页应用生成 Facebook 登录对话框，则可为生成对话框的端点预置版本号：

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

社交插件

如果您使用的是我们社交插件的 HTML5 或 xfbml 版本，则呈现的版本将取决于您初始化 JavaScript SDK 时指定的版本。

如果您要插入我们其中一个插件的 iframe 或者纯链接版本，您应该在插件的源路径前添加版本号：

<iframe
  src="//www.facebook.com/v21.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

从 SDK 发出指定版本号的请求

如果您使用的是适用于 iOS、Android 或 JavaScript 的 Facebook SDK，则会在很大程度上自动进行版本调用。请注意，这有别于每个 SDK 的专属版本管理系统。

JavaScript

如果您使用 sdk.js 路径，则 JavaScript SDK 只能使用不同的 API 版本。

如果您使用 JavaScript SDK 中的 FB.init()，则需要按如下方式使用 version 参数：

FB.init({
  appId      : '{app-id}',
  version    : 'v21.0'
});

如果在 init 中设定版本标记，则任何对 FB.api() 的调用都会自动将版本号添加到调用的路径前。对于碰巧调用的 Facebook 登录的对话框，情况也是如此。您将获得该版 API 的 Facebook 登录对话框。

如有需要，您只需为 FB.api() 调用中的端点路径预置版本，即可覆盖版本。

iOS

每个已发布的 iOS Facebook SDK 版本都已与发布当日推出的版本关联起来。这意味着，如果您要升级，使用新 SDK，您也将升级从而使用最新 API 版本（尽管您可以通过 [FBSDKGraphRequest initWithGraphPath] 手动指定较早的可用 API 版本）。发布每个 iOS Facebook SDK 版本时，我们均会列出相应的 API 版本。

对于通过 iOS Facebook SDK 对图谱 API 进行的调用，系统都会预先考虑 API 版本，这与 JavaScript SDK 非常相似。例如，如果 v2.7 是 API 的最新版本，则在以下代码示例中使用的 /me/friends 调用实际上会调用 /v2.7/me/friends：

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

您可以使用 [FBSDKGraphRequestConnection overrideVersionPartWith] 覆盖调用的版本。

Android

每个已发布的 Android Facebook SDK 版本都已与发布当日推出的版关联起来。这意味着，如果您要升级，使用新 SDK，您也将升级从而使用最新 API 版本（尽管您可以通过 GraphRequest.setVersion() 手动指定较早的可用 API 版本）。发布每个 Android Facebook SDK 版本时，我们均会列出相应的 API 版本。

对于通过 Android Facebook SDK 对图谱 API 进行的调用，系统都会预先考虑 API 版本，这与 JavaScript SDK 非常相似。例如，如果 v2.7 是 API 的最新版本，则在以下代码示例中使用的 /me 调用实际上会调用 /v2.7/me：

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

您可以使用 GraphRequest.setVersion() 覆盖调用的版本。