Truy vấn Microsoft Graph bằng cách sử dụng REST

  • 3 phút

Microsoft Graph là một API web RESTful cho phép bạn truy cập các tài nguyên dịch vụ Microsoft Cloud. Sau khi bạn đăng ký ứng dụng của mình và nhận mã thông báo xác thực cho người dùng hoặc dịch vụ, bạn có thể đưa ra yêu cầu đối với API Microsoft Graph.

API Microsoft Graph xác định hầu hết các tài nguyên, phương pháp và liệt kê trong không gian tên OData, microsoft.graphtrong siêu dữ liệu Microsoft Graph. Một vài bộ API được xác định trong không gian tên con của chúng, chẳng hạn như API bản ghi cuộc gọi xác định các tài nguyên như callRecord trong microsoft.graph.callRecords.

Trừ khi được chỉ định rõ ràng trong chủ đề tương ứng, giả sử các loại, phương pháp và liệt kê là một phần của không microsoft.graph gian tên.

Gọi phương pháp REST API

Để đọc từ hoặc viết vào một tài nguyên như người dùng hoặc thư email, hãy xây dựng một yêu cầu trông giống như mẫu sau đây:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

Các cấu phần của yêu cầu bao gồm:

  • {HTTP method} - Phương thức HTTP được sử dụng trên yêu cầu cho Microsoft Graph.
  • {version} - Phiên bản API Microsoft Graph mà ứng dụng của bạn đang sử dụng.
  • {resource} - Tài nguyên trong Microsoft Graph mà bạn đang tham chiếu.
  • {query-parameters} - Tùy chọn truy vấn OData tùy chọn hoặc tham số phương pháp REST tùy chỉnh phản hồi.

Sau khi bạn thực hiện yêu cầu, phản hồi sẽ được trả về bao gồm:

  • Mã trạng thái - Mã trạng thái HTTP cho biết thành công hoặc thất bại.
  • Thông báo phản hồi - Dữ liệu mà bạn đã yêu cầu hoặc kết quả của thao tác. Thông báo phản hồi có thể trống đối với một số thao tác.
  • nextLink - Nếu yêu cầu của bạn trả về nhiều dữ liệu, bạn cần phải phân trang qua nó bằng cách sử dụng URL trả về trong @odata.nextLink.

Phương pháp HTTP

Microsoft Graph sử dụng phương pháp HTTP trên yêu cầu của bạn để xác định yêu cầu của bạn đang làm gì. API hỗ trợ các phương pháp sau.

Phương pháp Sự miêu tả
GET Đọc dữ liệu từ tài nguyên.
TRỤ Tạo tài nguyên mới hoặc thực hiện hành động.
VÁ Cập nhật tài nguyên với các giá trị mới.
ĐỂ Thay thế tài nguyên bằng tài nguyên mới.
XÓA Loại bỏ tài nguyên.
  • Đối với các phương pháp CRUD GET và DELETE, không yêu cầu nội dung nào được yêu cầu.
  • , POSTvà các PATCHphương pháp yêu PUT cầu nội dung yêu cầu được chỉ định trong định dạng JSON có chứa thông tin bổ sung. Chẳng hạn như các giá trị cho thuộc tính của tài nguyên.

Phiên bản

Microsoft Graph hiện hỗ trợ hai phiên bản: v1.0 và beta.

  • v1.0 bao gồm các API thường có sẵn. Sử dụng phiên bản v1.0 cho tất cả các ứng dụng sản xuất.
  • beta bao gồm các API hiện đang ở chế độ xem trước. Vì chúng tôi có thể giới thiệu những thay đổi mới nhất cho API beta của mình, chúng tôi khuyên bạn chỉ nên sử dụng phiên bản beta để kiểm tra các ứng dụng đang được phát triển; không sử dụng API beta trong các ứng dụng sản xuất của bạn.

Tài nguyên

Tài nguyên có thể là một thực thể hoặc loại phức tạp, thường được định nghĩa với các thuộc tính. Các thực thể khác với các loại phức tạp bằng cách luôn bao gồm một thuộc tính id .

URL của bạn bao gồm tài nguyên mà bạn đang tương tác trong yêu cầu, mechẳng hạn như , người dùng, nhóm, ổ đĩa và trang web. Thông thường, các tài nguyên cấp cao nhất cũng bao gồm các mối quan hệ mà bạn có thể sử dụng để truy nhập các tài nguyên khác, chẳng hạn me/messages như hoặc me/drive. Bạn cũng có thể tương tác với các tài nguyên bằng cách sử dụng phương pháp; ví dụ: để gửi email, hãy sử dụng me/sendMail.

Mỗi tài nguyên có thể yêu cầu các quyền khác nhau để truy nhập vào tài nguyên đó. Bạn thường cần có mức quyền cao hơn để tạo hoặc cập nhật tài nguyên thay vì đọc tài nguyên đó. Để biết chi tiết về các quyền bắt buộc, hãy xem chủ đề tham khảo phương pháp.

Tham số truy vấn

Tham số truy vấn có thể là tùy chọn truy vấn hệ thống OData hoặc các chuỗi khác mà phương pháp chấp nhận để tùy chỉnh phản hồi của nó.

Bạn có thể sử dụng các tùy chọn truy vấn hệ thống OData tùy chọn để bao gồm nhiều hoặc ít thuộc tính hơn so với phản hồi mặc định. Bạn có thể lọc phản hồi cho các mục khớp với truy vấn tùy chỉnh hoặc cung cấp một tham số khác cho phương pháp.

Ví dụ: việc thêm tham số sau filter đây sẽ hạn chế các thư được trả về với thuộc emailAddress tính của jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Các tài nguyên khác

Sau đây là các liên kết đến một số công cụ mà bạn có thể sử dụng để xây dựng và kiểm tra yêu cầu bằng api Microsoft Graph.