圖形 API 參考資料

總覽

適用於 Workplace 的圖形 API 是一種將資料傳入和傳出 Workplace 的程序化方式。此為低階 HTTP 型 API，可用來查詢 Workplace 圖形中物件的相關資料。

圖形 API 以圖形資料模型的概念命名，其中物件由節點表示並以關係連線連接。從 API 層級來看，其與應用程式如何存取 Workplace 上的資訊有關。適用於 Workplace 的圖形 API 允許為適用於 Facebook 的圖形 API 建立功能子集。此功能僅限於與 Workplace 社群的互動，且在某些情況下可能會有所不同，以獲得更好的效能或可用性。

Workplace 圖形 API 物件

可以使用自訂整合或第三方應用程式存取權杖透過 Workplace 圖形 API 存取下列節點。

社群

Workplace 社群。Workplace 圖形 API 呼叫的根群組。

社團

Workplace 社團。

貼文

在社團中或成員個人檔案上貼文。

成員

特定 Workplace 用戶的帳號。此節點亦用於檢視及編輯該用戶所收發的訊息。

技能

新增至成員個人檔案中的技能。

活動

Workplace 社群或社團的活動。

類別

知識資料庫中用於儲存重要公司內容的類別。

用戶群組

使用條件或名單來定義的用戶集合。

遭檢舉的內容

Workplace 上遭檢舉供管理員審查的內容。

輪班

Workplace 上計時員工的輪班表資料。

問卷調查

在 Workplace 上建立的問卷調查。

資料匯出

從 Workplace 批量匯出資料的資料匯出工作。

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

使用圖形 API

圖形 API 物件

圖形 API 是 Workplace 資訊的表示，由以下部分組成：

• 節點 - 物件，例如用戶、相片、貼文、留言等
• 關係連線 -「元件」之間的連線，例如貼文的檔案，或相片的留言等
• 欄位 - 關於物件的中繼資料，例如用戶的姓名，或社團的隱私

Workplace 圖形中的每個項目都以專屬編號表示。社團、成員、貼文，甚至留言都有自己的編號，可用來從圖形 API 擷取相關資訊。

管理社群

每個 Workplace 社群都與其他社群分開，因此您只能使用圖形 API 存取您自己社群內的內容，以及已新增社群成員的跨公司社團中的內容。

為了供圖形 API 存取之用，會將社群視為社團。您可以將社群視為一個根社團，底下所有社團皆作為子社團新增。若要在圖形 API 上擷取社群的資訊，您需要取得您的社群編號，該編號是透過使用有效的應用程式存取權杖對 graph.facebook.com/community 提交 HTTP GET 要求，以程式化方式從圖形 API 擷取。

圖形 API 版本控制

適用於 Workplace 的圖形 API 是建立在 Facebook 平台的圖形 API 之上。亦即它會繼承 Facebook 上所使用的相同 API 版本控制行為。

圖形 API 版本大約每三個月發佈一次，所有 Workplace 和 Facebook API 的變更都發佈在圖形 API 變更紀錄中。

對圖形 API 提交 API 呼叫時，您可在 API 路徑中指定版本，方法如下：

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

但是，有一些關於可用版本的限制：

• 發佈新版本時，它會成為目前的 API 版本，且保證在發佈後的兩年內都能運作。
• 建立應用程式時，它預設為建立時的目前 API 版本，且其將成為該應用程式可用的最低 API 版本。
• 應用程式在發出 API 呼叫時可以自由指定任何 API 版本，但不能呼叫已廢棄的 API 版本，或呼叫低於應用程式的最低 API 版本。
• 未知版本的 API 呼叫將預設為該應用程式的最低 API 版本。

建立新的自訂整合時，其最低可用 API 版本將是建立時的最新 API 版本。此最低版本會影響圖形 API 呼叫和 Webhook 訂閱。

查看圖形 API 版本

如果您不確定使用的是哪個版本，有一些方法可以檢查。若要檢查哪個版本的圖形 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 版本

如果透過自訂整合彈出式對話方塊進行訂閱，或透過訂閱圖形 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"
              },
      ...
    

使用存取權杖

取得應用程式存取權杖

若要為您的社群發出任何圖形 API 呼叫，您需要建立一個應用程式並擷取存取權杖。這涉及建立新的自訂整合，接著為其授予您要建置的功能所需的權限。

若要了解有關建立應用程式和權限模型的詳細資訊，請參閱權限指南。

取得成員存取權杖

應用程式存取權杖允許應用程式存取社群範圍的物件並與之互動，而成員存取權限允許服務代表特定帳號發出呼叫。

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

此功能需要呼叫應用程式的假冒權限。