Tài liệu tham khảo về API Đồ thị

Tổng quan

API Đồ thị dành cho Workplace là cách để đưa dữ liệu vào và lấy dữ liệu ra khỏi Workplace theo lập trình. API Đồ thị là API dựa trên HTTP cấp thấp mà bạn có thể dùng để truy vấn dữ liệu về các đối tượng trong một đồ thị Workplace.

API Đồ thị được đặt tên theo ý tưởng về mô hình dữ liệu đồ thị, trong đó các đối tượng được biểu thị bằng các nút và được nối dọc theo các cạnh. Ở cấp độ API, đây là cách các ứng dụng truy cập vào thông tin trên Workplace. API Đồ thị dành cho Workplace cho phép một nhóm nhỏ chức năng của API Đồ thị dành cho Facebook. Chức năng này chỉ giới hạn ở các hoạt động tương tác với cộng đồng Workplace và có thể khác nhau trong một số trường hợp nhằm mang lại hiệu quả hoặc khả năng sử dụng cao hơn.

Các đối tượng trên API Đồ thị dành cho Workplace

Sử dụng tiện ích tích hợp tùy chỉnh hoặc mã truy cập ứng dụng bên thứ ba để truy cập các nút sau thông qua API Đồ thị dành cho Workplace.

Cộng đồng

Cộng đồng Workplace. Nhóm gốc cho các lệnh gọi API Đồ thị dành cho Workplace của bạn.

Nhóm

Nhóm Workplace.

Bài viết

Một bài viết được đăng trong nhóm hoặc trên trang cá nhân của một thành viên.

Thành viên

Tài khoản cho một người dùng Workplace cụ thể. Nút này cũng được dùng để xem và chỉnh sửa tin nhắn mà người dùng này đã gửi và nhận.

Kỹ năng

Một kỹ năng được thêm vào trang cá nhân của thành viên.

Sự kiện

Một sự kiện trong Nhóm hoặc Cộng đồng Workplace.

Hạng mục

Một hạng mục trong Thư viện kiến thức để lưu trữ nội dung quan trọng của công ty.

Nhóm nhân viên

Một nhóm gồm những người được xác định theo tiêu chí hoặc danh sách.

Nội dung bị báo cáo

Nội dung trên Workplace đã bị báo cáo để quản trị viên xem xét.

Ca làm việc

Dữ liệu về lịch ca làm việc của nhân viên làm theo giờ trên Workplace.

Khảo sát

Khảo sát đã được tạo trên Workplace.

Xuất dữ liệu

Công việc xuất dữ liệu để xuất dữ liệu hàng loạt từ Workplace.

Để xem ví dụ về cách kết hợp các lệnh gọi API Đồ thị để giải quyết những vấn đề cụ thể, hãy xem danh sách Ứng dụng mẫu.

Sử dụng API Đồ thị

Các đối tượng trên API Đồ thị

API Đồ thị trình bày thông tin trên Workplace, bao gồm:

• Nút - các đối tượng như Người dùng, Ảnh, Bài viết, Bình luận
• Cạnh - quan hệ kết nối giữa những "đối tượng" đó, chẳng hạn như file của Bài viết hoặc Bình luận của Ảnh
• Trường - siêu dữ liệu về các đối tượng, chẳng hạn như tên của người dùng hoặc quyền riêng tư của một Nhóm

Mọi mục trong đồ thị Workplace đều được biểu thị bằng ID riêng biệt. Nhóm, Thành viên, Bài viết và thậm chí là Bình luận đều có ID riêng. Bạn có thể dùng những ID này để truy xuất thông tin về các mục đó từ API Đồ thị.

Quản lý cộng đồng

Mỗi cộng đồng Workplace đều được tách biệt với các cộng đồng khác. Vì vậy, bạn chỉ có thể sử dụng API Đồ thị để truy cập vào nội dung trong cộng đồng của riêng mình, cũng như trong các nhóm đa công ty mà bạn thêm các thành viên trong cộng đồng của mình.

Để có quyền truy cập API Đồ thị, hãy xem Cộng đồng của bạn là một Nhóm. Bạn có thể xem cộng đồng của mình là một nhóm gốc, trong đó tất cả các nhóm của bạn đều được thêm làm nhóm con. Để truy xuất thông tin về cộng đồng của bạn trên API Đồ thị, bạn sẽ cần có ID cộng đồng. Bạn có thể truy xuất ID này theo lập trình từ API Đồ thị bằng cách gửi yêu cầu HTTP GET đến graph.facebook.com/community kèm mã truy cập ứng dụng hợp lệ.

Lập phiên bản API Đồ thị

