總覽

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

圖形 API 是以「社交關係圖」的概念命名，代表 Facebook 上的資訊，其中包括節點、關係連線和欄位。一般而言，節點是用於取得特定物件的資料、關係連線是用於取得單一物件上的物件集合，而欄位則是用於取得單一物件或集合中各個物件的資料。在整個文件中，我們將節點和關係連線都視為「端點」。例如，「將 GET 要求傳送至用戶端點」。

HTTP

所有資料傳輸皆符合 HTTP/1.1 通訊協定，且所有端點都會要求使用 HTTPS。圖形 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"

我們已在 facebook.com 啟用 includeSubdomains HSTS 指令，但這應該不會對您的圖形 API 呼叫產生負面影響。

主機網址

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

存取權杖

存取權杖可允許應用程式存取圖形 API。幾乎所有圖形 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 類型。

list 類型會以 JSON 語法指定，例如：["firstitem", "seconditem", "thirditem"]

object 類型也會以 JSON 語法指定，例如：{"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"

寫入後讀取

對於建立和更新端點，圖形 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",
}

請參閱各端點的參考文件，以瞭解是否支援寫入後讀取功能，以及可用的欄位。

錯誤

如果出於任何原因而讀取失敗（例如，要求不存在的欄位），圖形 API 將以標準錯誤回應來回應。如需詳細資訊，請瀏覽處理錯誤指南。

若要刪除節點（例如貼文或相片節點），通常可針對物件編號執行 DELETE 作業來完成：

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

您通常只能刪除自己所建立的節點，但請查閱各節點的參考指南，以瞭解刪除作業的要求。

Webhooks

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

版本

圖形 API 有多個版本，每季發佈一次。您可以在呼叫中，將「v」和版本編號加入到要求路徑的開頭來指定版本。例如，以下是向 4.0 版發出的呼叫：

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

若您未包含版本編號，系統將預設為可用的最舊版本，因此建議在要求中包含版本編號。

您可以在版本指南中深入瞭解版本，並在圖形 API 變更紀錄中瞭解所有可用的版本。

Facebook API、SDK 和平台

使用 Facebook 的各種 API、SDK 和平台，連結介面並跨平台開發。

後續步驟

圖形 API 入門 – 讓我們使用圖形測試工具來探索 Facebook 社交關係圖，並執行一些要求來取得資料。