使用學校數據同步處理的 OneRoster API 提供者上線指引 (SDS)

發行項
10/15/2024

簡介

Microsoft 學校資料同步處理 (SDS) 可以從任何實作 1EdTech OneRoster API (應用程式開發介面的系統同步處理身分識別和名冊資訊，) 輸入數據流中的標準。本檔旨在協助 OneRoster API 的任何新提供者成功與 SDS 整合。客戶可以使用 REST 型 OneRoster 1.1 API 直接連線到其提供者。下列上線程式會定義 API 提供者必須先執行的步驟，才能新增這些步驟，租使用者才能在 SDS 中選取和使用。

關於 SDS

如果您想要深入瞭解 SDS，請移至 SDS 產品網站。
如需有關 SDS 的技術資訊，包括部署影片和系統管理員指引，請移至 SDS 文件網站。
如需客戶使用 OneRoster API 連線數據體驗的詳細資訊，請移至使用 OneRoster API 連線數據。

概觀

完成 SDS 合作夥伴註冊表單上的表單。
1. 表示您會在表單上提供學校資料同步整合協助。
2. 需要註冊才能存取窗體 - 如需詳細資訊，請造訪Microsoft合作夥伴網站。您必須提交個別表單以供 SDS 和 Office 開發資源存取。
實作 SDS 所需的 OneRoster API 端點。

SDS 會使用 dateLastModified 屬性上的篩選條件來進行差異同步處理/累加式同步處理，而且需要此篩選條件才能與 SDS 整合。
確認 SDS 可與您的 OneRoster API 端點搭配運作。
1. 使用 Postman集合評估您的 API。
2. 針對沙箱環境使用SDS工程進行測試。
3. 設定SDS以驗證解決方案 E2E。
使用兩個生產客戶來試驗解決方案。
讓所有 Office 365 EDU 租使用者在 SDS 中正式推出您的連接器。

快速入門

如果您是新開發的 OneRoster API，請遵循核心名冊的 OneRoster API v1.1 規格。
我們建議以 1EdTech 的提供者身分進行認證，但不需要它。 
如需 SDS 所支援之預設值清單的詳細資訊，請參閱預設值清單。

SDS 的必要 API 端點

動作	URL	必要的篩選屬性	選擇性/建議的篩選	範例
GetAllAcademicSessions	/academicSessions	狀態	dateLastModified	/academicSessions？offset=0&limit=5000&filter=status='active'/academicSessions？filter=dateLastModified>'{deltaDateTime}'
GetAllOrgs	/orgs	狀態	dateLastModified	/orgs？offset=0&limit=5000&filter=status='active'/orgs？filter=dateLastModified>'{deltaDateTime}'
GetAllUsers	/使用者	狀態	dateLastModified	/users？offset=0&limit=5000&filter=status='active'/users？filter=dateLastModified>'{deltaDateTime}'
GetAllClasses	/類	狀態	dateLastModified	/classes？offset=0&limit=5000&filter=status='active'/classes？filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments	/入學人數	狀態	dateLastModified	/enrollments？offset=0&limit=5000&filter=status='active'/enrollments？filter=dateLastModified>'{deltaDateTime}'

適用於 SDS 的選擇性 API 端點

注意事項

針對人口統計、學生聯繫人關係和學生使用者旗標的選擇性數據片段，客戶包含此數據或不包含此數據的能力，將會以我們將建立的提供者配置檔中支援的選用數據功能為基礎。遵循所述的測試和驗證步驟，如果您選擇也針對使用SDS的客戶支援此數據，他們會看到切換 (預設) 選取 [ 開啟 ] 以包含其他數據。他們可以視需要選取要關閉的切換開關。如果切換無法使用、顯示但關閉，且無法進行互動，這表示您的提供者配置檔目前不支援提供該數據。

動作	URL	必要的篩選屬性	選擇性/建議的篩選	範例
GetAllCourses	/課程	狀態	dateLastModified	/courses？offset=0&limit=5000&filter=status='active'/courses？filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics	/人口	狀態	dateLastModified	/demographics？offset=0&limit=5000&filter=status='active'/demographics？filter=dateLastModified>'{deltaDateTime}'

選擇性的用戶學生聯繫人關係

提示

由於如果透過 OneRoster API 提供學生聯繫人數據，SDS 不支援透過 CSV 側載學生聯繫人日期，建議所有提供者都使用 OneRoster API 方法來支援提供連絡人。

您可以為學生使用者指定學生聯繫人關係，以增強與學生家長和守護者通訊的授課者體驗。聯繫人是更多使用 /users 端點提供的使用者，而與學生的關聯會在學生的用戶記錄的 'agents' 底下找到。

