2026 年 4 月版本中的 API 變更

2026 年 4 月的 Adobe Learning Manager 版本針對公開 API 進行了針對替代方案與等效功能的專注強化，包括內容時窗存取、內容導向測驗嘗試、非登入體驗，以及職業輔助處理。 這些變更設計上大致向下相容，同時允許更精確的整合。

學習路徑的自適應學習

此版本新增了完整的公開 API 支援，以支援自適應學習路徑。 學習路徑（Learning Paths，LP）現在可以定義自適應規則，控制哪些區段與子學習物件（sub LO）對不同學習者群組可見，而公共 API 也反映了此行為。

以下終點受影響：

一個新的布林屬性 attributes.isAdaptive，表示學習程式使用自適應規則。 當此旗標為真時，該區段屬性會被自適應地解釋。

對於學習者呼叫，僅回傳目前學習者可見的區段。 每個區段包含學習物件 ID（loId）、一個強制旗標和一個強制的 LOCount，這些都是根據該學習者的自適應配置計算出來的，還有 sectionId。 relationships.subLOs 的關係現在也經過過濾，只包含該學習者可見的子學習物件。

對於管理員呼叫，區塊還可以同時暴露 adaptiveConfig 陣列。 此說明了各使用者群組的自適應規則，包括 userGroupId、userGroupName 以及該區塊是否為該群組的強制性。 面向管理的工具可以利用此點來視覺化和管理自適應規則。

學習計畫的重置完成

此版本引入了一套 API，用於 刷新（重置）學習物件的完成 ，包括自適應學習程式。 這支援了如再訓練、定期合規更新或計畫重啟等情境。

新增端點：

POST /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/refreshCompletion

此操作需要適當的寫入權限，並在指定使用者情境中重置指定學習物件實例的完成狀態。 它主要供管理端自動化或精心設計的學習工具使用。

此功能計畫透過 Jobs API 推出批量版本。 請求表單設計用來依電子郵件、使用者 ID 或使用者群組 ID 來鎖定使用者，例如：

{
  "emails": ["[user1@example.com](mailto:user1@example.com)", "[user2@example.com](mailto:user2@example.com)"],
  "userIds": ["12345", "67890"],
  "userGroupIds": ["ug1", "ug2"]
}

整合者在需要重新啟動每個課程或課程的學習者時，應該使用這個 API。 用戶端必須優雅地處理錯誤回應：API 可能會拒絕不適用重置的刷新請求（例如當沒有完成功能或不支援學習物件類型時）。

等價與替代完備化

為了支援多個學習物件能滿足相同需求的實作，本版本引入了等價與替代完成作為公開 API。

學習物件端點現在包含以下資訊：

- GET /primeapi/v2/learningObjects
- GET /primeapi/v2/learningObjects/{loId}

新的布林屬性 attributes.isAlternateComplete 顯示學習者對某個學習對象的完成是否來自另一個或等價的學習對象，而非該物件本身。 當此情況成立時，relationships.alternateCompletions 關係會列出作為替代角色的學習物件。 這使得下游報告與儀表板能區分直接完成與替代完成，並顯示哪個替代完成符合需求。

此外，相關學習對象視角允許發現可能滿足學習對象的替代方案。 此現象可透過以下方式曝光：

GET /primeapi/v2/learningObjects/{loId}/relatedLOs?type=sourceAlternateLOs&limit={n}

回應回傳可作為替代物件的學習對象，並包含一個meta.count欄位，顯示此類替代物件的總數，與當前限制無關。 整合系統可利用此方法呈現推薦的對應版本，或建立替代映射的管理視圖。

報告與分析的應用案例

產生報告或分析的使用者應更新邏輯，將 isAlternateComplete 和 alternateCompletions 加入報告工作流程。

使用完成資料的報告整合（例如，LT 匯出、自訂資料倉儲串流或 BI 儀表板）應擴展其邏輯，從 LO API 讀取並持久化屬性 .isAlternateComplete 與 relationships.alternateCompletions：

