概覽

Graph API 是在 Facebook 平台輸入和輸出資料的主要方法。這是低級別 HTTP 型 API,應用程式可以用來以程序化的方式查詢資料、發佈新動態、管理廣告、上載相片,以及執行各種操作。

基本入門

Graph API 是以「社交圖表」的想法命名——代表 Facebook 上的資訊。內容包含:

  • 節點:基本上就是如「用戶」、「相片」、「專頁」、「回應」這些個別物件
  • 邊緣:一組物件與單一物件之間的連結,例如專頁內的多張相片,或相片內的多個回應
  • 欄位:物件的相關資料,例如用戶的生日或專頁的名稱

一般而言,您會使用節點取得特定物件的資料、使用邊緣取得單一物件上的一組物件,然後使用欄位來取得一組物件內的單一物件或每個物件的相關資料。

HTTP

Graph API 是以 HTTP 為基礎,因此可以配搭任何具有 HTTP 程式庫的語言使用,例如 cURL 及 urllib。這就表示您可以直接在瀏覽器內使用 Graph 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 參數與預留位置值。大部分的 Graph API 要求都需要一個存取憑證。您之後一定要閱讀存取憑證文件來瞭解其運作方式,但現在您只需要知道:

  • 幾乎所有的 Graph API 要求都需要某種存取憑證,且
  • 取得存取憑證最簡單的方式就是安裝 Facebook 登入

我們在 Graph API 文件中提供的虛擬程式碼要求/回應並不會刻意提及存取憑證,但您必須假設每一個要求中都含有存取憑證,以便獲得回應。

架構

我們會在使用 Graph 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

版本

Graph API 有多種版本。您可以在我們的應用程式版本指南中進一步瞭解建立版本的相關資訊,但是我們將在此向您解釋如何傳送調用至特定版本。

這非常簡單,只需在要求路徑的開頭前面加上字母 v 與版本識別碼。例如,這是對 2.9 版的調用:

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

如果您沒有加入版本識別碼,我們會預設使用最舊的可用版本,所以建議您最好在要求中加入版本識別碼。

Graph API 變更記錄會列出所有可用版本,我們的參考資料文件可以讓您按照本版刪選內容。

後續步驟

現在讓我們來看看使用 Graph API,進一步瞭解更複雜的要求及其回應,並瞭解您可以使用 Graph API 執行哪些操作。