圖形 API 總覽

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

基本入門

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

  • 節點 ─ 基本的「事物」,例如用戶、相片、粉絲專頁、留言等
  • 關係連線 ─ 這些「事物」之間的連結,像是粉絲專頁的相片,或是相片的留言
  • 欄位 ─ 這些「事物」的資訊,像是用戶的生日,或是粉絲專頁名稱

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

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

大部分的圖形 API 要求必須使用存取權杖,也就是您的應用程式執行 Facebook 登入後所產生的存取權杖。

本總覽將說明圖形 API 如何在社交關係圖上讀取和發佈資料。

構成方式

我們的圖形 API 使用指南已完整說明構成方式,但是概括來說,您可以藉由在這些節點上對節點或關係連線發出 HTTP GET 要求來讀取 API。

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

物件 ID

每一個節點都有獨特的 ID,用來透過圖形 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}

透過 API 進行刪除是使用對相同端點發出 HTTP DELETE 要求來完成(進行更新則是透過 POST 要求)。

API 版本

圖形 API 有多種版本可用,可以隨時存取。每一個版本包含一組核心欄位和關係連線作業。我們保證每個版本在推出後至少 2 年內,該版本的核心 API 都可持續使用,不會有任何修改。平台變更紀錄可以告訴您哪些版本目前可以使用。

某些特定作業(例如:在關係連線內發佈,或是節點內的特定欄位)可能得以作為核心,而不必以整個關係連線或節點為核心。我們在圖形 API 參考文件內使用 來註明這些核心 API。

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

您可以在我們的指南裡參閱版本目的詳細資訊,但是我們將在此向您解釋如何對特定版本的圖形 API 進行呼叫。

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

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

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

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

其中需要的版本是 X.Y。我們在變更紀錄中發佈了可用版本的完整清單。我們所有的圖形 API 參考文件都提供各版本的資訊,因此請檢查並確認您查閱的是正確版本;有些版本會移除節點和關係連線,有些則會新增節點和關係連線。

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

載入圖形 API 測試工具

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

圖形 API 測試工具

產生基本用戶存取權杖

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

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

發出第一個要求

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

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

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

GET graph.facebook.com
  /me

/me 是一個特殊端點,會轉譯為發出要求所用存取權杖的用戶編號。

恭喜,您已完成第一次圖形 API 要求!

取得發佈權限

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

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

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

發佈貼文

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

在出現的新欄位裡,「名稱」填入 message,「值」填入 Hello, World。應該類似如下所示:

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

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

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

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

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

後續步驟

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