使用圖形 API

圖形 API 總覽已大致介紹圖形 API 的專用術語和結構。本文將詳述有關可透過圖形 API 執行的各種作業詳細資料。

HTTP/1.1

所有資料傳輸皆符合 HTTP/1.1 通訊協定,且所有節點都會要求使用 HTTPS。facebook.com 已啟用 includeSubdomains HSTS 指示詞,但這不應對圖形 API 呼叫造成任何負面影響。

主機網址

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

存取權杖

存取權杖可允許應用程式存取圖形 API。存取權杖通常有兩個作用:

  • 允許應用程式無需用戶密碼即可存取用戶資訊,以及
  • 允許我們識別應用程式、應用程式用戶,以及用戶授權應用程式存取的資料類型。

所有的圖形 API 端點都需要某種存取權杖,所以每次存取端點時,要求中都必須包含存取權杖。

權杖的運作方式

存取權杖符合 OAuth 2.0 通訊協定。OAuth 2.0 可允許用戶或粉絲專頁等實體將權限授予權杖。這通常是透過網路介面完成。授權之後,應用程式便可使用這些權杖來存取特定資訊。

例如,以下應用程式要求用戶授予權限,以便存取用戶的相片、影片和電子郵件地址:

如您所見,此為 Facebook 介面。該用戶剛使用此介面登入帳號,以便我們能夠驗證用戶。如果該用戶持續進行,我們將會把舊權杖(應用程式權杖)交換為新權杖(用戶權杖)。然後,應用程式便可使用新的用戶權杖發出圖形 API 要求,但只可存取該特定用戶的相片、影片和電子郵件地址。

這是存取權杖很重要的特性。應用程式編號和用戶編號皆編碼在權杖內(包括其他項目),我們會使用這些編號來追蹤用戶允許應用程式存取的資料。例如,如果在用戶授予權限後檢查權杖,將會顯示以下資訊:

因為權杖會授予存取用戶資料的權限,且可供任何人使用,所以權杖極有價值,在查詢中使用權杖時請務必小心謹慎。使用「Facebook 登入」來處理權杖是最簡單的方式。

Facebook 登入

OAuth 2.0 牽涉到許多重新導向、登入提示和權杖交換,為了讓您在作業上更為輕鬆,我們打造了 Facebook 登入產品。「Facebook 登入」具備所有 SDK 皆可輕鬆使用的函數和方法,比起建立您自己的存取權杖解決方案更加簡單。

如需深入瞭解存取權杖和 Facebook 登入,或瞭解如何建立您自己的解決方案,請參閱 Facebook 登入文件

讀取

節點

讀取作業幾乎總是從節點開始。節點是具有專屬編號的個別物件。例如,假設有許多粉絲專頁節點物件且各有唯一編號,而可口可樂粉絲專頁是唯一編號為 820882001277849 的節點。若要讀取任何節點,您需要查詢特定物件的編號。所以,若要讀取可口可樂粉絲專頁節點,您應查詢其編號:

GET https://graph.facebook.com/820882001277849

依照預設,這個要求會以 JSON 的格式傳回以下欄位(節點屬性):

{
  "name": "Coca-Cola",
  "id": "820882001277849"
}

關係連線

節點有關係連線,通常可傳回與節點連結的其他節點集合。若要讀取關係連線,您必須在路徑中同時包含節點編號和關係連線名稱。例如,/page 節點有 /feed 關係連線,可傳回粉絲專頁的所有貼文節點。以下說明如何使用此關係連線來取得可口可樂粉絲專頁上的所有貼文:

GET https://graph.facebook.com/820882001277849/feed

JSON 格式的回應會類似以下所示:

{
  "data": [
    {
      "created_time": "2017-12-08T01:08:57+0000",
      "message": "Love this puzzle. One of my four coke puzzles",
      "id": "820882001277849_1805191182846921"
    },
    {
      "created_time": "2017-12-07T20:06:14+0000",
      "message": "You need to add grape as a flavor for Coke in your freestyle machines.",
      "id": "820882001277849_1804966026202770"
    },
    {
      "created_time": "2017-12-07T01:29:12+0000",
      "message": "Plz play the old commercial’s with the polar bears. Would be nice to see them this holiday",
      "id": "820882001277849_1804168469615859"
    }
  ]
}

請注意,回應中包含的不只是集合中貼文節點的編號,還有 created_timemessage 欄位。這是很常見的情況。大部分的關係連線會預設包含一或多個欄位。

欄位

欄位為節點屬性。如上例所示,查詢節點時,會傳回一組預設欄位。不過,您可使用 fields 參數並列出各個欄位,以指定想要傳回的欄位。這樣的方式會覆寫預設欄位,而僅傳回指定的欄位,以及一律會傳回的物件編號。

