Graph API 參考資料

概覽

Workplace 的 Graph API 是將資料匯入和匯出 Workplace 的程序化方式。這是一個以 HTTP 為基礎的低級別 API，可以用於查詢 Workplace 圖表物件的相關數據。

Graph API 是以圖表數據模型的概念命名，當中的物件由節點代表，並沿關係連線連接。在 API 級別，這是應用程式存取 Workplace 資訊的方式。Workplace 的 Graph API 允許為 Facebook 的 Graph API 建立功能子集。此功能僅限於與 Workplace 社群之間的互動；在某些情況下，功能或會有所差異，以提高成效或可用性。

Workplace Graph API 物件

您可使用自訂整合程序或第三方應用程式的存取憑證，透過 Workplace Graph API 存取以下節點。

社群

此為 Workplace 社群，Workplace Graph API 呼叫的根群組。

成員

此為特定 Workplace 用戶的帳戶。此節點亦用於查看及編輯此用戶所收發的訊息。

資料匯出

從 Workplace 大量匯出資料的資料匯出作業。

若要查看結合 Graph API 呼叫以解決特定問題的範例，請查看應用程式範例清單。

使用 Graph API

Graph API 物件

Graph API 代表由以下部分組成的 Workplace 資訊：

節點：用戶、相片、專頁、回應等物件
關係連線：「元件」之間的連線，例如帖子的檔案或相片的回應
欄位：關於元數據的中繼資料，例如用戶的姓名，或群組的私隱設定

Workplace 圖表的每個項目都由一個不重複編號表示。群組、成員、帖子甚至留言都有自己的編號，可用於從 Graph API 檢索相關資訊。

管理您的社群

每個 Workplace 社群都獨立於其他社群，因此您只能使用 Graph API 存取自己社群的內容，以及已加入社群成員的跨公司群組內容。

在 Graph API 存取情況下，您的社群將被視為群組。您可以將您的社群當作根群組，以子物件的形式將所有群組加入這個社群。若要在 Graph API 上檢索您社群的相關資訊，您需要使用自己的社群編號。您可透過使用有效的應用程式存取憑證來向 graph.facebook.com/community 提出 HTTP GET 要求，從而以程式化方式從 Graph API 檢索社群編號。

Graph API 版本管理

Workplace Graph API 建立於 Facebook 開放平台的 Graph API 之上。這亦表示這個 API 會繼承 Facebook 上使用的相同 API 版本管理行為。

Graph API 版本大約每 3 個月會發佈 1 次，所有 Workplace 和 Facebook API 的變更都會在 Graph API 變更記錄中發佈。

在向 Graph API 執行 API 呼叫時，您可以在 API 路徑中指定版本，如下所示：

      https://graph.facebook.com/v2.11/community/groups

但是，可用版本有一些限制條件：

發佈新版本時，它會成為目前的 API 版本，且保證在發佈後的兩年內都能運作。
建立應用程式時，它預設為建立時的目前 API 版本，而此將成為該應用程式可用的最低 API 版本。
應用程式可在執行 API 呼叫時隨意指定任何 API 版本，但不能對已停用的 API 版本或低於應用程式最低 API 版本的版本執行呼叫。
未知版本的 API 呼叫將預設為該應用程式的最低 API 版本。

在建立新的自訂整合時，其可用的最低 API 版本將為建立時的目前 API 版本。此最低版本將影響 Graph API 呼叫和 Webhook 訂閱。

平台版本管理 Graph API 變更記錄

檢查 Graph API 版本

如果您不確定您所使用的版本，則可使用一些方法來檢查。若要檢查哪個版本的 Graph API 可與您的應用程式配搭使用，您可將 debug 參數加入自己的 API 呼叫。

      https://graph.facebook.com/community?debug=all

這將傳回額外的除錯資訊並確認所使用的版本。

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

若您嘗試使用的版本低於自家應用程式的最低 API 版本，debug 訊息將通知您。

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

檢查 Webhook 版本

若透過自訂整合彈出式對話框進行訂閱，或透過訂閱 Graph API 端點 /app/subscriptions 訂閱指定的 API 版本，則 Webhook 訂閱會使用最低 API 版本。

您可以使用訂閱端點，以確認每個 Webhook 欄位和主題所套用的 Webhook 版本。此端點需要應用程式存取憑證。

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...

根據 Webhook 訂閱的啟用方式，單一 Webhook 物件內不同的欄位可能會使用不一樣的版本編號傳回承載。

如果您的裝載格式並非您想要的格式，請再次檢查版本編號，並使用較新的版本重新訂閱（若需要）。

使用存取憑證

獲取應用程式存取憑證

若要為您的社群執行任何 Graph API 呼叫，您需要建立應用程式和檢索存取憑證。這涉及建立新的自訂整合工具，然後向其授予您想開發的功能之所需權限。

若要進一步了解建立應用程式和權限模型，請參閱權限指南。

取得成員存取憑證

應用程式存取憑證允許應用程式存取社群範圍的物件並與之互動，成員存取憑證則允許服務代表特定帳戶執行呼叫。

您可透過使用管理員存取憑證並要求額外的 impersonate_token 欄位，向特定成員的 /member_id 端點提出 GET 要求，以此擷取成員存取憑證。

此功能需要執行呼叫的應用程式之冒名權限。

冒名為已停用的權限，請勿使用此權限開發新功能。此權限將無法再加入自訂整合工具。

您只能為已認領帳戶擷取冒名憑證。