本文說明使用 Learn 目錄 API 的最佳做法。
瞭解服務條款
雖然 Learn 目錄 API 已公開提供且可供使用，但使用者受限於 Microsoft API 使用規定。 在使用 Learn 目錄 API 之前，以及在任何生產環境中納入輸出之前，請先閱讀並瞭解 API 使用規定。
瞭解 Learn 目錄 API 的限制
請參閱 Learn 類別目錄 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，您必須考慮到這一點，並且如果您將內容物件分別載入，請實作它們之間的等價關係，如此無論使用者完成訓練的語言為何，他們都能在其他語言中獲得 credits，而不需要重新參加訓練。
了解內容版本控制如何在 Learn 中運作，以及如何反映在 API 輸出中
值得注意的是，內容會隨時更新。 我們每天發佈兩次可用的更新。 它們可能是次要的，例如次要文字變更，或主要，例如主要修訂、新增或刪除。 一般而言，內容組合包會以具有數千個參與者的龐大量高度控管開源專案來管理，因此，改變持續不斷發生。 如果您在生產系統中使用 Learn 目錄 API，您應該注意這一點，並讓系統能夠處理它。
新增內容物件時，它們會顯示為回應中的新物件（由 UID 識別）。 當內容被修改時，您可以根據其 "last_modified" 的值來判斷。 刪除內容時，內容物件會從回應中移除。 雖然 API 回應中更新的內容有時會稍有延遲，但當使用者遵循內容的 URL 時，他們一律會看到最新的資訊。 在刪除的情況下，舊的 URL 會重新導向至新的內容或體驗，或重新導向至下一個最佳選項。
目前沒有任何超過 last_modified 日期的內容版本紀錄。
定期重新整理數據
如果您使用 Learn Catalog API 中的目錄資訊來支援您的商務流程，或顯示給客戶作為網站體驗的一部分，請確保每天至少重新整理內容一次。
值得注意的是，內容會隨時更新。 我們每天發佈兩次可用的更新。 它們可能是次要的，例如次要文字變更，或主要，例如主要修訂、新增或刪除。 一般而言，內容組合以大量高度管理的開放原始碼專案進行管理，該專案有數千名參與者，因此，不斷地發生變更。 如果您在生產系統中使用 Learn 目錄 API，您應該注意這一點，並讓系統能夠處理它。
檢閱開發人員文件的建議
Learn 目錄 API 開發人員檔 包含回應中提供的完整數據清單，以及建議如何使用每個欄位來支援絕佳的學習體驗。
了解查詢邏輯
有許多篩選條件可用來預先篩選回應，因此您只會取得所要尋找的內容，而且可以處理較小的檔案大小。 您可以在 Learn 目錄 API 開發人員參考文章中看到查詢篩選的完整清單。 值得注意的是，您必須正確形成查詢，而且如果您在要求中使用多個查詢參數，則會使用 AND 運算符來評估查詢。
後續步驟
如需更多與 Learn 目錄 API 有關的資訊以支援您，請檢閱下列文章：