如需 SDS 所支援學生聯繫人關聯性角色的詳細資訊，請參閱預設值清單：聯繫人關聯性角色。
具有聯繫人/守護者角色的使用者需要familyName、givenName和電子郵件。
預期電話和簡訊必須包含在 E.164 和 + 中。 (範例： +1234567890) 。
如果提供反向數據，從聯繫人關係守護者記錄到聯繫人使用者「代理程式」欄位中的學生，就會篩選掉這些記錄。

選擇性的使用者人口統計旗標

您可以為學生使用者指定使用者旗標，以表示他們參與計劃或世代。當使用者) 為 true 時，會包含使用者旗標 (，如果不適用則不包含。

旗標會在元數據欄位中指定為使用者的元數據延伸。方法遵循索引鍵|值組，具有名為 microsoft.userFlags 的索引鍵，且必須格式化為逗號分隔清單。用戶旗標可以依任何順序顯示，且不區分大小寫。

如需詳細資訊，請參閱 SDS 支援的預設使用者旗標值清單，請參閱預設值清單：使用者旗標。

例如:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

數據比對和驗證規則

如需數據比對和驗證規則的詳細資訊，請參閱驗證規則和描述。

重要事項

根據 1EdTech，提供者必須負責在提出數據要求時，強制執行可用數據的數據隱私權。學校數據同步會根據要求的時間提出使用中數據的要求。

實用的附注和秘訣

端點一律位於 HTTPs URL 後面：{server_URL}/ims/oneroster/v1p1。
所有端點都必須支援分頁，也就是限制和位移參數 (例如：limit=10&offset=5000) 。
端點對於篩選參數支援有需求，以允許依狀態篩選，或啟用差異同步處理。
客戶知道如何啟用 [作用中] 選項，或如何只允許作用中數據可供學校數據同步使用的連線使用。這可確保在學年進行時，只會提供使用中學年和會話的作用中數據。
若要防止特定學校包含在從 SIS 提供給 SDS 的數據中，客戶知道如何設定要用來將 SDS 連結至其 SIS 的連線/認證所包含的學校。
SDS 會在 dateLastModified 屬性上套用篩選條件，以進行差異同步處理/累加式同步處理，且需要此篩選條件才能與 SDS 整合。
提供者必須選擇 () 或 OAuth 2.0 實作 OAuth1， (客戶端認證授與) 驗證配置，建議使用 OAuth 2.0。
在開發期間，您可以使用我們的 Postman 集合來驗證您的端點。
如果支援的驗證通訊協定是「OAuth 2」 - 客戶端認證授與類型，SDS 會在 “Authorization” 標頭中傳送認證。 SDS 不支援在要求本文中傳送認證。

測試您的 OneRoster API

使用 Postman 集合

Postman 是用來執行和管理 REST API 的已知工具。我們建立了 OneRoster API Postman 集合，以叫用和測試 SDS 所需的 OneRoster API。執行集合會叫用SDS所需的所有API，並針對傳回的數據執行簡單的測試。

針對沙箱環境測試SDS工程

為您的 OneRoster API 建立沙箱環境，並與您指定的 SDS 工程師共用認證。我們會一起執行一組更深入的測試，以確保整合成功。

設定以驗證解決方案

當所有測試都成功時，系統名稱會新增至 SDS 中的 OneRoster 提供者清單。不過，目前只有針對證明為 'InPilot' 模式之提供者配置檔進行正式發行前小眾測試的租使用者， (無法公開取得) 。接下來，將 SDS 設定為在測試Microsoft 365 租使用者中使用 OneRoster API 連線數據，以同步處理來自沙箱 OneRoster 端點的數據，並確保執行完成而不會發生錯誤。如果您在自行調查之後看到任何錯誤或警告，而且需要協助，請連絡指定的 SDS 工程師。

客戶試驗

測試成功完成之後，就可以開始與客戶試驗解決方案。您的系統名稱會顯示在 SDS 中的 OneRoster® 提供者清單中，讓這些「正式發行前小眾測試」的提供者也能看到「InPilot」模式的提供者，同意試驗整合。 SDS 小組和 OneRoster 提供者小組共同合作，以識別適當的試驗客戶，並排程部署 SDS 的時間。我們與客戶密切合作，以確保輸入流程執行成功，並一起驗證結果。在將解決方案公開提供給所有 Office 365 教育客戶之前，必須先解決所有已識別到的任何最終錯誤。

移至公用

一旦兩個客戶成功完成試驗部署，合作夥伴系統便可在 SDS 中作為經認證的 OneRoster 提供者來源系統使用。當租使用者使用 OneRoster API 定義其連線數據組態時，SDS 會向租用戶顯示提供者的名稱。 SDS 小組會在我們的 SDS 在線檔的 OneRoster API 提供者概觀頁面上記錄合作夥伴系統。

SDS 小組需要：

軟體的最低版本
設定必要條件
如何取得用戶端標識碼、客戶端密碼和URL
任何其他特定指示
要連絡的人員以尋求協助

SDS 小組可能會與您的小組協調，以透過各種行銷管道更廣泛地促進整合。

共用方式為