例如,粉絲專頁節點參考資料中列出讀取粉絲專頁節點時,可要求的欄位。若要取得可口可樂粉絲專頁的 aboutfan_countwebsite 欄位,方式如下:

GET https://graph.facebook.com/820882001277849
    ?fields=about,fan_count,website

這樣會傳回以下回應:

{
  "about": "Welcome to the happiest Facebook page on, um, Facebook.",
  "fan_count": 106714402,
  "website": "http://coca-cola.com",
  "id": "820882001277849"
}

關係連線通常會傳回物件集合,也會傳回集合中各物件的欄位。假設您使用 /photos 關係連線來取得可口可樂粉絲專頁的所有相片節點:

GET https://graph.facebook.com/820882001277849/photos

這樣會產生類似以下所示的回應:

{
  "data": [
    {
      "created_time": "2016-08-23T13:12:10+0000",
      "id": "1308573619175349"
    },
    {
      "created_time": "2016-08-05T22:34:19+0000",
      "id": "1294456907253687"
    },
    {
      "created_time": "2016-04-29T16:17:02+0000",
      "id": "1228552183844160"
    }
  ]
}

如您所見,依照預設,/photos 關係連線會傳回相片節點編號的集合,以及各相片的 created_time 屬性。如同節點一樣,您也可針對集合中傳回的各物件使用 fields 參數,指定想要傳回的欄位。

假設對於 /photos 關係連線傳回的各相片節點,您想要取得 heightwidthlink(網址)欄位:

GET https://graph.facebook.com/820882001277849/photos
      ?fields=height,width,link

回應會類似以下所示:

{
  "data": [
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1308573619175349/?type=3",
      "id": "1308573619175349"
    },
    {
      "height": 720,
      "width": 720,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1294456907253687/?type=3",
      "id": "1294456907253687"
    },
    {
      "height": 180,
      "width": 180,
      "link": "https://www.facebook.com/CocaColaUnitedStates/photos/a.820887414610641.1073741825.820882001277849/1228552183844160/?type=3",
      "id": "1228552183844160"
    }
  ]
}

請注意,您也可使用 fields 參數來指定關係連線,這適用於使用欄位擴展時。

欄位擴展

如果您恰巧在圖形 API 測試工具中測試上述的 GET /page/photos 查詢,大概注意到要求傳回的不只三個物件,並且將結果分頁處理。這對大部分的關係連線是很常見的情況。我們很快會說明瀏覽結果功能,但在這之前,我們會先帶您瞭解欄位擴展功能,此功能不只可讓您執行巢狀化的查詢,還可限制排序結果。

限制結果

限制可讓您控制每組分頁結果中所傳回的物件數。若要限制結果,請將 .limit() 引數新增至任何欄位或關係連線。

例如,針對可口可樂粉絲專頁的 /feed 關係連線執行 GET 要求時,可能會傳回數百篇貼文。您可透過以下方式來限制每頁結果傳回的貼文數:

GET https://graph.facebook.com/820882001277849
    ?fields=feed.limit(3)

這樣會傳回可口可樂粉絲專頁上的所有貼文,但將每頁結果中的物件數限制為三個。請注意,您不是在路徑網址中指定動態關係連線(/page/feed),而是在 fields 參數中指定(?fields=feed),才能附加 .limit(3) 引數。

查詢結果如下:

{
  "feed": {
    "data": [
      {
        "created_time": "2017-12-12T01:24:21+0000",
        "message": "This picture of my grandson with Santa screams Coca Cola",
        "id": "820882001277849_1809387339093972"
      },
      {
        "created_time": "2017-12-11T23:40:17+0000",
        "message": ":)",
        "id": "820882001277849_1809316002434439"
      },
      {
        "created_time": "2017-12-11T23:31:38+0000",
        "message": "Thought you might enjoy this.  My horse loves Coke!",
        "id": "820882001277849_1809310929101613"
      }
    ],
    "paging": {
      "cursors": {
        "before": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5UTRNakE0T0RJd01ERXlOemM0TkRrNkxUVXdPRE16TXpVM01EQXpNVFUwTkRRME5Ua1BER0ZA3YVY5emRHOXllVjlwWkE4ZA09ESXdPRGd5TURBeE1qYzNPRFE1WHpFNE1Ea3pPRGN6TXprd09UTTVOeklQQkhScGJXVUdXaTh2eFFFPQZDZD",
        "after": "Q2c4U1pXNTBYM0YxWlhKNVgzTjBiM0o1WDJsa0R5TTRNakE0T0RJd01ERXlOemM0TkRrNk1UTTJORE01T0RVNU1UZAzVPRGMyTnpFNE1BOE1ZAWEJwWDNOMGIzSjVYMmxrRHlBNE1qQTRPREl3TURFeU56YzRORGxmTVRnd09USXdOamsxTlRjM09EWTNOdzhFZAEdsdFpRWmFMdk9HQVE9PQZDZD"
      },
      "next": "https://graph.facebook.com/820882001277849/feed?access_token=valid_token_goes_here"
    }
  },
  "id": "820882001277849"
}

