Graph API 概覽

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

基本入門

Graph API 是以「社交圖表」的想法命名 ─ 代表 Facebook 資訊,包含:

  • 節點 ─ 基本上就是如用戶、相片、專頁、回應這些「東西」
  • 邊緣 ─ 這些「東西」之間的連結,例如專頁的相片,或相片的回應
  • 欄位 ─ 這些「東西」的資訊,例如用戶的生日,或專頁名稱

Graph API 是以 HTTP 為基礎,因此可以配搭任何具有 HTTP 程式庫的語言使用,例如 cURL 及 urllib。在下列章節中,我們將進一步解釋您可以用 Graph API 做什麼,但是這代表您也可以直接在瀏覽器上使用 Graph API,例如 Graph API 要求等同於:

GET graph.facebook.com
  /facebook/picture?
    redirect=false

大部分 Graph API 要求需要使用存取憑證,您的應用程式執行 Facebook 登入後即可產生。

本概覽將展示您 Graph API 如何在社交圖表上讀取和發佈資料。

構成方式

這些在我們的 Graph API 使用指南皆有涵蓋,但是整體上,您可以藉由在這些節點上對節點或邊緣發出 HTTP GET 要求來讀取 API。

幾乎所有要求都在 graph.facebook.com 傳遞至 API,唯一的例外是使用 graph-video.facebook.com 上載的影片。

物件 ID

每一個節點都有獨特的 ID,用來透過 Graph API 存取節點。我們不特別記錄任何節點/物件 ID 的結構或格式,因為這極有可能隨著時間改變,而且應用程式不應該基於目前的結構做假設。

以下教您該如何使用 ID 發出節點的要求:

GET graph.facebook.com
  /{node-id}

或邊緣:

GET graph.facebook.com
  /{node-id}/{edge-name}

您通常可以使用參數發出 HTTP POST 要求,將 API 發佈至節點:

POST graph.facebook.com
  /{node-id}

或邊緣:

POST graph.facebook.com
  /{node-id}/{edge-name}

可以使用相同端點的 HTTP DELETE 要求,透過 API 完成刪除(以及透過 POST 要求升級)。

API 版本

Graph API 有多種版本可用,可以隨時存取。每一個版本包含一組核心欄位和邊緣作業。我們保證在推出後至少 2 年內,可以在該版本使用核心 API 且不必修改。平台變更記錄可以告訴您哪些版本目前可以使用。

某些特定作業,例如在邊緣內發佈、或節點內的特定欄位,可能得以成為核心,而整個邊緣或節點則不必為核心。我們在 Graph API 參考文件內使用 來註明這些核心 API。

所有在這些核心 API 之外的都稱為擴展 API。這些 API 仍然可透過版本路徑存取,但可能得以隨時修改或移除,根據我們的平台藍圖宣布的 90 天轉移而定。或者,它們可能就直接包含於下一個可用的 API 版本中。

您可以在我們的指南中參閱版本目的詳細資訊,但是我們將在此向您解釋如何對特定版本的 Graph API 進行調用。

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

GET graph.facebook.com
  /v2.2/me

所有版本都適用,一般形式如下:

GET graph.facebook.com
  /vX.Y/{request-path}

其中需要的版本是 X.Y。我們發佈了藍圖中所有可用版本的清單。我們所有的 Graph API 參考文件都提供各版本的資訊,因此請務必確認您查閱的是正確的版本;有些版本會移除節點和邊緣,有些則會加入。

現在讓我們試試 API 要求,您就會知道這有多簡單。

載入 Graph API 測試工具

瞭解 Graph API 最簡單的方法,就是和 Graph API 測試工具配搭使用,這是一個低級別工具,可以用來查詢、增加和移除資料。在與 Facebook 整合時,這是非常便利、觸「指」可及的資源。所以您的下一步是前往 Graph API 測試工具

Graph API 測試工具

產生基本用戶存取憑證

當您建立屬於您的應用程式時,您需要瞭解存取憑證以及如何使用「Facebook 登入」產生,但是現在,我們可以藉由 Graph API 測試工具快速取得:

  1. 點擊測試工具右上方的 Get Token 按鈕。
  2. 選擇 Get User Access Token 選項。
  3. 在接下來的對話框中,不要核取任何方格,只要點擊藍色的 Get Access Token 按鈕。
  4. 您會看到一個 Facebook 登入對話框,在這裡點擊 OK 以繼續操作。

發出第一個要求

現在您已準備好發出第一個 Gragh API 要求,我們就從「讀取」要求開始。在「GET」下拉式選單按鈕旁邊的文字欄位(我們稱為路徑欄位),刪除現有文字,然後輸入「me」:

現在按下「提交」按鈕。程序需時數秒,但是您現在應該可以看到回應介面出現了許多資訊。出現在這裡的內容,取決於您個人檔案的私隱設定,但是應該至少有一些基本欄位:

您剛才在 Grapg API 測試工具所做的,就和以下 Graph API 「讀取」要求相同:

GET graph.facebook.com
  /me

/me 是一個特殊端點,會轉譯至使用存取憑證發出要求的用戶編號。

恭喜,您在剛剛完成了第一次 Graph API 要求!

取得發佈權限

接著我們要嘗試使用 Graph API 將一些內容發佈到 Facebook。只有當您在建立屬於您的自訂撰寫程式,且沒有在網頁iOS、或 Android 使用其中一個分享對話框時,才可以在您的應用程式進行這個程序。Facebook 分享對話框並不會要求您執行 Facebook 登入,或建立您自己的介面讓別人分享。

若要使用 Graph API 探索發佈,請再一次點擊「取得存取憑證」按鈕,而這一次,請選擇 publish_actions 權限:

現在點擊藍色「取得存取憑證」按鈕,然後您會再次看到登入對話框。這裡將會徵求您同意 Graph API 測試工具代表您發佈帖子。如有需要,您也可以把受眾改為「只限本人」,這樣就只有您可以看見帖子,但是您要接受這個對話框,並進行下一個步驟。

發佈帖子

如果您已請求過 publish_actions 權限,現在請點擊「GET」按鈕,然後從出現的下拉式選單選擇「POST」。進入路徑欄位中的 me/feed,然後點擊「新增欄位」。

在出現的新欄位中,「名稱」填入 message,「值」填入 Hello, World。看起來如同這樣:

現在點擊藍色「提交」按鈕,幾秒鐘之後,回應介面應該看起來像這樣:

{
  "id": "{new-post-id}"
}

這代表您剛剛透過 Graph API 發佈您的第一則帖子! 您可以前往個人檔案,然後您應該可以在此看到這則帖子:

您剛才在 Graph API 測試工具所做的,就和以下 Graph API 「發佈」要求相同:

POST graph.facebook.com
  /me/feed?
    message="Hello, World."&
    access_token={your-access-token}

後續步驟

您已經學會基礎了,何不繼續深入瞭解使用 Graph API? 如果還沒學會,我們建議您先參閱 Facebook 登入,特別是如何產生存取憑證,當您進行更複雜的 Graph API 調用時,會需要用到。