Graph API是什麼東東?

Graph API是Facebook所推出的一種技術標準，它的核心概念是: 「物件與連結」。為什麼稱為「Graph API」呢? Facebbook將整個社群抽象為物件與物件之間連結的圖，來看看我畫的示意圖:

中間那個帥氣的騎士，就是在下，我與其它物件的連結就是透過彼此的關係。舉例來說，我與上方兩位猛男就是朋友(friends)的連結；左邊就是所謂的相本(albums)的連結；右邊的忐忑與火影忍者分別是音樂(music)與書籍(books)的連結；下面的就是所謂的讚(likes)的連結，魏小猴讚啦!猛男與我都是屬於User的物件，因此也有friends、albums、music、book等連結。這讓我可以透過這樣的連結關係去得知兩位猛男的朋友(freinds)名單。左邊的相本屬於Album的物件，也可以透過它的讚(likes)的連結去找到誰覺得這相本很讚，透過圖片(photos)連結可以找到相本內的圖片。整個Facebook就是透過這些物件與連結建立而成的Social Graph。Facebook所提供存取的介面，就稱為「Graph API」。

如何使用?

Facebook提供給外部程式存取的方式就是URL，如果以Javascript實作就是透過Ajax，Java可以用HttpConnection或直接用HttpClient的API，簡單而言就是「透過Http的Request」。發出請求的URL格式如下，「ID為物件id，CONNECTION_TYPE為物件連結的種類」：

https://graph.facebook.com/ID/CONNECTION_TYPE

舉例來說，我想存取某一個User的物件，可以透過它的id存取:

https://graph.facebook.com/100000274774093/

而Facebook會給你Json format的回傳內容，以User物件而言，在沒有授權的情況下，能夠存取到以下這些欄位:

{
   "id": "100000274774093",
   "name": "鄭發哥",
   "first_name": "發哥", 
   "last_name": "鄭", 
   "link": "https://www.facebook.com/rusiasia",
   "username": "rusiasia",
   "gender": "male",
   "locale": "zh_TW"
}

如果我想查詢User 100000274774093的朋友名單，可以加上friends的connection type，但它是需要使用者授權的喔!

https://graph.facebook.com/100000274774093/friends?access_token=xxxxxxxxx....

回傳的結果如下:

{
  "data": [
    {
      "name": "Natalie Lee", 
      "id": "527104164"
    }, 
    {
      "name": "阿倫", 
      "id": "538008660"
    }, 
    {
      "name": "Tsung Ham Shen", 
      "id": "544172024"
    }, 
    ...

如果沒有授權，會出現這樣的回傳結果:

{
  "error": {
    "message": "(#604) Can't lookup all friends of 1000559192. Can only lookup 
         for the logged in user or the logged in user's friends that are users of your app.", 
    "type": "OAuthException", 
    "code": 604
  }
}

那我要怎麼知道Facebook到底有哪些物件，物件的哪些欄位需要授權，連結型態有哪些呢?

物件?連結型態?權限?

Facebook提供了多少物件的存取、各個物件所提供的欄位，都可以在Developers文件中查詢到。下圖就是目前Facebook所支援的物件種類，點擊進去各連結可以看到物件支援的欄位與連結型態。

如User物件所支援的欄位。在先前取得User 100000274774093的範例中，如果應用程式沒經過使用者授權，如下圖所示，我們僅能取得id、name、first_name等欄位。如果想要取得使用者設定的languages欄位，使用者必須授權user_likes這個權限並使用access_token去存取Graph API。我們的應用程式想要取得什麼欄位，只要根據這個表格的欄位與權限對應資訊，我們就可以和使用者要求怎麼樣的授權。(access_token即應用程式存取Facebook資源的一把鑰匙)

連結型態也是一樣。如果想取得User的相簿(albums)，應用程式就需要使用者的user_photos授權。顧名思義，friends_photos就是為了要取得朋友相簿的授權。

讓我們來個練習!

假如我想取得朋友的生日，那我該怎麼做呢?有以下幾個步驟:

friends_birthday的授權: 要取得朋友的生日欄位，必須要使用者有提供friends_birthday的權限。
取得朋友列表: 透過friends的連結型態去取得我的朋友列表，這只要有access_token就能夠使用了!
使用朋友的id去呼叫Graph API: 就是Http的Request。

這個範例不需要寫任何程式碼，主要透過Facebook提供的Graph API測試工具:「Graph API瀏覽工具」，讓我們使用它來練習吧!(讀萬卷書不如行萬里路，動手做做看)

取得Access Token

首先在Graph API瀏覽工具的畫面中，點擊取得存取代碼，我們需要授權的是Friends Data Permissions中的friends_birthday。

點擊Get Access Token後，會出現授權的對話盒，我想這大家應該不陌生。授權後我們就有access_token可以使用了!

取得朋友列表

在URL的地方輸入me/friends去取得我的朋友列表，其中me代表目前登入的使用者，它是個User的物件。點擊確認後就可以在下方看到輸出結果。

取得朋友生日

為了避免讓人認為我是色胚，我們以阿倫為範例，id為538008660。我們直接在URL上輸入538008660，就會出現阿倫的個人資料了。

看到了嗎?是不是很簡單呢?

Summary

這篇文章的目的要讓你對Graph API有基本的認識，包含該怎麼去看Document去得知該怎麼去取得你要的資料。以下幾個項目可能是你還有疑問又或者是期望想看到的:

授權項目中，也包含了授權存取朋友的資料。但需要注意的是，如果朋友不想讓你看到他的相簿，即使你授權給應用程式，也別想看到裡面的美女圖拉!所以別以為你可以透過這個管道看到某些正妹的「私藏」!
acess_token到底要怎麼獲得呢?這個問題其實有點複雜也可以說很簡單。簡單來說，就是透過Facebook提供的OAuth2.0認證機制，根據你需要的權限讓使用者授權並取得access_token。但實作上，又會根據不同種類的應用程式有所差別。在之後的文章中，我會再一一介紹。
說好的實作呢? 一般Web應用程式透過Javascript SDK已經綽綽有餘了，藉由FB.login做認證並取得access_token，透過FB.api呼叫Graph API。其它如PHP、iOS、Android，Facebook都有提供SDK；Adobe也提供了Flash的SDK。雖說有那麼多的SDK，在之後的文章我的主力也是放在介紹Java的Grah API - RestFB。所以，其它的等我寫到再說吧!
再簡單也只不過是URL? Graph API是很強大滴，除了上述的內容外，還提供了資料分頁、資料編碼設定、Query條件、發佈、刪除、Locale設定、批次執行等API支援。說那麼多我也不是全會啦，但我有著好學不倦的精神，以後有機會再一一分享給大家。

阿兩的筆記本 Ryoutsu's Notebook

搜尋此網誌