Bagikan melalui

Praktik terbaik untuk menggunakan Microsoft Learn Catalog API

  • Artikel

Artikel ini menjelaskan praktik terbaik untuk menggunakan Learn Catalog API.

Memahami Ketentuan Layanan

Meskipun Learn Catalog API tersedia untuk umum dan gratis digunakan, pengguna tunduk pada Ketentuan Penggunaan Microsoft API. Baca dan pahami Ketentuan Penggunaan API sebelum menggunakan Learn Catalog API dan sebelum menyertakan output di lingkungan produksi apa pun.

Memahami batasan Learn Catalog API

Lihat Batasan dalam artikel gambaran umum Fitur Learn Catalog API .

Memahami model pelajari konten

Untuk menggunakan respons Learn Catalog API secara efektif, penting untuk memahami jenis konten yang tersedia di Microsoft Learn dan hubungannya satu sama lain. Tinjau artikel model konten Learn untuk informasi lebih lanjut.

Terutama:

  • UID adalah singkatan dari ID Unik dan unik untuk setiap objek konten. Jika UID berubah, meskipun judul atau metadata lainnya tetap sama, konten dianggap sebagai objek baru.
  • Modul adalah objek inti dalam katalog pelatihan Learn. Mereka semua mandiri, artinya mereka mengajarkan skenario atau konsep secara menyeluruh dan tidak memerlukan modul prasyarat. Bagi sebagian orang, ini adalah itu dan mereka bukan bagian dari jalur pembelajaran. Bagi yang lain, mereka dibundel bersama-sama dalam satu atau beberapa jalur pembelajaran yang membawa pengguna melalui membangun konsep yang lebih canggih. Modul tidak harus menjadi bagian dari jalur pembelajaran, atau dapat menjadi bagian dari satu atau beberapa modul.
  • Satuan tidak ditulis sebagai konten yang berdiri sendiri. Instruksi tersebut dimaksudkan untuk diikuti dalam urutan tertentu untuk modul. Untuk alasan ini, kami menyertakan tautan ke halaman detail modul dan unit pertama sehingga pengguna dapat mulai di sana dan melanjutkan melalui konten.

Memahami cara kerja pelokalan di Pelajari dan bagaimana konten yang dilokalkan tercermin dalam output API

Microsoft Learn mendukung lebih dari 65 lokal di situs dan sebagian besar konten diterjemahkan ke dalam lokal ini. Kami bertujuan untuk membuat konten tersedia dalam semua bahasa yang tersedia untuk produk dalam konten tersebut, namun tidak semua pengalaman lokal sudah memiliki konten yang dilokalkan.

Ketika rekaman lokal tidak memiliki terjemahan terkait yang tersedia, konten di situs dan respons API "kembali" ke bahasa Inggris sebagai default. Dalam output API, Anda akan melihat metadata Inggris pada respons lokal lain saat umpan balik terjadi. Namun, URL ke konten masih mengarah ke bahasa tersebut, meskipun konten utama dapat kembali ke versi sebelumnya. Alasannya adalah untuk memungkinkan pengguna tetap dapat menavigasi situs dalam bahasa tersebut, yang menunjukkan header/footer yang diterjemahkan, serta tautan lain yang memiliki terjemahan yang tersedia.

Ketika pembaruan diterbitkan ke konten bahasa Inggris, alur pelokalan kami berfungsi untuk memperbarui versi yang dilokalkan sesegera mungkin - biasanya dalam beberapa hari setelah perubahan asli. Anda dapat melihat daftar lengkap lokal yang didukung di footer situs Microsoft Learn (pilih bahasa yang Sedang Anda lihat). Masing-masing lokal ini dapat dikueri dengan Learn Catalog API menggunakan filter locale.

