上架 OneRoster® API 提供者 SDS 和年級同步處理Onboarding OneRoster® API providers in SDS and Grade Sync

簡介Introduction

Microsoft School Data Sync 可同步處理輸入資料流程中任何執行 IMS OneRoster® API standard 之系統的身分識別與名單資訊。Microsoft School Data Sync can synchronize identity and roster information from any system that implements the IMS OneRoster® API standard in an inbound data stream. 年級同步處理也會使用 IMS OneRoster® API,不過這是從小組傳回 SIS 的輸出流程。Grade sync also uses the IMS OneRoster® API however this is an Outbound flow back to the SIS from Teams. 本檔的目的是為了協助 OneRoster®的任何新提供者,APIs 順利整合學校資料同步和年級同步處理。下列上架程式會定義 API 提供者所需的步驟,才能將其新增至 School Data Sync 入口網站。This document is intended to help any new providers of OneRoster® APIs to successfully integrate with School Data Sync and Grade Sync. The following onboarding process defines the steps required by the API provider before they can be added into the School Data Sync portal.

SDS 整合的 API 指導方針API Guidance for SDS integration

  1. SDS Partner 註冊表單上完成表單。Complete the form on the SDS Partner Signup Form.

  2. 實施 School Data Sync 所需的 OneRoster API®端點。Implement the OneRoster API® endpoints required by School Data Sync.

  3. 驗證 School Data Sync 是否可與您的 OneRoster API 端點搭配使用。Verify School Data Sync works with your OneRoster API endpoints.

    a.a. 使用 Postman 集合測試 APIs。Test your APIs using Postman collection.

    b.b. 在沙箱環境中測試 SDS 工程。Test with SDS engineering against a sandbox environment.

    c.c. 在 SDS 中設定完整同步處理以驗證方案 E2E。Configure a full sync in SDS to validate the solution E2E.

  4. 使用2個生產客戶試驗解決方案。Pilot the solution with 2 production customers.

  5. 讓您的連接器在 SDS 中可用於所有 Office 365 EDU 承租人。Make your connector Generally Available in SDS for all Office 365 EDU tenants.

快速入門Getting Started