API Đồ thị dành cho Workplace được xây dựng dựa trên nền tảng của API Đồ thị dành cho Facebook. Nghĩa là API Đồ thị này kế thừa hành vi lập phiên bản API tương tự như được sử dụng trên Facebook.

Các phiên bản API Đồ thị được phát hành khoảng 3 tháng một lần. Những thay đổi trên tất cả các API Workplace và API Facebook đều được đăng trong Nhật ký thay đổi API Đồ thị.

Khi thực hiện lệnh gọi API đến API Đồ thị, bạn có thể chỉ định một phiên bản trong đường dẫn API, như sau:

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

Tuy nhiên, có một số hạn chế đối với các phiên bản có sẵn:

• Khi một phiên bản mới được phát hành, phiên bản đó sẽ trở thành phiên bản API hiện tại và đảm bảo sẽ hoạt động trong 2 năm sau khi phát hành.
• Khi một ứng dụng được tạo, ứng dụng đó sẽ được đặt mặc định là phiên bản API hiện tại vào thời điểm tạo và phiên bản này sẽ trở thành phiên bản API tối thiểu có sẵn cho ứng dụng đó.
• Các ứng dụng có thể chỉ định bất kỳ phiên bản API nào khi thực hiện lệnh gọi API, nhưng sẽ không thể thực hiện lệnh gọi đến phiên bản API đã ngừng hoạt động hoặc đến các phiên bản thấp hơn phiên bản API tối thiểu của ứng dụng.
• Các lệnh gọi API không có phiên bản sẽ được đặt mặc định thành phiên bản API tối thiểu cho ứng dụng đó.

Khi tiện ích tích hợp tùy chỉnh mới được tạo, phiên bản API tối thiểu hiện có của tiện ích đó sẽ là phiên bản API hiện tại vào thời điểm tạo. Phiên bản tối thiểu này sẽ ảnh hưởng đến cả lệnh gọi API Đồ thị lẫn gói đăng ký Webhook.

Kiểm tra phiên bản API Đồ thị

Nếu bạn không biết chắc mình đang sử dụng phiên bản nào, có một số cách để kiểm tra điều này. Để kiểm tra phiên bản API Đồ thị nào có thể dùng với ứng dụng của bạn, bạn có thể thêm thông số debug vào lệnh gọi API.

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

Thao tác này sẽ trả về thông tin gỡ lỗi bổ sung để xác nhận phiên bản đang được sử dụng.

      {
         "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"
               }
            ]
         }
      }
    

Nếu bạn cố sử dụng một phiên bản thấp hơn phiên bản API tối thiểu cho ứng dụng của mình, thông báo debug sẽ báo cho bạn biết điều đó.

      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"
               }
            ]
         }
      }
    

Kiểm tra phiên bản Webhook

Các gói đăng ký Webhook sử dụng phiên bản API tối thiểu nếu việc đăng ký được thực hiện thông qua hộp thoại bật lên Tiện ích tích hợp tùy chỉnh. Nếu không, phiên bản API đã chỉ định sẽ là đăng ký được thực hiện thông qua điểm cuối đăng ký API Đồ thị có tên /app/subscriptions.

Bạn có thể sử dụng điểm cuối đăng ký này để xác nhận phiên bản webhook đã đăng ký cho từng chủ đề và trường webhook. Điểm cuối này yêu cầu một mã truy cập ứng dụng.

      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"
              },
      ...
    

Sử dụng mã truy cập

Lấy mã truy cập ứng dụng

Để thực hiện bất kỳ lệnh gọi API Đồ thị nào cho cộng đồng của bạn, bạn sẽ phải tạo một ứng dụng và truy xuất mã truy cập. Bước này liên quan đến việc tạo tiện ích tích hợp tùy chỉnh mới, sau đó cấp cho tiện ích đó các quyền cần thiết đối với chức năng mà bạn muốn xây dựng.

Để tìm hiểu thêm về cách tạo ứng dụng và mô hình cấp quyền, hãy xem phần hướng dẫn về Quyền.

Lấy mã truy cập thành viên

Trong khi mã truy cập ứng dụng cho phép một ứng dụng truy cập và tương tác với các đối tượng trong cộng đồng, mã truy cập thành viên lại cho phép một dịch vụ thực hiện lệnh gọi thay mặt một tài khoản cụ thể.

Bạn có thể tìm nạp mã truy cập thành viên bằng cách gửi yêu cầu GET đến điểm cuối /member_id cho một thành viên cụ thể, sử dụng mã truy cập quản trị viên và yêu cầu trường bổ sung impersonate_token.

Chức năng này yêu cầu quyền Mạo danh để ứng dụng thực hiện lệnh gọi.