如您所見,此分頁結果頁面僅顯示三個物件,但回應中包含 next 欄位和網址,可用於擷取下一頁的結果。

排序結果

您可依物件建立時間的順序排列結果。若要這樣做,請針對欄位或關係連線使用 .order() 引數,並指定以下其中一個值:

  • chronological — 依最早建立的物件最先顯示的順序排列結果。
  • reverse_chronological — 依最晚建立的物件最先顯示的順序排列結果。

例如,若要取得可口可樂粉絲專頁上其中一篇影片貼文(1809938745705498)的所有留言、依時間先後順序排列結果(越舊的越先顯示),並將每分頁結果的物件數限制為三個:

GET https://graph.facebook.com/1809938745705498
    ?fields=comments.order(chronological).limit(3)

請再次注意,為了針對關係連線使用引數,您必須在 fields 參數中指定關係連線。如您所見,您可針對單一欄位或關係連線合併使用 .limit().order() 引數。

結果如下:

{
  "comments": {
    "data": [
      {
        "created_time": "2017-12-12T14:12:20+0000",
        "message": ":) :) :)",
        "id": "1809938745705498_1809939942372045"
      },
      {
        "created_time": "2017-12-12T14:14:03+0000",
        "message": "seasons greetings!",
        "id": "1809938745705498_1809941802371859"
      },
      {
        "created_time": "2017-12-12T14:14:11+0000",
        "message": "My bestie <3",
        "id": "1809938745705498_1809941879038518"
      }
    ],
    "paging": {
      "cursors": {
        "before": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd3T1Rrek9UZAzROVGN3TlRNNE5Eb3hOVEV6TURnM09UTTIZD",
        "after": "WTI5dGJXVnVkRjlqZAFhKemIzSTZANVGd4TURBd09UazROVFk1T0RNM05Eb3hOVEV6TURreU5qQXoZD"
      },
      "next": "https://graph.facebook.com/1809938745705498/comments?access_token=valid_token_goes_here"
    }
  },
  "id": "1809938745705498"
}

發佈

大部分的關係連線可允許您將物件發佈至節點上的集合。方式為針對節點的關係連線發出 POST 要求。例如,若要對相片發佈留言,可利用相片節點的 /comments 關係連線:

POST https://graph.facebook.com
  /1809938745705498
    /comments
      ?message=Awesome!

成功時,大部分的關係連線會傳回您剛發佈物件的編號,這個編號通常是由發佈所針對物件的編號及新編號組合而成的字串:

{
  "id": "1809938745705498_1810399758992730"
}

發佈通常需要額外權限,請參閱各關係連線的參考文件以瞭解所需權限。

用於發佈物件的存取權杖可能會影響物件的外觀。 使用粉絲專頁存取權杖時,物件看起來像是由粉絲專頁所發佈;而使用用戶存取權杖時,會使得物件看起來是由用戶所發佈。

許多關係連線還支援進階功能,例如:寫入後讀取(可讓您立即讀取新發佈的物件)和批次發佈(可讓您鏈結多個發佈作業)。

更新

您可透過 POST 要求,針對現有節點執行更新作業。例如,若要更新現有留言的 message 欄位,方式如下:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?message=Happy%20Holidays!

成功時,該節點會傳回 success 欄位且其值為 true

{
  "success": true
}

如同發佈作業,更新作業也需要額外權限,這些權限會列於各節點的參考文件中。就像大部分關係連線一樣,許多節點也支援寫入後讀取功能。

刪除

您通常可透過 DELETE 作業來刪除節點:

DELETE https://graph.facebook.com
  /1809938745705498_1810399758992730

成功時,該節點會傳回 success 欄位且其值為 true

{
  "success": true
}

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

若用戶端並未支援所有的 HTTP 方法,應變方法為向該節點傳送 POST 要求,同時包含 method=delete 參數和值來覆寫 HTTP 方法:

POST https://graph.facebook.com
  /1809938745705498_1810399758992730
    ?method=delete

瀏覽分頁的結果

對節點或關係連線發出 API 要求時,您通常不會在單一回應中就收到這個要求的所有結果。這是因為某些回應可能包含數千個物件,所以系統會依預設將大多數回應進行分頁處理。