Catatan penyelesaian konten pelatihan kami bersifat lokal-agnostik, artinya, kami tidak membedakan versi konten yang dilokalkan sebagai objek terpisah dalam rekaman penyelesaian pelatihan pengguna kami. Tidak peduli bahasa apa pun yang digunakan pengguna untuk menyelesaikan pelatihan, mereka menerima kredit untuk objek keseluruhan, dan kami tidak menyimpan referensi ke dalam bahasa apa pelatihan itu diselesaikan. Penyelesaian lokal-agnostik ini berarti jika Anda menerapkan Learn Catalog API dalam pengalaman pembelajaran Anda, Anda perlu memperhitungkannya dan, jika Anda memuat objek konten sebagai objek terpisah, terapkan kesetaraan di antara mereka sehingga tidak peduli bahasa mana yang digunakan pengguna untuk menyelesaikan pelatihan, mereka mendapatkan kredit untuk itu dalam bahasa lain dan tidak perlu mengambilnya kembali.

Pahami cara kerja penerapan versi konten di Learn dan bagaimana penerapan versi tersebut tercermin dalam output API

Terutama, konten sedang diperbarui sepanjang waktu. Kami menerbitkan pembaruan yang tersedia dua kali sehari. Mereka mungkin kecil, seperti perubahan teks kecil, atau utama, seperti revisi utama, penambahan, atau penghapusan. Secara umum, portofolio konten dikelola sebagai proyek sumber terbuka besar dan sangat diatur dengan ribuan kontributor, dan dengan demikian, perubahan terjadi sepanjang waktu. Jika Anda menggunakan Learn Catalog API dalam sistem produksi, Anda harus mengetahui hal ini dan membuat sistem Anda dapat menanganinya.

Saat objek konten baru ditambahkan, objek tersebut muncul sebagai objek baru (diidentifikasi oleh UID) dalam respons. Saat konten dimodifikasi, Anda dapat mengetahui berdasarkan nilai last_modified. Saat konten dihapus, objek konten dihapus dari respons. Meskipun terkadang ada sedikit keterlambatan pada konten yang diperbarui dalam respons API, ketika pengguna mengikuti URL ke konten, mereka akan selalu melihat informasi terbaru. Dalam kasus penghapusan, URL lama akan dialihkan ke konten atau pengalaman baru, atau ke opsi terbaik berikutnya.

Saat ini tidak ada referensi ke versi konten di luar tanggal last_modified.

Memperbarui data secara teratur

Jika Anda menggunakan informasi katalog dari Learn Catalog API untuk mendukung proses bisnis Anda, atau menampilkan untuk pelanggan sebagai bagian dari pengalaman situs Anda, pastikan Anda me-refresh konten setidaknya sekali sehari.

Terutama, konten sedang diperbarui sepanjang waktu. Kami menerbitkan pembaruan yang tersedia dua kali sehari. Mereka mungkin kecil, seperti perubahan teks kecil, atau utama, seperti revisi utama, penambahan, atau penghapusan. Secara umum, portofolio konten dikelola sebagai proyek sumber terbuka besar dan sangat diatur dengan ribuan kontributor, dan dengan demikian, perubahan terjadi sepanjang waktu. Jika Anda menggunakan Learn Catalog API dalam sistem produksi, Anda harus mengetahui hal ini dan membuat sistem Anda dapat menanganinya.

Tinjau rekomendasi dokumentasi pengembang

Dokumentasi pengembang Learn Catalog API memiliki daftar lengkap data yang disediakan sebagai bagian dari respons, dan rekomendasi tentang bagaimana setiap bidang direkomendasikan untuk digunakan untuk mendukung pengalaman pembelajaran yang hebat.

Memahami logika kueri

Ada banyak filter yang tersedia untuk digunakan untuk memfilter respons sebelumnya, sehingga Anda hanya mendapatkan apa yang Anda cari dan dapat menangani ukuran file yang lebih kecil. Anda dapat melihat daftar lengkap filter kueri di artikel referensi Learn Catalog API Developer. Terutama, Anda perlu membentuk kueri dengan benar dan jika Anda menggunakan lebih dari satu parameter kueri dalam permintaan, kueri dinilai menggunakan operator AND.

Langkah berikutnya

Untuk informasi selengkapnya untuk mendukung Anda dengan Learn Catalog API, tinjau artikel berikut: