Bắt đầu với API Nền tảng Microsoft Learn

Bài viết này hỗ trợ bạn bắt đầu sử dụng API Nền tảng Microsoft Learn. Nếu bạn không quen thuộc với thông tin chi tiết về API hoặc các trường hợp sử dụng của nó, chúng tôi khuyên bạn nên xem lại bài viết Tổng quan về API Nền tảng Microsoft Learn trước.

Tìm hiểu xác thực API nền tảng

API REST của Learn Platform sử dụng Microsoft Entra ID để xác thực. Trước khi thực hiện lệnh gọi API, bạn cần chọn phương thức truy cập và ứng dụng khách của bạn phải xác thực bằng thông tin đăng nhập hợp lệ.

Quyền truy cập chỉ ứng dụng

Khi ứng dụng của bạn truy cập trực tiếp vào Tìm hiểu, quyền truy cập của ứng dụng đó không bị ràng buộc với bất kỳ người dùng nào. Ứng dụng gọi API trực tiếp bằng danh tính của chính nó, trường hợp này là quyền truy cập chỉ ứng dụng. Tìm hiểu thêm về nền tảng danh tính của Microsoft.

Để bắt đầu, bạn cần có danh tính hợp lệ trên Nền tảng Danh tính Microsoft, có thể là đăng ký ứng dụng hoặc danh tính được quản lý. Lý tưởng nhất là mỗi đối tác nên có một danh tính duy nhất để đơn giản hóa hạn ngạch và quản lý đối tác. Sử dụng danh tính được quản lý do người dùng chỉ định có thể giúp hợp nhất danh tính được quản lý trên các dịch vụ khác nhau.

Sau khi danh tính Entra ID của bạn được thiết lập, hãy lấy mã truy cập từ Entra ID với phạm vi được đặt làm bằng chứng xác thực. Bao gồm mã truy cập trong tiêu đề Ủy quyền HTTP khi thực hiện yêu cầu API REST cho Learn.

Quyền truy cập được ủy quyền

Khi người dùng đăng nhập vào ứng dụng của bạn và sử dụng ứng dụng đó để truy cập Tìm hiểu, trước tiên ứng dụng cần thay mặt người dùng yêu cầu quyền truy cập vào tài nguyên này. Kịch bản này được gọi là quyền truy cập được ủy quyền. Tìm hiểu thêm về nền tảng danh tính của Microsoft.

Để bắt đầu, bạn cần đăng ký đăng ký ứng dụng. Sau khi thiết lập đăng ký ứng dụng, ứng dụng của bạn cần yêu cầu người dùng cấp một phạm vi cụ thể hoặc tập hợp các phạm vi để thay mặt người dùng truy cập Tìm hiểu. Learn cung cấp danh sách các phạm vi để truy cập tài nguyên chi tiết. Danh sách các phạm vi bao gồm:

• : Phạm vi này cho phép người dùng truy cập nội dung công khai trên Learn mạo danh người dùng đã đăng nhập.

Tìm hiểu về Phiên bản API Nền tảng Microsoft Learn

Khi API thực hiện các thay đổi đột phá, chúng tôi sẽ phát hành một phiên bản mới, đã cũ. Thay đổi phá vỡ là những thay đổi có khả năng phá vỡ tích hợp. Mọi thay đổi không phá vỡ (bổ sung) sẽ có sẵn trong tất cả các phiên bản API được hỗ trợ.

Phiên bản API được chỉ định dưới dạng tham số truy vấn phiên bản api và sử dụng yyyy-MM-dd cho phiên bản ổn định và yyyy-MM-dd-preview cho phiên bản xem trước. Tham số truy vấn phiên bản api là bắt buộc đối với mọi yêu cầu API.

Khi phiên bản API ổn định mới được phát hành, phiên bản API ổn định trước đó sẽ được hỗ trợ trong ít nhất 24 tháng nữa sau khi phát hành phiên bản API mới. API xem trước có chu kỳ hỗ trợ ngắn hơn ba tháng nữa sau khi phát hành API xem trước mới.

Phiên bản hiện tại là 2023-11-01-preview.

Phân đoạn URL /v1/ trước mỗi API là một phần của URL cơ sở chứ không phải phiên bản API. Nó được dành riêng cho các thay đổi đáng kể về giao thức API và mẫu trong tương lai.

Tìm hiểu giới hạn tốc độ API nền tảng

Tìm hiểu giới hạn số lượng yêu cầu API REST mà bạn có thể thực hiện trong một khoảng thời gian cụ thể. Giới hạn này giúp ngăn chặn các cuộc tấn công lạm dụng và từ chối dịch vụ, đồng thời đảm bảo rằng API vẫn có sẵn cho tất cả người dùng.

Tìm hiểu áp dụng giới hạn tốc độ dựa trên xác nhận oid trong mã truy cập. Đối với quyền truy cập chỉ ứng dụng, giới hạn được áp dụng cho chính ứng dụng, trong khi đối với quyền truy cập được ủy quyền, giới hạn được áp dụng cho người dùng đã đăng nhập vào ứng dụng.

Theo mặc định, giới hạn tốc độ là 100 lệnh gọi API mỗi phút, được tính trong khoảng thời gian 5 phút. Nếu yêu cầu giới hạn sản xuất cao hơn, bạn có thể liên hệ với Bộ phận hỗ trợ Learn Integrations để yêu cầu tăng.

Một số API nhất định, như API tìm kiếm kiến thức, cũng triển khai giới hạn tốc độ dựa trên mã thông báo. Điều này dựa trên số lượng mã thông báo Microsoft Azure OpenAI đã tiêu thụ, với giới hạn mặc định là 10.000 mã thông báo mỗi phút. Để tăng giới hạn này cho sản xuất, hãy liên hệ với Bộ phận hỗ trợ tích hợp Tìm hiểu.

Tìm hiểu phân trang API nền tảng

Tất cả các tài nguyên API cấp cao nhất đều hỗ trợ truy xuất hàng loạt thông qua các phương thức API 'danh sách'. Ví dụ: bạn có thể truy xuất danh sách các mô-đun hoặc bài kiểm tra. Các phương thức này trả về phản hồi được phân trang theo cách tiếp cận được chuẩn hóa.

Các phương thức API danh sách sử dụng phân trang dựa trên con trỏ, được biểu thị bằng trường nextLink trong nội dung phản hồi. Trường này chứa một URL mờ đục với thông tin cần thiết để tìm nạp trang kết quả tiếp theo. Theo mặc định, API danh sách trả về 30 mục cho mỗi yêu cầu, nhưng bạn có thể điều chỉnh kích thước trang bằng thông số maxpagesize.

Thư viện SDK ứng dụng của chúng tôi cung cấp trình trợ giúp tự động phân trang để duyệt qua tất cả các trang của danh sách.

Nội dung liên quan

• Bắt đầu nhanh: Thiết lập và sử dụng Dữ liệu Danh mục API Nền tảng Microsoft Learn
• Tìm hiểu dữ liệu danh mục API nền tảng Tham khảo dành cho nhà phát triển
• Tìm hiểu câu hỏi thường gặp về API nền tảng