典型使用案例：

若不納入這兩個欄位，下游報告將將替代完成視為一般完成，無法​ 解釋   為 ​何學習者顯示完成了他從未直接接受的培訓。

學習者與管理員 LO API 行為

多語言工作輔助的結構在學習者與行政 LO API 中都是相同的。 學習者範圍只會回傳學習者可見的工作輔助，但對每個可見的工作輔助工具，它會透過多個資源實體（每個區域一個）及多區域本地化元資料，揭露所有已設定的區域。 管理範圍會回傳管理員能管理的所有工作輔助工具，使用相同的 LO 模型和區域特定資源 ID。 具有學習者範圍的客戶應選擇與學習者內容語言最匹配的 attributes.locale 資源，而管理工具則可列舉所有區域以便報告和管理。

具備註解功能的檢查清單

為了支援審核員能對檢查清單活動分享結構化回饋的工作流程，本版本透過學習物件資源 API 呈現​ 檢查清單評論 ​與審查者可見性控制。

與檢查清單相關的元資料會暴露在 learningObjectResource 實體（JApiLOResource，「類型」：「learningObjectResource」）上，這些實體代表課程或其他學習物件中的檢查清單資源。

相關資訊可透過以下管道取得：

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

當學習物件實例包含檢查清單類型的資源時，包含陣列中對應的 learningObjectResource 條目會在屬性下暴露評論與審查者可見性屬性，並在關係下顯示審查者身份。

新的檢查清單評論屬性

對於檢查清單資源，learningObjectResource 可能包含以下屬性：

其他針對檢查清單的上下文，如 checklistEvaluationStatus、isChecklistMandatory、resourceSubType：「CHECKLIST」及 submissionDate，也在同一 learningObjectResource 中提供，以支援更豐富的檢查清單使用者介面與報告功能。

審稿人身份關係

當審稿人名稱是要顯示時，learningObjectResource 包含一個指向審稿人使用者的關聯：

"relationships": {
  "checklistReviewedBy": {
    "data": {
      "id": "user_id",
      "type": "user"
    }
  }
}

此關係僅在以下​ 情況下被 ​填入：

用戶端應用程式應：

存取清單資源與評論

要取得檢查清單資源及其對特定學習物件的註解，客戶端應：

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

此模式允許無頭或自訂客戶端直接從 Prime API 呈現完整的檢查清單體驗，包括狀態、強制/可選標誌，以及審核者回饋。

報告與使用者體驗考量

多語言就業援助支援

為支援需同時以多種語言提供工作輔助給學習者與管理員的實作，本版本將工作輔助處理擴展為每個地區​ 回傳 ​一個資源，而非單一硬編碼的美國英語資源。

多語言工作輔助工具仍沿用現有的階層制度：

learning Object （lo） → learningObjectResource（loResource） → 資源

API 合約無需更改。 任何在地化的工作輔助工具自然都符合此結構，每個區域有獨立的資源實體，並在 learningObject / learningObjectResource 層級共享本地化元資料。

工作援助資料透過以下方式公開：

GET /primeapi/v2/learningObjects/jobAid:{jobAidId}?include=instances.loResources.resources

當工作輔助工具有多種語言變體時，所包含的陣列包含多個「類型」：「資源」條目——分別對應每個地區（例如 en-US、fr-FR、es-ES），全部由單一 learningObjectResource 連結。

多語言就業輔助結構

多語言工作輔助工具的用途：

對於多語言工作輔助工具，典型的模式是：

用戶端可透過將學習者的所在地與 resource.attributes.locale 欄位匹配來選擇合適的資源。

工作輔助工具的新資源 ID 格式

為了正確區分多個在地化的工作輔助資源變體，資源識別碼格式已改變。

舊的（舊有）資源 ID 格式

過去，工作協助資源使用的是不透明的識別格式，例如：

