總覽

圖形 API 是在 Facebook 開放平台取得與寫入資料的主要方法。這是低階 HTTP 型 API,可讓應用程式以程式設計的方式來查詢資料、發佈新動態、管理廣告、上傳相片及執行各種工作。

基本入門

圖形 API 是以「社交關係圖」的概念命名,代表 Facebook 上的資訊,其中包括:

  • 節點 — 基本的個別物件,例如用戶、相片、粉絲專頁、留言等
  • 關係連線 — 物件集合和單一物件之間的關係鏈,例如粉絲專頁上的相片或對相片的留言。
  • 欄位 — 物件相關資料,例如用戶生日或粉絲專頁名稱

一般而言,節點是用於取得特定物件的資料,關係連線是用於取得單一物件上的物件集合,欄位是用於取得單一物件或集合中各個物件的資料。

HTTP

圖形 API 是以 HTTP 為基礎,因此可以搭配任何具有 HTTP 程式庫的語言使用,例如 cURL 及 urllib。這表示您可在瀏覽器中直接使用圖形 API。例如,在瀏覽器中要求以下網址:

https://graph.facebook.com/facebook/picture?redirect=false

等同於執行以下 cURL 要求:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture?redirect=false&access_token={valid-access-token-goes-here}"

存取權杖

您大概有注意到以上 cURL 要求中的 access_token 參數和預留位置值。大部分的圖形 API 要求都需要存取權杖。雖然您之後還是必須詳閱存取權杖文件來瞭解存取權杖的運作方式,不過目前您只需知道以下幾點:

  • 幾乎所有的圖形 API 要求都需要某種存取權杖,而且
  • 若要取得存取權杖,最簡單的方式是透過實作 Facebook 登入

圖形 API 文件中以虛擬程式碼表示的要求/回應範例不會明確參照存取權杖,但您應假定要求中已包含存取權杖,才可收到回應。

架構

使用圖形 API 指南中有完整說明,不過簡單來說,使用方式為:

  • 節點是用於取得個別物件的資料
  • 關係連線是用於取得與節點連結的物件集合,或是用於發佈物件至這些集合
  • 欄位是用於指定回應中所需包含的資料

主機網址

幾乎所有要求都會傳遞至 graph.facebook.com 主機網址。唯一的例外是影片上傳要求會使用 graph-video.facebook.com

物件 ID

節點是個別物件,各有獨一無二的編號,所以若要取得節點相關資訊,方式為直接查詢節點編號。例如,Facebook 官方粉絲專頁的編號為 20531316728。您可使用該編號直接查詢:

GET graph.facebook.com
  /20531316728

如需取得節點特定資料(稱為欄位),則可包含 fields 參數來指定回應中所需傳回的欄位。從粉絲專頁節點參考資料中可見,讀取粉絲專頁物件時,其中一個可取得的欄位為 cover,亦即粉絲專頁的封面相片。該查詢會類似以下所示:

GET graph.facebook.com
  /20531316728?fields=cover

大部分節點都有關係連線,可傳回與該節點連結的物件集合。若要查詢關係連線,請同時使用節點編號和關係連線名稱。粉絲專頁節點參考資料中列出的其中一個關係連線為 photos,該關係連線會傳回粉絲專頁擁有的所有相片物件。所以,若要取得 Facebook 粉絲專頁擁有的所有相片,請查詢該節點的 photos 關係連線:

GET graph.facebook.com
  /20531316728/photos

部分節點允許以 POST 作業更新欄位。例如,假使您是 Facebook 粉絲專頁的管理員,便可如下所示更新其 description 欄位:

POST graph.facebook.com
  /20531316728?description=The%20OFFICIAL%20Facebook%20Page

關係連線通常允許以 POST 作業,將新物件發佈至節點的集合以下範例說明如何將相片發佈至 Facebook 粉絲專頁擁有的相片集合中:

POST graph.facebook.com
  /20531316728/photos

當然,若要將物件發佈至集合,通常需要該物件的其他欄位,例如相片的網址、標題或說明。關係連線參考文件中詳述必要和選用欄位。

最後,若要刪除節點,通常可針對物件編號執行 DELETE 作業來完成。

DELETE graph.facebook.com
  /20531316728

版本

圖形 API 有多個版本。您可在應用程式版本指南中詳閱版本設定的資訊,此處只說明如何向特定版本發出呼叫。

方法非常簡單,只需在要求路徑的開頭依序加上字母 v 和版本編號即可。例如,以下是向 2.9 版發出的呼叫:

GET graph.facebook.com
  /v2.9/20531316728/photos

若未包含版本編號,系統將預設為可用的最舊版本,所以最好在要求中包含版本編號。

圖形 API 變更紀錄中會列出所有可用版本,參考文件還可讓您按版本篩選內容。

後續步驟

接下來請參閱使用圖形 API 一節,查看一些更複雜的要求及其回應,並瞭解其他可透過圖形 API 執行的動作。