關於 School Data SyncAbout School Data Sync

  • 如果您想要深入瞭解 SDS,請移至 SDS 產品網站If you’d like to learn more about SDS, go to the SDS Product Site.

  • 如需 SDS 的相關技術資訊,包括部署影片和系統管理指引,請移至 [SDS 檔] 網站For technical information regarding SDS, including deployment videos and admin guidance, go to the SDS Docs site.

  • 如需搭配 OneRoster API®使用 SDS 的詳細資訊,請移至 [SDS OneRoster] 頁面](https://aka.ms/sdsoneroster)。For more information on using SDS with OneRoster API®, go to the SDS OneRoster page.

  • 如果您想要將您的系統與 School Data Sync 和 Office 365 整合,請完成 SDS Partner FormIf you’d like to integrate your system with School Data Sync and Office 365, please complete the SDS Partner Signup Form.

有用資源Useful Resources

如果您是® APIs 的 OneRoster,請遵循 核心名冊登記的OneRoster API 1.1 規格。If you are newly developing the OneRoster® APIs, please follow the OneRoster API 1.1 specification for Core Rostering here.

使用 c # ASP.NET MVC 中的範例實現是在 這裡A sample implementation in ASP.NET MVC using C# is here.

我們建議使用 IMS Global 提供者的 認證 ,但不需要。We suggest certification of the provider with the IMS Global, but do not require it.

學校資料同步處理的必要 API 端點Required API Endpoints for School Data Sync

動作Action [URL]****URL 必要的篩選屬性Required Filter Properties 範例Examples
getAllAcademicSessionsgetAllAcademicSessions /academicSessions/academicSessions schoolYear、狀態schoolYear, status /academicSessions? filter = schoolYear = ' 2019 ' 和狀態 = ' active '/academicSessions?filter=schoolYear='2019' AND status='active'
getAcademicSessiongetAcademicSession /academicSessions/{academicSession_id}/academicSessions/{academicSession_id}
getAllUsersgetAllUsers /users/users status,dateLastModifiedstatus, dateLastModified /schools? filter = status = ' active ' AND dateLastModified> ' 2018-01-25T03:22: 03.297 Z '/schools?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getUsergetUser /users/{user_id}/users/{user_id}
getAllSchoolsgetAllSchools /schools/schools status,dateLastModifiedstatus, dateLastModified /users? filter = status = ' active ' AND dateLastModified> ' 2018-01-25T03:22: 03.297 Z '/users?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getSchoolgetSchool /schools/{school_id}/schools/{school_id}
getClassesForSchoolgetClassesForSchool /schools/{school_id}/classes/schools/{school_id}/classes status,dateLastModifiedstatus, dateLastModified /schools/{school_id}/classes? filter = dateLastModified> ' 2018-01-25T03:22: 07.209 Z '/schools/{school_id}/classes?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getStudentsForSchoolgetStudentsForSchool /schools/{school_id}/students/schools/{school_id}/students status,dateLastModifiedstatus, dateLastModified /schools/{school_id}/students? filter = dateLastModified> ' 2018-01-25T03:22: 07.209 Z '/schools/{school_id}/students?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getTeachersForSchoolgetTeachersForSchool /schools/{school_id}/teachers/schools/{school_id}/teachers status,dateLastModifiedstatus, dateLastModified /schools/{school_id}/teachers? filter = dateLastModified> ' 2018-01-25T03:22: 07.209 Z '/schools/{school_id}/teachers?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getEnrollmentsForSchoolgetEnrollmentsForSchool /schools/{school_id}/enrollments/schools/{school_id}/enrollments status、dateLastModified、rolestatus, dateLastModified, role /schools/{school_id}/enrollments? filter = role = ' student '/schools/{school_id}/enrollments? filter = dateLastModified> ' 2018-01-25T03:22: 28.204 Z ' AND role = ' 教師 '/schools/{school_id}/enrollments?filter=role='student'/schools/{school_id}/enrollments?filter=dateLastModified>'2018-01-25T03:22:28.204Z' AND role='teacher'
getClassgetClass /classes/{class_id}/classes/{class_id}
getEnrollmentgetEnrollment /enrollments/{enrollment_id}/enrollments/{enrollment_id}
getStudentgetStudent /students/{student_id}/students/{student_id}
getTeachergetTeacher /teachers/{teacher_id}/teachers/{teacher_id}
getTermgetTerm /terms/{term_id}/terms/{term_id}

有用的附注和秘訣Helpful Notes and Tips

  1. 端點一定會晚 https://{server_URL}/ims/oneroster/v1p1The endpoints always come after https://{server_URL}/ims/oneroster/v1p1

  2. {school_id} 和 {term_id} 對應于設定檔建立中所選取之每個學校或字詞的 sourcedId 屬性。{school_id} and {term_id} correspond to the sourcedId property of each school or term that was selected in profile creation.

  3. 所有端點都必須支援分頁,例如限制及位移參數 (ex: limit = 10&位移 = 20) 。All endpoints must support paging, i.e., limit and offset parameters (ex: limit=10&offset=20).

  4. 某些端點的篩選參數支援要求允許依狀態篩選,或啟用 [增量同步處理]。這些會包含在表格中。Some endpoints have requirements on filter parameter support to allow filtering by status, or to enable delta sync. Those are included in the table.

  5. SDS 利用 dateLastModified 屬性上的篩選,以進行增量同步/增量同步處理,以及與 SDS 整合所需。SDS leverage a filter on the dateLastModified property for delta sync / incremental sync processing, and is required for integration with SDS.

  6. 提供者必須選擇實現 OAuth1 () 或 OAuth 2.0 (用戶端認證授與) 驗證配置。Providers must choose to implement either OAuth1(a) or OAuth 2.0 (Client Credentials Grant) authentication scheme. OAuth 2.0 是可取的。OAuth 2.0 is preferred.

  7. 在開發過程中,您可以使用 Postman 集合來驗證您的端點。During development you can verify your endpoints with our Postman Collection.

  8. 如果支援的驗證通訊協定為 "OAuth 2"-用戶端認證授與類型,School Data Sync 會在 "Authorization" 標頭中傳送認證。If authentication protocol supported is "OAuth 2" - Client Credentials Grant type, School Data Sync would send the credentials in "Authorization" Header. SDS 不支援在要求正文中傳送認證。SDS does not support sending the credentials in request body.

測試 APIsTesting the APIs

使用 Postman 集合測試您的 APIsTest your APIs using Postman collection

Postman 是眾所周知的工具,可執行和管理 REST APIs。Postman is a well-known tool to run and manage REST APIs. 我們已建立 OneRoster® API 集合,以叫用並測試 SDS 所需 OneRoster APIs。We have created OneRoster® API collection to invoke and test the OneRoster APIs required by SDS. 這裡下載並執行 OneRoster® postman 集合。Download and run the OneRoster® postman collection available here. 執行集合會呼叫 SDS 所需的所有 APIs,並對傳回的資料執行簡單測試。Running the collection invokes all the APIs required by SDS and runs simple tests against the data returned.

在沙箱環境中測試 SDS 工程Test with SDS Engineering against a sandbox environment

為 OneRoster®建立沙箱環境 APIs 並與指定的 SDS 工程師共用認證。Create a sandbox environment for the OneRoster® APIs and share the credentials with your designated SDS engineer. 我們將執行一組更深入的測試,以確保整合成功。Together, we will run a deeper set of tests to ensure integration is successful.

設定完整同步以驗證解決方案 E2EConfigure a full sync to validate the solution E2E

所有測試都成功時,請在測試 O365 租使用者上建立 SDS 同步處理設定檔,以同步處理 OneRoster 端點中的資料,並確認已完成同步處理但沒有錯誤。When all the tests have succeeded, create an SDS sync profile on your test O365 tenant to sync data from your OneRoster endpoints, and ensure sync completed without errors. 可使用建立 OneRoster 同步處理設定檔的指示。Instructions to create an OneRoster sync profile are available here. 當您選取 OneRoster®提供者時,請選取 [其他] 選項。When you select the OneRoster® provider, select the "Other" option. 如果您看到任何錯誤或問題,請呈報至您的學校資料同步工程師。If you see any errors or issues, please escalate to your School Data Sync Engineer.

試驗Pilot

測試順利完成之後,就可以開始試驗客戶的解決方案。Once testing has completed successfully, it’s time to start piloting the solution with customers. 您的系統名稱將會新增至 School Data Sync 的 OneRoster®提供者清單中,而且將會對「flighted」 Office 365 EDU 承租人(已同意試驗整合)顯示。Your System’s name will be added to the list of OneRoster® providers in School Data Sync and will be visible to “flighted” Office 365 EDU tenants which have agreed to pilot the integration. SDS 團隊和 OneRoster®提供者小組會共同運作,以識別適當的試驗客戶,並使用 OneRoster® API 整合,安排部署 SDS 的時間。The SDS team and the OneRoster® provider team will work together to identify the appropriate pilot customers and schedule a time to deploy SDS using OneRoster® API integration. 我們將與客戶密切合作,以確保資料同步處理成功,並驗證結果與提供者及客戶。We will work closely with customers to ensure the data sync is successful and validate the results along with the provider and customers. 任何識別出的最後一個錯誤,都是在讓所有 Office 365 教育版客戶正式使用解決方案之前進行處理。Any final bugs identified will be addressed prior to making the solution generally available to all Office 365 Education customers.

公開Go Public

當我們有兩個客戶成功完成其試驗部署時,合作夥伴系統將可在學校資料同步處理成為已驗證的來源系統。Once we have two customers successfully complete their pilot deployments, the partner system will be made available in School Data Sync as a certified source system. 在安裝期間,SDS 會向所有使用者顯示提供者名稱。SDS will display the provider name to all the users during setup. SDS 小組也會在我們的 ONEROSTER API 整合系統網站上記錄合作夥伴系統。The SDS team will also document the partner system on our OneRoster API integrated systems site. 整合也會在我們的 SDS 產品網站上反映。The integration will also be reflected on our SDS product site. 為做到這一點,SDS 小組將需要:To do this, the SDS team will need:

  • 公司標誌Company logo
  • 軟體的最低版本Minimum Version of Software
  • 設定必要條件Configuration Prerequisites
  • 如何取得用戶端識別碼、用戶端密碼及 URL (s) How to get Client ID, Client Secret, and URL(s)
  • 任何其他特定指示Any other specific instructions
  • 要取得協助的人員Who to contact for help

SDS 小組也會與合作夥伴系統小組合作,透過各種行銷管道提升整合。The SDS team will also work with the partner system team to promote the integration more broadly through various marketing channels.

年級同步處理整合的 API 指導方針API Guidance for Grade Sync Integration

  1. 請遵循上述步驟完成與 SDS 的整合。Finalize integration with SDS following the steps above.

  2. 若尚未提供其他 OneRoster 1.1 端點,請加以實施。Implement additional OneRoster v1.1 endpoints if they are not already available.

  3. 與 Microsoft 共同認可此功能。Commit to co-own this with Microsoft.

為什麼要與 SDS 進行整合才能進行評分同步處理Why integration with SDS is necessary for Grade Sync

雖然年級同步處理是從 Microsoft 和團隊向您的 SIS 中取得工作分派和分級,但 SDS 已將您的名單資訊帶入 Microsoft。While it is true that Grade Sync is about getting assignments and grades out of Microsoft and Teams into your SIS, SDS is what brings your roster information into Microsoft. 這是必要的動作,因為它允許年級同步處理 Office 365 租使用者與 SIS 之間的完美運作。This is required as it allows Grade Sync to work seamlessly between an Office 365 Tenant and your SIS. 年級同步處理取決於 SDS 中同步處理設定檔所保存的身分識別及其同步記錄。Grade Sync relies on the identities and their sync records persisted by the Sync Profile in SDS.

執行其他 OneRoster 1.1 端點Implement additional OneRoster v1.1 endpoints

將 SIS 資料的初始整合到 SDS 需要數個 OneRoster 1.1 端點時,需要進行其他存取才能同步處理評分資料。While the initial integration of SIS data into SDS requires several OneRoster v1.1 endpoints, additional access is required to sync grade data. 除了此頁面先前所列的端點,還需要下列端點。The below endpoints are required in addition to those listed earlier on this page. 當下列端點是特別需要的端點時,建議您執行所有的表 3.1 (名冊登記) 和 table 3.1 c (Gradebook) 。While the below endpoints are what is specifically required, we recommend implementing all of Table 3.1a (Rostering) and table 3.1c (Gradebook). 如需端點的完整詳細資訊,請流覽 ONEROSTER API 最終規格 頁面。Please visit the OneRoster API Final Specifications page for full detailed information on the endpoints.

動作Action [URL]****URL 方法Methods
課程的學生Students for a Class /classes/{class_id}/students/classes/{class_id}/students GETGET
類別的教師Teachers for a Class /classes/{class_id}/teachers/classes/{class_id}/teachers GETGET
所有教師All Teachers /teachers/teachers GETGET
教師的類別Classes for a Teacher /teachers/{teacher_id}/classes/teachers/{teacher_id}/classes GETGET
所有使用者All users /users/users GETGET
類別的所有行專案All Line Items for a Class /classes/{class_id}/lineItems/classes/{class_id}/lineItems GETGET
單一行專案的結果Results for a single Line Item /classes/{class_id}/lineItems/{lineitem_id}/results/classes/{class_id}/lineItems/{lineitem_id}/results GETGET
特定類別中單一學生的結果Results for a single Student in a specific Class /classes/{class_id}/students/{student_id}/results/classes/{class_id}/students/{student_id}/results GETGET
更新特定行專案Update specific Line Item /lineItems/{lineitem_id}/lineItems/{lineitem_id} PUT
更新特定結果Update specific result /results/{result_id}/results/{result_id} PUT

使用 OneRoster 的標準是一種方式,讓等級同步處理成為我們所有客戶的需求。Working with standards like OneRoster is the only way to make a feature such as Grade Sync scalable to all of our customers' needs.

有用的附注和秘訣Helpful Notes and Tips

  1. {lineitem_id} 和 {result_id} 對應于每個行專案或所傳回結果的 sourcedId 屬性。{lineitem_id} and {result_id} correspond to the sourcedId property of each line item or result that is being returned.

  2. 某些端點在篩選參數支援上有需求,允許透過電子郵件和 sourcedId 進行篩選。Some endpoints have requirements on filter parameter support to allow filtering by email and sourcedId.

  3. 提供者必須執行 OAuth1 () 授權配置,這是目前 GradeSync 唯一支援的配置。Providers must implement OAuth1(a) authorization scheme which is the only supported scheme by GradeSync currently.

  4. 在開發過程中,您可能會考慮使用我們的 Postman 集合來驗證您的端點。During development you may consider verifying your endpoints with our Postman Collection.

測試 APIsTesting the APIs

我們已使用 GradeSync 需求更新 OneRoster® API Postman 集合。We have updated the OneRoster® API Postman Collection with GradeSync requirements. 除了 SDS 之外,更新後的集合也會呼叫 GradeSync 的所有 APIs。The updated Collection invokes all APIs for GradeSync in addition to SDS. 它會在每次執行時建立新的工作分派並為其新增評分。It creates a new assignment and adds a grade to it, upon every execution. 下載並執行 OneRoster® 1.1-OAuth1。 Postman 集合可用於 這裡Download and run the OneRoster® V1.1-OAuth1.a Postman collection available here.

請注意,集合呼叫會在建立的工作分派和分數上刪除,以用於清除目的。Note that the Collection calls DELETE on created Assignments and Grades for cleanup purposes. 不過,執行刪除 APIs 完全選用,因為 GradeSync 目前並未使用。However, implementing DELETE APIs is completely optional as they aren't currently used by GradeSync.

與 Microsoft 認可以共同擁有Commit to co-own this with Microsoft

建立與您的 Microsoft 連絡人的合約,以負責這項共同作業的下列方面:Create an agreement with your Microsoft contact to be accountable for the following aspects of this collaboration:

  • 測試環境:這包括為 Microsoft 提供實際執行的測試環境,該測試環境在啟動日期之後仍可運作。Test environment: This includes furnishing Microsoft with a production-like test environment that will remain functional beyond launch date.

  • 共同開發:這包括在啟動之前及之後協助解決開發及測試問題。Co-development: This includes helping solve dev and test problems before and after launch.

  • 共同服務:這包括協助解決重要的客戶問題,包括針對嚴重性為1問題的上報途徑,已取得回應方,以處理即時網站問題。Co-servicing: This includes helping solve critical customer issues, including having an escalation path for Severity 1 issues that has responsive parties to deal with live site issues.

  • 共同行銷與共同推廣:這包括與您社區的適當通訊,以協助我們產生有關啟動的興奮。Co-marketing and co-promotion: These include appropriate communications to your community to help us generate excitement about the launch.

當我們共同運作時,我們的所有客戶都會成功。All our customers succeed when we work together.