jobAid:131032_-1_-1_2_resource

此格式不編碼區域，API 實際上只會暴露單一資源（通常是美國）。

新的資源識別格式（多語言感知）

新格式如下：

jobAid:<jobAidId>_<version>_<localeCode>

舉例：

視覺解析：

jobAid:131032_2_fr_FR

        │      │ │ │

        │      │ │ └──► Locale Code (fr_FR, en_US, es_ES, etc.)

        │      │ └────► Version (2)

        │      └──────► JobAid ID (131032)

        └─────────────► Resource Type Prefix ("jobAid:")

此結構使客戶能：

向下相容性：

/resources/{resourceId}

舊有資源端點仍可使用：

它現在​ 同時向下相容 ​舊有與新 ID 格式：

目前儲存或參考舊資源 ID 的整合系統可繼續運作且不需更改，而較新的實作則鼓勵採用新的 ID 格式以執行區域特定操作。

整合與使用者體驗考量

起始模組的時間槽限制

有些學習經驗必須只在限定的時間範圍內提供。 該版本顯示學習對象資源的時間槽資訊，並引入驗證端點，檢查學習者是否能在當前時間啟動資源。

時隙元資料可透過端點取得：

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

在學習物件資源層級，timeSlot 物件現在可能存在於屬性中，且 startTime 與 endTime 的值以 UTC 表示。 這指定了資源可啟動的視窗。

在啟動模組前，整合可以呼叫新的驗證端點：

GET /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/loResources/{loResourceId}/canStart

此端點用於學習者-讀取情境，會回傳學習者是否目前被允許啟動該資源，並考量已設定的時間時隙、交付類型及其他後端規則。

自訂播放器與用戶端應用程式應使用 canStart 強制時間存取，並利用 timeSlot 元資料清楚顯示內容何時可用或過期。 canStart 的負面回應應明確處理，告知學習者為何該內容尚未或無法開始。

多重嘗試、內容導向測驗

有些內容套件會自行執行嘗試追蹤，而非僅依賴 Adobe Learning Manager。 該發布會引入一個標誌，指示何時嘗試是由內容本身驅動。

透過：

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources

學習物件資源現在可能會暴露一個布林屬性 hasContentDrivenAttemptTracking。 當情況成立時，測驗或模組會內部管理嘗試次數（例如透過 SCORM 或 xAPI 邏輯），而平台的標準嘗試計數器可能無法完全反映學習者的經驗。

顯示嘗試次數或控制重試行為的整合應該會檢查這個標記。 啟用後，不應僅從平台元資料推斷嘗試次數限制，應準備依賴內容端報告（例如透過 xAPI 語句）或業務專用規則。

工作援助資源ID格式中的行為改變

本版本引入了工作輔助資源 ID 格式的重要 行為變更 。 雖然沒有新的端點，但這會直接影響儲存或解析這些 ID 的系統。

過去，職業援助資源ID的格式如下：

jobAid:<jobAidId>_-1_-1_2_resource

在 2026 年 4 月版本中，此格式被簡化且更明確的格式取代：

jobAid:<jobAidId>_<version>_<localeCode>

例如：

jobAid:131032_2_fr_FR

組成部分包括：

任何索引資源或持續存在 Job Aid 資源 ID 的整合，都必須更新其解析與儲存邏輯以識別新格式。 由於識別碼本身會變動，強烈建議您在升級至 2026 年 4 月版本後，重建任何以 Job Aid 資源 ID 為關鍵的本地索引。

透過遷移設定航向橫幅圖片

你現在可以在 Adobe Learning Manager 中設定或更新課程橫幅影像，作為標準遷移工作流程的一部分。 這有助於你啟動或整理大型目錄，同時保持課程頁面的視覺一致性，無需手動編輯

橫幅圖片定義的地點

橫幅影像會在course.csv 遷移檔案中設定，你已經用來提供課程的元資料，例如：

