API Đồ thị

Lập phiên bản nền tảng

Nền tảng của Facebook hỗ trợ lập phiên bản để những người xây dựng ứng dụng có thể triển khai các thay đổi theo thời gian. Tài liệu này giải thích về mức độ ảnh hưởng của các phiên bản đến SDK và API, cũng như cách sử dụng các phiên bản đó trong yêu cầu của bạn.

Lập phiên bản

Không phải API và SDK nào cũng dùng chung một hệ thống lập phiên bản. Ví dụ: API Đồ thị được lập phiên bản với tốc độ và cách đánh số khác so với Facebook SDK dành cho iOS. Mọi Facebook SDK đều hỗ trợ khả năng tương tác với các phiên bản API khác của chúng tôi. Nhiều phiên bản API hoặc SDK có thể tồn tại trong cùng một thời điểm, nhưng mỗi phiên bản lại có chức năng khác nhau.

Phiên bản API Đồ thị mới nhất là gì?

Phiên bản API Đồ thị mới nhất là v21.0

Tại sao lại có các phiên bản?

Mục tiêu của việc lập phiên bản là để các nhà phát triển xây dựng ứng dụng có thể nắm trước được khi nào một API hoặc SDK có thể thay đổi. Các phiên bản này hỗ trợ quá trình phát triển web, nhưng cũng rất quan trọng đối với quá trình phát triển di động vì một người dùng ứng dụng của bạn trên điện thoại có thể mất nhiều thời gian để nâng cấp (hoặc có thể không bao giờ nâng cấp).

Mỗi phiên bản sẽ tồn tại ít nhất 2 năm kể từ khi phát hành. Vì thế, bạn sẽ có mốc thời gian chắc chắn về khoảng thời gian ứng dụng của bạn còn hoạt động, cũng như khoảng thời gian bạn phải cập nhật ứng dụng đó lên các phiên bản mới hơn.

Lịch trình phiên bản

Mỗi phiên bản được đảm bảo sẽ hoạt động trong ít nhất 2 năm. 2 năm sau ngày phát hành phiên bản tiếp theo, phiên bản cũ sẽ không dùng được nữa. Ví dụ: nếu API phiên bản 2.3 được phát hành vào ngày 25/03/2015 và API phiên bản 2.4 được phát hành vào ngày 07/08/2015 thì phiên bản 2.3 sẽ hết hạn vào ngày 07/08/2017 – 2 năm sau khi phát hành phiên bản 2.4.

Đối với API, sau khi một phiên bản không dùng được nữa, mọi lệnh gọi đến API đó sẽ được đặt mặc định là phiên bản cũ nhất, dùng được tiếp theo. Sau đây là ví dụ về mốc thời gian:

Đối với SDK, một phiên bản sẽ luôn có sẵn vì đó là gói có thể tải xuống. Tuy nhiên, SDK này có thể dựa vào các API hoặc phương thức không còn hoạt động nữa. Vì vậy, bạn nên giả định rằng SDK hết hạn không hoạt động nữa.

Bạn có thể tìm thấy thông tin cụ thể về mốc thời gian của phiên bản, các thay đổi và ngày phát hành trên trang nhật ký thay đổi của chúng tôi.

Mọi thứ sẽ hoàn toàn không thay đổi trong một phiên bản chứ?

Facebook có quyền thực hiện thay đổi đối với bất kỳ API nào trong một khoảng thời gian ngắn cho những vấn đề liên quan đến tính bảo mật hoặc quyền riêng tư. Các thay đổi này không xảy ra thường xuyên, nhưng vẫn xảy ra.

Nếu tôi không chỉ định phiên bản cho API thì sao?

Chúng tôi sẽ xem một lệnh gọi API không được chỉ định phiên bản là lệnh gọi không có phiên bản. Ví dụ: giả sử phiên bản hiện tại là 4.0. Lệnh gọi sẽ có dạng như sau:

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

Lệnh gọi không có phiên bản tương tự sẽ có dạng như sau:

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

Một lệnh gọi không có phiên bản sẽ sử dụng phiên bản được đặt trong bảng điều khiển ứng dụng ở thẻ Nâng cấp phiên bản API trong phần Cài đặt > Nâng cao. Trong ví dụ sau, phiên bản được đặt trong bảng điều khiển ứng dụng là 2.10 và lệnh gọi không có phiên bản sẽ tương đương với:

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

Bạn nên chỉ định phiên bản mọi lúc có thể.

Các giới hạn

  • Bạn không thể thực hiện các lệnh gọi API không có phiên bản đến JavaScript SDK của Facebook.

Ứng dụng của tôi có thể thực hiện lệnh gọi đến các phiên bản cũ hơn phiên bản hiện tại không?

Bạn có thể chỉ định các phiên bản cũ hơn trong lệnh gọi API miễn là chúng có sẵn và ứng dụng của bạn đã thực hiện lệnh gọi đến phiên bản đó. Ví dụ: nếu ứng dụng của bạn được tạo sau khi phát hành phiên bản 2.0 và thực hiện lệnh gọi bằng phiên bản 2.0, ứng dụng đó có thể thực hiện lệnh gọi đến phiên bản 2.0 cho đến khi phiên bản này hết hạn (kể cả khi các phiên bản mới hơn được phát hành). Nếu bạn đã tạo ứng dụng sau phiên bản 2.0 nhưng không thực hiện lệnh gọi nào cho đến phiên bản 2.2, ứng dụng đó sẽ không thể thực hiện lệnh gọi bằng phiên bản 2.0 hoặc 2.1. Ứng dụng đó chỉ có thể thực hiện lệnh gọi bằng phiên bản 2.2 và các phiên bản mới hơn.