游標型分頁

游標型分頁是最有效的分頁方法,應盡可能加以運用。游標關連至一個隨機字元字串,用於標示資料清單中的特定項目。除非將該項目刪除,否則游標會一律指向清單的相同部分;但若將項目移除後,游標便會失效。因此,您的應用程式不應該儲存游標,假設這些游標日後都將仍然有效。

讀取支援游標分頁的關係連線時,您將看到下列 JSON 回應:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

游標分頁的關係連線支援以下參數:

  • before:這是指向已傳回資料頁面開頭的游標。
  • after:這是指向已傳回資料頁面結尾的游標。
  • limit:這是可能傳回的物件數量上限。由於篩選功能的緣故,查詢時傳回的物件數量可能低於 limit 的值。請不要根據結果數量少於 limit 值的情形,而標示查詢已來到資料清單的結尾處,請改為使用未包含 next 的方式,如下所述。例如,如果您將 limit 的值設為 10,而系統傳回 9 個結果,可能仍有更多資料可使用,但因為隱私篩選功能,而有一項結果遭系統移除。 基於效能因素,某些關係連線的 limit 值同樣具有上限。無論什麼情況,API 都會傳回正確的分頁連結。
  • next:將傳回下一頁資料的圖形 API 端點。如果未包含這個修飾詞,代表傳回資料為最後一頁。由於分頁作業配合能見度和隱私設定的方式,有可能某頁為空白,但卻包含「下一頁」的分頁連結。當「下一頁」連結不再出現時,請即停止詢問分頁。
  • previous:將傳回上一頁資料的圖形 API 端點。如果未包含這個修飾詞,代表傳回資料為第一頁。

請勿儲存游標。如果新增或刪除項目,游標很快就會變成無效。

時間型分頁

時間型分頁用於使用 UNIX 時間戳記瀏覽結果資料,這些時間戳記指向資料清單中的特定時間。

使用支援時間型分頁的端點時,您將看到下列 JSON 回應:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

時間型分頁的關係連線支援下列參數:

  • until:UNIX 時間戳記或 strtotime 資料值,可指向時間型資料範圍的結尾。
  • since:UNIX 時間戳記或 strtotime 資料值,可指向時間型資料範圍的開頭。
  • limit:這是可能傳回的物件數量上限。由於篩選功能的緣故,查詢時傳回的物件數量可能低於 limit 的值。請不要根據結果數量少於 limit 值的情形,而標示查詢已來到資料清單的結尾處,請改為使用未包含 next 的方式,如下所述。例如,如果您將 limit 的值設為 10,而系統傳回 9 個結果,可能仍有更多資料可使用,但因為隱私篩選功能,而有一項結果遭系統移除。 基於效能因素,某些關係連線的 limit 值同樣具有上限。無論什麼情況,API 都會傳回正確的分頁連結。
  • next:將傳回下一頁資料的圖形 API 端點。
  • previous:將傳回上一頁資料的圖形 API 端點。

為了結果的一致性,請同時指定 sinceuntil 參數。此外,建議時間差最多為 6 個月。

位移型分頁

當您不在乎時間順序,而只想要傳回特定數目的物件時,可使用位移分頁。僅當關係連線不支援游標或時間型分頁時,才應該使用位移分頁。

位移型分頁的關係連線支援下列參數:

  • offset:依指定數目,將每一頁開頭位移。
  • limit:這是可能傳回的物件數量上限。由於篩選功能的緣故,查詢時傳回的物件數量可能低於 limit 的值。請不要根據結果數量少於 limit 值的情形,而標示查詢已來到資料清單的結尾處,請改為使用未包含 next 的方式,如下所述。例如,如果您將 limit 的值設為 10,而系統傳回 9 個結果,可能仍有更多資料可使用,但因為隱私篩選功能,而有一項結果遭系統移除。 基於效能因素,某些關係連線的 limit 值同樣具有上限。無論什麼情況,API 都會傳回正確的分頁連結。
  • next:將傳回下一頁資料的圖形 API 端點。如果未包含這個修飾詞,代表傳回資料為最後一頁。由於分頁作業配合能見度和隱私設定的方式,有可能某頁為空白,但卻包含「下一頁」的分頁連結。當「下一頁」連結不再出現時,請即停止詢問分頁。
  • previous:將傳回上一頁資料的圖形 API 端點。如果未包含這個修飾詞,代表傳回資料為第一頁。

請注意,如果將新的物件加入分頁中的項目清單,每個位移型分頁的內容都會變更。

並非所有 API 呼叫都支援位移型分頁。若要取得一致的結果,建議您使用在回應中傳回的上一頁/下一頁連結來進行分頁。