平台版本控制

Facebook 的平台支援版本控制功能，應用程式組建人員每隔一段時間就能發佈變更。本文件說明版本對 SDK 和 API 的影響，以及在要求中使用這些版本的方式。

版本控制

API 和 SDK 未必完全使用同一個版本控制系統。例如，圖形 API 的版本控制進度與編碼就不同於 Facebook iOS SDK。所有 Facebook SDK 都支援與不同 API 版本互動的功能。多個 API 或 SDK 版本可同時存在，且每個版本具有不同的功能。

圖形 API 的最新版本是哪一版？

圖形 API 的最新版本是 v21.0

為什麼要分版本？

版本控制的目標是要讓組建應用程式的開發人員能夠預先掌握 API 或 SDK 可能出現變化的時間點。API 有助於網站開發，但對行動裝置開發來說則更為重要，因為手機應用程式的使用者可能很久才會升級應用程式（或可能永遠不會升級）。

自發佈之日起，每個版本至少會保留 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 呼叫稱為未知版本呼叫。例如，假設目前的最新版本是 4.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 呼叫中指定舊版本。例如，如果您的應用程式是在 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}

社交外掛程式

如果您使用的是 Facebook 社交外掛程式的 HTML5 或 xfbml 版本，則您在初始化 JavaScript SDK 時指定的版本將決定轉譯的版本。

若您要插入 iframe 或純連結版的 Facebook 外掛程式，就要在外掛程式原始路徑前面加上版本號碼：

<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 發出版本控制要求

如果您使用 Facebook iOS SDK、Facebook Android SDK 或 Facebook SDK for Javascript，則大部分的版本呼叫會自動進行。請注意，這個部分因各個 SDK 所用的版本控制系統而異。

JavaScript

只有在您使用 sdk.js 路徑時，JavaScript SDK 才會使用不同的 API 版本。

如果您使用 JavaScript SDK 中的 FB.init()，您必須使用版本參數，如以下所示：

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

若您在 init 中設定版本標示，只要是對 FB.api() 發出的呼叫，一律會在所呼叫的路徑前面自動加上版本。對於正好要呼叫的任何 Facebook 登入對話方塊也是如此。您得到的會是該 API 版本的 Facebook 登入對話方塊。

若有需要，只要在 FB.api() 呼叫中將版本加在端點路徑的前面，即可覆寫版本。

iOS

只要是已經發佈的 Facebook iOS SDK 版本，每一個皆以發佈日當天適用的版本為準。這表示，如果您升級到新版 SDK，您也會升級到最新的 API 版本（但是您可以使用 [FBSDKGraphRequest initWithGraphPath] 手動指定任何舊版、可用的 API 版本）。API 版本列在每一個 Facebook iOS SDK 版本的版本資訊中。

版本會加在您使用 Facebook iOS SDK 對圖形 API 發出的任何呼叫前面，大致上與 JavaScript SDK 的情況相去不遠。例如，如果 API 的最新版本是 v2.7，則下列程式碼範例中使用的 /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

只要是已經發佈的 Facebook Android SDK 版本，每一個皆以發佈日當天適用的版本為準。這表示，如果您升級到新版 SDK，您也會升級到最新的 API 版本（但是您可以使用 GraphRequest.setVersion() 手動指定任何舊版、可用的 API 版本）。API 版本列在每一個 Facebook Android SDK 版本的版本資訊中。

版本會加在您使用 Facebook Android SDK 對圖形 API 發出的任何呼叫前面，大致上與 JavaScript SDK 的情況相去不遠。例如，如果 API 的最新版本是 v2.7，則下列程式碼範例中使用的 /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() 覆寫這個呼叫的版本。