存取權杖

當用戶使用「Facebook 登入」連結到應用程式時,這個應用程式將能夠取得存取權杖,供用戶暫時且安全地存取 Facebook API。

存取權杖是一種可辨識用戶、應用程式或粉絲專頁的隱晦字串,可以讓應用程式用來進行圖形 API 呼叫。 存取權杖可經由許多方法取得,本文件稍後會介紹各種方法。 由權杖中包含的資訊,可得知這個權杖將於何時到期,以及哪個應用程式產生了這個權杖。因為隱私檢查的關係,在 Facebook 上的大多數 API 呼叫都需要包含存取權杖。不同類型的存取權杖可用來支援不同使用情況:

存取權杖類型 說明

用戶存取權杖

用戶權杖是最常使用的權杖類型。 每當應用程式呼叫 API 以代表用戶讀取、修改或寫入特定用戶的 Facebook 資料時,就會需要這種類型的存取權杖。 用戶存取權杖通常可經由「登入」對話方塊取得,且通常會要求用戶允許您的應用程式取得權杖

應用程式存取權杖

若要修改和讀取應用程式設定,就會需要這種類型的存取權杖,此外也可以用來發佈開放社交關係圖動作。 應用程式存取權杖可使用應用程式與 Facebook 之間預先同意的密鑰產生,之後可在變更應用程式範圍設定的呼叫期間使用。 您可經由伺服器對伺服器的呼叫取得應用程式存取權杖

粉絲專頁存取權杖

粉絲專頁存取權杖和用戶存取權杖類似,不過粉絲專頁存取權杖可提供權限給讀取、寫入或修改屬於 Facebook 粉絲專頁資料的 API。 若要取得粉絲專頁存取權杖,您必須先從取得用戶存取權杖開始,然後要求取得 manage_pages 權限。 您有了用戶存取權杖之後,就可以經由圖形 API 取得粉絲專頁存取權杖

用戶端權杖

用戶端權杖是一種識別碼,您可以將用戶端權杖嵌入原生行動應用程式二進位檔或桌面版應用程式,以辨識您的應用程式。 由於用戶端權杖嵌入在應用程式內,因此並不是用來當作密鑰識別碼使用。 用戶端權杖可用來存取應用程式層級 API,但只能存取非常有限的子集。您可以在應用程式主控板內找到這個用戶端權杖。因為用戶端權杖很少用到,所以我們將不會在這份文件中討論, 不過,您可以在任何使用用戶端權杖的 API 文件中找到相關資訊。

產生存取權杖

- 用戶存取權杖

- 應用程式存取權杖

- 粉絲專頁存取權杖


用戶存取權杖

儘管每個平台都可經由不同的 API 產生存取權杖,但是所有平台都應遵循基本策略,以取得用戶權杖:

不同平台會有不同的方法來開始這個程序,而且其中所包含的功能,可代表開發人員和授予權限的用戶管理存取權杖:

JavaScript

Facebook JavaScript SDK 會自動在瀏覽器 Cookie 中取得用戶存取權杖,並持續保存。您可以呼叫 FB.getAuthResponse,如此將會在回應內加入 accessToken 屬性,進而擷取用戶存取權杖。

Android

Facebook Android SDK 可透過 com.facebook.AccessToken 類別自動管理用戶存取權杖。您可以實作 Android 專用 Facebook 登入,深入瞭解如何取得用戶存取權杖。您可以檢查 Session.getCurrentAccessToken 來擷取用戶存取權杖。

iOS

Facebook iOS SDK 可透過 FBSDKAccessToken 類別自動管理用戶存取權杖。您可以實作 iOS 專用 Facebook 登入,深入瞭解如何取得用戶存取權杖。您可以檢查 FBSDKAccessToken.currentAccessToken 來擷取這個存取權杖。

網頁版(不使用 JavaScript)

建立網頁版應用程式但不使用 Facebook JavaScript SDK 時,您需要在該文件所列步驟中產生存取權杖。

程式碼範例

Android

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    FacebookSdk.sdkInitialize(this.getApplicationContext());
    accessToken = AccessToken.getCurrentAccessToken();
}

iOS

- (void)viewDidLoad
{
  [super viewDidLoad];
  NSString *accessToken = [FBSDKAccessToken currentAccessToken];
}

JavaScript(網頁版)

FB.getLoginStatus(function(response) {
  if (response.status === 'connected') {
    var accessToken = response.authResponse.accessToken;
  } 
} );

短期權杖和長期權杖

用戶存取權杖有兩種形式:短期權杖和長期權杖。 短期權杖的存留期通常約為一到兩個小時,而長期權杖通常有約 60 天的存留期。 請勿預期存留期會保持不變;存留期有可能無預警地變更,或提前到期。 請在處理錯誤下方查看更多資訊。

經由網頁版登入所產生的存取權杖是短期權杖,但您可以將他們轉換成長期權杖,方法是使用您的應用程式密鑰,進行伺服器端 API 呼叫。

