使用 Microsoft Learn 目錄 API 的最佳做法
本文說明使用 Learn 目錄 API 的最佳做法。
瞭解服務條款
雖然 Learn 目錄 API 已公開提供且可免費使用，但使用者受 Microsoft API 使用條款 所約束。 先閱讀並瞭解 API 使用條款，並使用 Learn 目錄 API 和在任何生產環境中納入輸出。
瞭解 Learn 目錄 API 的限制
請參閱 Learn Catalog API 功能概觀 一文中的限制。
瞭解 Learn 內容模型
為了有效地使用 Learn 目錄 API 回應，請務必瞭解 Microsoft Learn 中可用的內容類型及其彼此的關聯性。 如需詳細資訊，請檢閱 Learn 內容模型文章。
特別注意:
- UID 代表唯一識別碼，而且對每個內容物件而言都是唯一的。 如果 UID 變更，即使標題或其他中繼資料保持不變，內容也會被視為新的物件。
- 課程模組是 Learn 訓練目錄中的核心物件。 它們全都能夠獨立存在，也就是說，課程模組會教導其內案例或概念端對端，而不需要採用必要條件課程模組。 對於課程模組來說，就是這樣，它們不是學習路徑的一部分。 對於其他課程模組來說，它們會以一或多個學習路徑組合在一起，引導使用者建置更進階的概念。 課程模組不一定要是學習路徑的一部分，或者也可以是一或多個學習路徑的一部分。
- 單元不會寫入為獨立內容。 單元應按照課程模組的特定順序進行。 基於這個理由，我們會包含課程模組詳細資料頁面和第一個單元的連結，以便使用者從該處開始並照順序進行內容。
瞭解當地語系化如何在 Learn 中運作，以及當地語系化內容如何反映在 API 輸出中
Microsoft Learn 支援網站上超過 65 個地區設定，而且大部分內容轉譯成這些地區設定。 我們的目標是提供內容中所教授的產品的所有語言版本的內容，但並非所有地區設定體驗都有可用的翻譯內容。
當地區設定記錄沒有相關聯的翻譯可用時，網站上的內容和 API 回應會「恢復」為預設值英文。 API 輸出時，當系統出現恢復情況時，您會在其他地區設定回應中看到英文中繼資料。 不過，內容的 URL 仍會指向地區設定，即使主要內容可能會恢復，其中原因是為了允許使用者仍然可在該地區設定中瀏覽網站 (這將顯示翻譯頁首/頁尾，以及任何其他有可用翻譯的連結)。
當更新內容發佈至英文內容時，我們的當地語系化管線會努力儘快更新的當地語系化版本 - 通常會在原始變更後的幾天內完成。
您可以在 Microsoft Learn 網站頁尾 (選取您正在檢視的語言) 中看到支援地區設定的完整清單。 這些地區設定中的每一個，都可以使用 locale 篩選條件，以 Learn 目錄 API 進行查詢。
我們的訓練內容完成記錄與地區設定無關，這表示我們不會將當地語系化的內容版本區分為使用者訓練完成記錄中的個別物件。 無論使用者完成訓練所使用的語言為何，他們都會獲得整體物件的點數，而且我們不會儲存其完成內容所使用之語言的參照。 此地區設定無關的完成情況表示如果您在學習體驗中實作 Learn 目錄 API，您必須將之納入考慮，而且，如果您以個別物件的形式載入內容物件，請實現它們之間的等效性，以便無論使用者使用哪種語言完成訓練，他們都能獲得其他語言的學分，而不必重新進行訓練。
瞭解內容版本設定如何在 Learn 中運作，以及如何反映在 API 輸出中
值得注意的是，內容會隨時更新。 我們每天發佈兩次可用的更新。 它們可能是次要更新，例如次要文字變更，或主要更新，例如主要修訂版本、新增內容或刪除內容。 一般而言，內容組合會以具有成千上萬個參與者的龐大、高度控管開放原始碼專案來管理，因此，隨時都有變更。 如果您在生產系統中使用 Learn 目錄 API，您應該瞭解這點，並確定您的系統能夠進行處理。
新增內容物件時，它們會顯示為回應中的新物件 (由 UID 識別)。 修改內容後，您可以根據其 last_modified 值來判斷。 當內容被刪除後，系統將會從回應中將內容物件移除。 雖然 API 回應中更新的內容有時會稍有延遲，但當使用者遵循內容的 URL 時，一律能看到最新的資訊。 若遇到刪除的情況，舊的 URL 會重新導向至新的內容或體驗，或到下一個最佳選項。
目前沒有任何內容版本的參照超過 last_modified 日期。
定期重新整理資料
如果您使用 Learn 目錄 API 的目錄資訊，來支援您的業務程序，或將之作為網站體驗的一部分向客戶顯示，請確定您每天至少重新整理內容一次。
值得注意的是，內容會隨時更新。 我們每天發佈兩次可用的更新。 它們可能是次要更新，例如次要文字變更，或主要更新，例如主要修訂版本、新增內容或刪除內容。 一般而言，內容組合會以具有成千上萬個參與者的龐大、高度控管開放原始碼專案來管理，因此，隨時都有變更。 如果您在生產系統中使用 Learn 目錄 API，您應該瞭解這點，並確定您的系統能夠進行處理。
檢閱開發人員文件的建議
Learn 目錄 API 開發人員文件 包含回應中提供的完整資料清單，以及針對如何使用每個欄位來支援絕佳的學習體驗的建議。
瞭解查詢邏輯
有許多篩選條件可用來預先篩選回應，因此您只會取得所要尋找的內容，而且可以處理較小的檔案大小。 您可以在 Learn 目錄 API 開發人員參考文章 中看到查詢篩選條件的完整清單。 值得注意的是，您必須正確形成查詢，而且如果您在要求中使用多個查詢參數，則查詢會使用 AND 運算子來進行評估。
下一步
如需使用 Learn 目錄 API 支援的詳細資訊，請檢閱下列文章: