概覽

Graph API 是在 Facebook 平台輸入和輸出資料的主要方法。Graph API 是一種以 HTTP 為基礎的 API，應用程式可使用此 API 以程式輔助的方式查詢資料、發佈新動態、管理廣告、上載相片和執行各種其他任務。

Graph API 是以「社交關係圖」的想法命名，代表 Facebook 上的資訊。當中包含節點、邊緣和欄位。一般而言，您需要使用節點來取得特定物件的資料、使用邊緣以取得與單一物件有關的一組物件，然後使用欄位來取得單一物件或一組物件中每個物件的相關資料。在本文中，我們可能會把節點和邊緣稱為「端點」。例如「向用戶端點傳送 GET 要求」。

HTTP

所有的資料傳輸都會遵守 HTTP/1.1，且所有端點都需要使用 HTTPS。由於 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"

我們也啟用了 facebook.com 的 includeSubdomains HSTS 指令，但這不會對您的 Graph API 呼叫造成負面影響。

代管網址

幾乎所有的要求都會傳送到 graph.facebook.com 代管網址。唯一的例外是影片上載，會改用 graph-video.facebook.com。

存取憑證

存取憑證可以讓您的應用程式存取 Graph API。幾乎所有的 Graph API 端點都需要使用某種存取憑證，所以當您每次存取端點時，您的要求都可能會要求獲取一個存取憑證。存取憑證通常可執行兩種功能：

• 允許應用程式存取用戶資訊，而無需使用用戶密碼。例如，您的應用程式需要用戶電郵才能執行某個功能。若用戶同意允許您的應用程式從 Facebook 擷取其電郵地址，用戶無需輸入 Facebook 密碼，您的應用程式便能取得其電郵地址。
• 存取憑證允許我們識別應用程式、使用應用程式的用戶，以及用戶允許應用程式存取的數據類型。

請瀏覽我們的存取憑證文件以進一步了解詳情。

節點

節點是一個含有不重複編號的個別物件。例如，用戶節點物件有很多，而每個節點物件都有一個代表 Facebook 用戶的不重複編號。Facebook 社交關係圖的一些節點包括專頁、群組、帖子、相片和回應。

下列 cURL 例子代表對用戶節點的呼叫。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?access_token=ACCESS-TOKEN"

根據預設，此要求會按照 JSON 格式傳回下列數據：

{
  "name": "Your Name",
  "id": "YOUR-USER-ID"
}

節點中繼資料

您會獲得一張列出所有欄位的清單，包括欄位名稱、說明以及節點物件的數據類型，例如用戶、專頁或相片。傳送 GET 要求至物件編號，並在要求中包含 metadata=1 參數：

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?
    metadata=1&access_token=ACCESS-TOKEN"

所產生的 JSON 回應會包含 metadata 屬性，當中列出指定節點的所有獲支援欄位：