根據預設,使用 Facebook iOS 和 Android SDK 的行動應用程式會取得長期權杖。

對 Facebook 行銷 API 使用長期權杖進行標準存取的應用程式,將收到沒有到期時間的長期權杖。這些權杖仍有可能因其他原因而失效,但不會只因時間因素就到期。這點也適用於企業管理平台中系統用戶的存取權杖。

權杖屬於可攜式

瞭解存取權杖時,很重要的一個認知是權杖具有可攜式特性。 您有了存取權杖後,可以用來從行動用戶端、網頁瀏覽器或您的伺服器,對 Facebook 的伺服器進行呼叫。 如果權杖是在用戶端上取得,您就可以傳送這個權杖到您的伺服器,然後用在伺服器對伺服器呼叫。 如果權杖經由伺服器呼叫取得,您也可以傳送這個權杖給用戶端,然後從用戶端進行呼叫。

在您的用戶端和伺服器之間移動權杖必須透過 HTTPS 以安全的方式進行,以確保用戶帳號的安全性。請詳閱在您的用戶端和伺服器之間移動權杖的可能影響

應用程式存取權杖

應用程式存取權杖可用來代表應用程式提出對 Facebook API 的要求,而非代表用戶。這可以用來修改應用程式的參數、建立並管理測試用戶,或是讀取您的應用程式洞察報告。

限制

使用用戶存取權杖提出要求的應用程式,通常可能會看到某些用戶資料,但如果使用應用程式存取權杖,就不一定可以看到這些用戶資料。如果您在應用程式中讀取並使用用戶資料,應該要使用用戶存取權杖,而非應用程式存取權杖。

如果您的應用程式在應用程式主控板的進階設定中設定為 Native/Desktop,應用程式存取權杖便會被視為不安全,因此將不能用於 API 呼叫。這是因為我們假設原生或桌面應用程式會把應用程式密鑰嵌入某處(因此使用這種密鑰產生的應用程式存取權杖並不安全)。

產生應用程式存取權杖

若要產生應用程式存取權杖,您需要進行圖形 API 呼叫:

GET /oauth/access_token
    ?client_id={app-id}
    &client_secret={app-secret}
    &grant_type=client_credentials

這個呼叫將傳回應用程式存取權杖,可用來取代用戶存取權杖,以進行如上所述的 API 呼叫。同樣地,為了安全起見,請切勿將應用程式存取權杖硬式編碼至用戶端程式碼,因為這樣做有可能讓載入您網頁或反編譯您應用程式的所有用戶,都有存取您應用程式密鑰的完整權限,進而可以修改您的應用程式。 這代表在大多數情況下,您將只能在伺服器對伺服器呼叫中使用應用程式存取權杖。

請注意:這項要求會使用您的應用程式密鑰,因此請切勿以用戶端程式碼進行,或是以可能被反編譯的應用程式二進位檔進行。請務必注意,絕對不要將您的應用程式密鑰與任何用戶分享。因此,這個 API 呼叫只應該使用伺服器端程式碼進行。

還有另一種方法可進行圖形 API 呼叫,且不需要使用所產生的應用程式存取權杖。 您進行呼叫時,可以只傳遞您的應用程式編號和應用程式密鑰,將其當成 access_token 參數:

https://graph.facebook.com/endpoint?key=value&access_token=app_id|app_secret

是否使用產生的存取權杖,或者使用這個方法,取決於您想將應用程式密鑰隱藏在哪裡。

粉絲專頁存取權杖

粉絲專頁存取權杖可用在圖形 API 中,以管理 Facebook 粉絲專頁。若要產生粉絲專頁存取權杖,粉絲專頁的管理員必須授予稱為 manage_pages進階權限。獲得此權限之後,您就可以使用具有所需權限的用戶存取權杖以及下列圖形 API 要求,擷取粉絲專頁存取權杖:

GET /me/accounts HTTP/1.1
Host: graph.facebook.com

這項要求將傳回這位用戶所管理的粉絲專頁清單和其他有關專頁的資訊,像是粉絲專頁類別、管理員所擁有的專頁權限,以及粉絲專頁存取權杖:

{
  "data": [
    {
      "category": "Product/service",
      "name": "Sample Page",
      "access_token": "{access-token}",
      "id": "1234567890",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    }, 
}

您可以使用粉絲專頁存取權杖來代表粉絲專頁發出 API 呼叫。例如,您可以發佈近況更新到粉絲專頁(而非這位用戶的動態時報),或讀取粉絲專頁洞察報告資料。

每個粉絲專頁、管理員和應用程式都有專屬的粉絲專頁存取權杖。

粉絲專頁管理員有不同的角色,會透過以上範例中傳回的 perms 陣列指出。粉絲專頁管理員可使用的功能是根據權杖與角色中所述的 perms 值而決定。