透過此強化，course.csv規範新增了 課程橫幅圖片的選用欄位 。 精確的標頭名稱會在你從 Learning Manager 帳號下載的 CSV 規格中定義（例如，可能看起來像 bannerUrl 或 bannerImageUrl）。

橫幅欄：

準備遷移用的橫幅圖片

id,courseName,courseCreationDate,state,author,thumbnailUrl,bannerUrl
12345,DEMO1,2018-05-05T08:56:21.000Z,Published,Sudheer,pic1.png,banners/banner1.png
45678,DEMO2,2018-05-05T08:56:21.000Z,Published,Sudheer,pic2.png,banners/banner2.png

遷移時套用橫幅

一旦你的course.csv更新，流程就和其他遷移一樣：

新課程與現有課程的比較

橫幅欄位在兩種情況下都適用：

您的實際欄位名稱和路徑必須與下載的 CSV 規格​及內容庫配置相符。

移除 LearningProgramCourse 中的順序欄位

Adobe Learning Manager 現在支援在遷移過程中，學習路徑（學習程式​）內簡化的課程排序模型。作為此變更的一部分， learning program_course.csv遷移檔案中的排序欄位被移除_ 。

過去，learning_program_course.csv 檔案包含一個欄位（通常稱為 order 或類似欄位），用於：

現在，Adobe Learning Manager 不再使用 learning_program_course.csv 的排序欄來決定課程順序。 遷移 CSV 著重 於哪些課程屬於哪個學習計畫，而非它們的數字排序。

對遷移CSVs的影響

learning_program_course.csv

你應該將舊有訂單欄位視為已移除或忽略：

請務必參考 Learning Manager 帳號（透過 csv _specifications.zip）最新的_ CSV 規格_ ，以確認目前的標頭集和需求。

timeZoneCode 在球場實例

從本版本起，課程實例模型（learningObjectInstance）揭露了一個新屬性：

timeZoneCode ——一個字串欄位，明確將課程實例連結到帳號設定的時區之一。

這讓客戶能夠：

timeZoneCode 出現的地方

該欄位會被加入 learningObjectInstance 模型的屬性中僅限於課程實例。

範例：

{
  "id": "course:1262748_1359228",
  "type": "learningObjectInstance",
  "attributes": {
    "dateCreated": "2019-08-06T13:50:39.000Z",
    "isAET": false,
    "isDefault": true,
    "timeZoneCode": "356",
    "isFlexible": false,
    "state": "Active",
    "localizedMetadata": [
      {
        "locale": "en-US",
        "name": "Default instance"
      }
    ]
  }
}

如何解析 timeZoneCode

數值 timeZoneCode 是帳號時區目錄的查詢金鑰，透過帳號 API 公開：

GET /primeapi/v2/account
Authorization: Bearer <access_token>

回應中列出的時區如下：

"data": {
  "attributes": {
    "timeZones": [
      {
        "name": "Etc/GMT+12",
        "timeZoneCode": "356",
        "utcOffset": -720,
        "utcOffsetCode": "UTC-12:00(Etc/GMT+12)",
        "zoneId": "Etc/GMT+12"
      },
      "..."
    ]
  }
}

推薦客戶流程：

使用者群組成員資格的非同步公開 API

簡介

Adobe Learning Manager 提供兩個 管理非同步 API 來管理使用者群組（UG）成員資格：

這些 API 不會在同一請求中更新成員身份，而是接受你的批次並回傳事件 ID。 實際結果則會透過 webhook 後續傳送。

在以下情況下使用：

對於小型互動式的管理操作，你可以繼續使用同步 /userGroups/{id}/users API。

認證與基礎網址

這些 API 是標準 v2 管理 API 表面的一部分。

關於一般的管理員 API 行為與範圍，請參見：

請求格式

兩者加​減____​都使用完全相同的身形。

車身