{
  "name": "Jane Smith",
  "metadata": {
    "fields": [
      {
        "name": "id",
        "description": "The app user's App-Scoped User ID. This ID is unique to the app and cannot be used by other apps.",
        "type": "numeric string"
      },
      {
        "name": "age_range",
        "description": "The age segment for this person expressed as a minimum and maximum age. For example, more than 18, less than 21.",
        "type": "agerange"
      },
      {
        "name": "birthday",
        "description": "The person's birthday.  This is a fixed format string, like `MM/DD/YYYY`.  However, people can control who can see the year they were born separately from the month and day so this string can be only the year (YYYY) or the month + day (MM/DD)",
        "type": "string"
      },
...

/me

/me 節點是一種特殊端點，可轉換為用戶或專頁（其存取憑證目前用於執行 API 呼叫）的物件編號。如果您曾有用戶存取憑證，您可以使用下列方法，檢索用戶的名稱和帳號：

curl -i -X GET \
  "https://graph.facebook.com/me?access_token=ACCESS-TOKEN"

關係連線

「邊緣」指兩個節點之間的聯繫。舉例來說，也許會有相片與用戶節點相連，而相片節點則可能會有回應與之相連。以下 cURL 範例會傳回一張清單，列出某人在 Facebook 上發佈的相片。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID/photos?access_token=ACCESS-TOKEN"

每個傳回的編號均代表一個相片節點，以及該相片何時被上載至 Facebook。

    {
  "data": [
    {
      "created_time": "2017-06-06T18:04:10+0000",
      "id": "1353272134728652"
    },
    {
      "created_time": "2017-06-06T18:01:13+0000",
      "id": "1353269908062208"
    }
  ],
}

欄位

欄位是節點屬性。當您查詢節點或邊緣，系統預設會傳回一組欄位，如上方範例所示。但您也可以使用 fields 參數並列出各個欄位，以指定您要傳回的欄位。這樣就能覆寫預設設定，使系統只傳回您指定的欄位及物件編號，後者為必定傳回的資料。

以下 cURL 要求包括 fields 參數，以及用戶姓名、電郵和個人資料相片。

curl -i -X GET \
  "https://graph.facebook.com/USER-ID?fields=id,name,email,picture&access_token=ACCESS-TOKEN"

傳回的數據

{
  "id": "USER-ID",
  "name": "EXAMPLE NAME",
  "email": "EXAMPLE@EMAIL.COM",
  "picture": {
    "data": {
      "height": 50,
      "is_silhouette": false,
      "url": "URL-FOR-USER-PROFILE-PICTURE",
      "width": 50
    }
  }
}

複雜參數

大多數參數類型均是直接了當的原始輸出，例如 bool、string 和 int，但亦可在要求中指定 list 和 object 等類型。

在 JSON 語法中可指定 list 類型，例如：["firstitem", "seconditem", "thirditem"]

在 JSON 語法中亦可指定 object 類型，例如：{"firstkey": "firstvalue", "secondKey": 123}

發佈、更新與刪除

瀏覽我們的 Facebook 分享指南，了解如何發佈至用戶的 Facebook，或是瀏覽我們的專頁 API 文件，了解如何發佈至專頁的 Facebook 動態消息。

部分節點可讓您透過 POST 操作來更新欄位。例如，您可以更新您的 email 欄位，如下所示：

curl -i -X POST \
  "https://graph.facebook.com/USER-ID?email=YOURNEW@EMAILADDRESS.COM&access_token=ACCESS-TOKEN"

先寫後讀

若要建立並更新端點，Graph API 可立即讀取成功發佈或更新的物件，並傳回相應讀取端點所支援的欄位。

根據預設，會傳回所建立或更新之物件的編號。如要在回應中包含更多資訊，請在要求中加入 fields 參數，並列出需要傳回的欄位。舉例來說，若要將訊息「你好」發佈至專頁的動態中，您可以執行以下要求：

curl -i - X POST "https://graph.facebook.com/PAGE-ID/feed?message=Hello&
  fields=created_time,from,id,message&access_token=ACCESS-TOKEN"

此舉會以 JSON 格式回應傳回指定欄位，詳情如下：

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "My Facebook Page",
    "id": "PAGE-ID"
  },
  "id": "POST_ID",
  "message": "Hello",
}

請參閱每個端點的參考文件，了解其是否支援先寫後讀以及有哪些可用的欄位。

錯誤

如果因某些原因（例如要求不存在的欄位）令讀取失敗，Graph API 會以標準錯誤回應作出回覆。請瀏覽我們的處理錯誤指南，了解更多資訊。

您通常可以在物件編號上執行 DELETE 操作來刪除節點，例如專頁或相片節點：

curl -i -X DELETE \
  "https://graph.facebook.com/PHOTO-ID?access_token=ACCESSS-TOKEN"

一般來說，您只能刪除自己建立的節點，但您也可以參閱每個節點的參考指南，以了解刪除操作的具體條件。

Webhooks

透過訂閱 Webhooks，您可以接收有關節點變更或與節點互動的通知。請參閱 Webhooks。

版本

Graph API 設有多個版本，每季推出。您可透過在呼叫中於要求路徑開頭加上「v」和版本編號來指定版本。例如，這是向 4.0 版執行的呼叫：

curl -i -X GET \
  "https://graph.facebook.com/v4.0/USER-ID/photos
    ?access_token=ACCESS-TOKEN"

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

您可以在我們的版本指南中進一步了解有關不同版本的相關資訊，並在 Graph API 變更記錄了解所有可用的版本。

Facebook API、SDK 和平台

使用 Facebook 的不同 API、SDK 和平台連接介面，並跨平台開發內容。

後續步驟

開始使用 Graph API – 使用 Graph 測試工具來探索 Facebook 社交關係圖並執行一些要求來獲取數據。