Lập phiên bản API Marketing

API Marketing có cơ chế lập phiên bản riêng. Cả số phiên bản và lịch trình đều khác với trạng thái của API Đồ thị.

Tìm hiểu thêm về Lập phiên bản API Marketing

Gửi các yêu cầu có phiên bản

API Đồ thị

Dù là chính hay mở rộng, hầu hết mọi điểm cuối API Đồ thị đều có sẵn thông qua một đường dẫn có phiên bản. Chúng tôi có hướng dẫn đầy đủ về cách sử dụng các phiên bản với API Đồ thị trong Hướng dẫn bắt đầu nhanh API Đồ thị.

Hộp thoại

Các đường dẫn có phiên bản không chỉ đúng với điểm cuối API mà còn đúng với cả hộp thoại và plugin xã hội. Ví dụ: nếu muốn tạo hộp thoại Đăng nhập bằng Facebook cho một ứng dụng web, bạn có thể thêm số phiên bản vào đầu điểm cuối tạo hộp thoại:

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

Plugin xã hội

Nếu bạn đang sử dụng phiên bản HTML5 hoặc xfbml của plugin xã hội, phiên bản hiển thị sẽ được xác định bằng phiên bản đã chỉ định khi bạn khởi tạo JavaScript SDK.

Nếu đang chèn phiên bản iframe hoặc phiên bản liên kết thuần túy của một trong các plugin, bạn sẽ thêm số phiên bản vào đầu đường dẫn nguồn của plugin:

<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>

Gửi các yêu cầu có phiên bản từ SDK

Nếu bạn đang dùng Facebook SDK dành cho iOS, Android hoặc JavaScript, việc thực hiện các lệnh gọi lập phiên bản phần lớn sẽ là tự động. Lưu ý rằng điều này khác với hệ thống lập phiên bản riêng của từng SDK.

JavaScript

JavaScript SDK chỉ có thể sử dụng các phiên bản API khác nếu bạn đang dùng đường dẫn sdk.js.

Nếu đang dùng FB.init() từ JavaScript SDK, bạn cần sử dụng thông số phiên bản như sau:

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

Nếu bạn đặt cờ phiên bản trong init, mọi lệnh gọi đến FB.api() sẽ tự động được thêm phiên bản vào đầu đường dẫn được gọi. Điều này cũng đúng đối với mọi hộp thoại Đăng nhập bằng Facebook vô tình được gọi. Bạn sẽ nhận được hộp thoại Đăng nhập bằng Facebook cho phiên bản API đó.

Nếu cần, bạn có thể ghi đè một phiên bản bằng cách thêm phiên bản đó vào đầu đường dẫn của điểm cuối trong lệnh gọi FB.api().

iOS

Mỗi phiên bản của Facebook SDK dành cho iOS được phát hành đều gắn liền với phiên bản có sẵn vào ngày phát hành. Nghĩa là nếu đang nâng cấp lên SDK mới thì bạn cũng đang nâng cấp lên phiên bản API mới nhất (mặc dù bạn có thể chỉ định thủ công bất kỳ phiên bản API cũ hơn nào có sẵn bằng [FBSDKGraphRequest initWithGraphPath]). Phiên bản API sẽ được liệt kê cùng với bản phát hành của từng phiên bản Facebook SDK dành cho iOS.

Giống như JavaScript SDK, phiên bản sẽ được thêm vào đầu mọi lệnh gọi đến API đồ thị thông qua Facebook SDK dành cho iOS. Ví dụ: nếu v2.7 là phiên bản mới nhất của API, lệnh gọi /me/friends – dùng trong mã mẫu sau – sẽ thực sự gọi /v2.7/me/friends:

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

Bạn có thể ghi đè phiên bản của lệnh gọi bằng [FBSDKGraphRequestConnection overrideVersionPartWith].

Android

Mỗi phiên bản của Facebook SDK dành cho Android được phát hành đều gắn liền với phiên bản có sẵn vào ngày phát hành. Nghĩa là nếu đang nâng cấp lên SDK mới thì bạn cũng đang nâng cấp lên phiên bản API mới nhất (mặc dù bạn có thể chỉ định thủ công bất kỳ phiên bản API cũ hơn nào có sẵn bằng GraphRequest.setVersion()). Phiên bản API sẽ được liệt kê cùng với bản phát hành của từng phiên bản Facebook SDK dành cho Android.

Giống như JavaScript SDK, phiên bản sẽ được thêm vào đầu mọi lệnh gọi đến API đồ thị thông qua Facebook SDK dành cho Android. Ví dụ: nếu v2.7 là phiên bản mới mất của API, lệnh gọi /me – dùng trong mã mẫu sau – sẽ thực sự gọi /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();

Bạn có thể ghi đè phiên bản của lệnh gọi bằng GraphRequest.setVersion().