{
  "metadata": {
    "event_id": "my-optional-correlation-id",
    "sourceSystem": "HRIS",
    "batchId": "hr_2026_03_30_0001"
  },
  "data": [
    { "type": "user", "id": "11101219" },
    { "type": "user", "id": "11101220" }
  ]
}

資料（必需）

資料是該批次的使用者資源識別碼清單。

限制條件

若上述任何條件失敗，API 會回傳錯誤，且不會被排隊。

元資料（可選）

metadata 你是否希望在 Webhook 中回傳任何額外的相關資料？

典型用法：

服務在 Webhook 回應中回傳這個物件時，保持不變，所以你可以將回調與你的內部工作匹配。

限制條件：

回應格式

兩個端點同步回應事件 ID：

{ "event_id": "cd2972c8-cb15-47a0-a23f-e4a16cb720f5" }

行為：

你應該時刻：

查看 Webhook 以新增或移除使用者群組成員 ，以便更多組織化。

常見問題

2026 年 4 月的版本將如何改變 learningObjects API 用於自適應學習程式？

此版本在學習程式上新增了 isAdaptive 旗標，並使區段與子語言組（subLO）對學習者有感知能力。 在自適應程式中，學習者只能看到根據自適應規則可見的區段和子學習物件，而管理員則可以看到使用者群組底層的自適應配置。

如果我的整合假設所有區段和子 LO 都會回傳，我需要更新嗎？

是的。 對於自適應學習程式，API 現在只會回傳目前學習者可見的段落和子 LO。 用戶端程式碼應將回應視為權威且可能經過過濾的視圖，而非假設完整清單。

我該如何以程式方式重置學習者完成課程或學習計畫的成績？

使用新的端點：

POST /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/refreshCompletion當權限與狀態允許時，這會重置目標實例的完成。

我如何判斷學習者是否透過替代或等效的學習物件完成了某件事？

檢查學習物件上的 isAlternateComplete 屬性。 如果是真的，alternateCompletions 關係列出了作為該學習者完成替代方案的學習物件。

我該如何找到所有能滿足特定學習對象的替代方案？

請使用以下端點：

GET /primeapi/v2/learningObjects/{loId}/relatedLOs?type=sourceAlternateLOs&limit={n}

並使用 data array（用於替代節點）和 meta.count（用於替代節點總數）。

我怎麼知道學習者此刻是否被允許開始一個模組？

首先，從以下處取得該資源的時間槽：

GET /primeapi/v2/learningObjects/{loId}?include=instances.loResources然後使用：

GET /primeapi/v2/learningObjects/{loId}/instances/{loInstanceId}/loResources/{loResourceId}/canStart

hasContentDrivenAttemptTracking 在資源上是什麼意思？

這表示嘗試追蹤是由內容本身控制（例如透過 SCORM/xAPI 邏輯），而不僅僅是平台計數器。 如果是真的，不要只依賴平台的嘗試次數或限制來做你的 UX 和報告。

我要如何取得適合未登入用戶（公開體驗）的選單？

用途：

GET /primeapi/v2/templates/menus?include=pages,subMenus.pages&isNonLoggedIn=true

此時會回傳篩選給匿名使用者的選單與頁面結構，適合 Experience Builder 或其他無頭網站。

effectiveModifiedDate 在工作協助篩選功能上有什麼改變？

將 filter.effectiveModifiedDate 與 filter.loTypes=jobAid 合併的請求，現在只會正確回傳指定日期視窗內的工作輔助資料。

工作援助資源識別碼格式有什麼改變？我該如何處理？

ID 格式從以下數值變更：

jobAid:<jobAidId>_-1_-1_2_resource

收件人：

jobAid:<jobAidId>_<version>_<localeCode>

例如JobAid:131032_2_fr_FR。 任何儲存或解析 Job Aid 資源 ID 的系統都必須更新，且你應計劃在升級至 2026 年 4 月版本後重建以這些 ID 為關鍵的本地索引。