在 SDS 中的上架 OneRoster® API 提供者Onboarding OneRoster® API providers in SDS

簡介Introduction

Microsoft School Data Sync 可以同步處理身分識別和名冊任何實作的 IM OneRoster® API 標準的系統資訊。Microsoft School Data Sync can synchronize identity and roster information from any system that implements the IMS OneRoster® API standard. 本文件旨在協助成功整合 School Data Sync 的 OneRoster® api 的任何新提供者。下列的上架程序定義之前即可將它們新增至 School Data Sync 入口網站,API 提供者所需的步驟。This document is intended to help any new providers of OneRoster® APIs to successfully integrate with School Data Sync. The following onboarding process defines the steps required by the API provider before they can be added into the School Data Sync portal.

程序的概觀:Overview of the Process:

  1. 完成SDS 合作夥伴註冊表單上的表單。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. 測試您使用我們郵差集合的 Api。Test your APIs using our 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 Docs 網站For technical information regarding SDS, including deployment videos and admin guidance, go to the SDS Docs site.

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

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

實用資源Useful Resources

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

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

我們建議憑證的全域 IM、 的提供者,但不是需要它。We suggest certification of the provider with the IMS Global, but do not require it.

適用於 School Data Sync 的必要的 API 端點Required API Endpoints for School Data Sync

ActionAction URLURL 必要的篩選器屬性Required Filter Properties 範例Examples
getAllAcademicSessionsgetAllAcademicSessions
/academicSessions/academicSessions
schoolYear 狀態schoolYear, status
/academicSessions? 篩選 = schoolYear = '2019' 與狀態 = 'active'/academicSessions?filter=schoolYear='2019' AND status='active'
getAcademicSessiongetAcademicSession
/academicSessions/ {academicSession_id}/academicSessions/{academicSession_id}


getAllUsersgetAllUsers
/users/users
狀態 dateLastModifiedstatus, dateLastModified
/ 學校? 篩選 = 狀態 = 'active' 與 dateLastModified>' 2018年-01-25T03:22:03.297Z'/schools?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getUsergetUser
/users/ {user_id}/users/{user_id}


getAllSchoolsgetAllSchools
/schools/schools
狀態 dateLastModifiedstatus, dateLastModified
/users? 篩選 = 狀態 = 'active' 與 dateLastModified>' 2018年-01-25T03:22:03.297Z'/users?filter=status='active' AND dateLastModified>'2018-01-25T03:22:03.297Z'
getSchoolgetSchool
/schools/ {school_id}/schools/{school_id}


getClassesForSchoolgetClassesForSchool
/schools/ {school_id} / 類別/schools/{school_id}/classes
狀態 dateLastModifiedstatus, dateLastModified
/schools/{school_id}/classes?filter=dateLastModified>'2018-01-25T03:22:07.209Z'/schools/{school_id}/classes?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getStudentsForSchoolgetStudentsForSchool
/schools/ {school_id} / 學生/schools/{school_id}/students
狀態 dateLastModifiedstatus, dateLastModified
/schools/ {school_id} / 學生嗎?/schools/{school_id}/students?
篩選器 = dateLastModified>' 2018年-01-25T03:22:07.209Z'filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getTeachersForSchoolgetTeachersForSchool
/schools/ {school_id} / 教師/schools/{school_id}/teachers
狀態 dateLastModifiedstatus, dateLastModified
/schools/{school_id}/students?filter=dateLastModified>'2018-01-25T03:22:07.209Z'/schools/{school_id}/students?filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getEnrollmentsForSchoolgetEnrollmentsForSchool
/schools/ {school_id} / 註冊/schools/{school_id}/enrollments
狀態、 dateLastModified、 角色status, dateLastModified, role
/schools/{school_id}/enrollments?filter=role='student'/schools/{school_id}/enrollments?filter=dateLastModified>'2018-01-25T03:22:28.204Z ' 與角色 = '教師'/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
/teacher/ {teacher_id}/teacher/{teacher_id}


getTermgetTerm
/terms/ {term_id}/terms/{term_id}

很有幫助的附註及秘訣:Helpful Notes and Tips:

  1. 端點一律來自 「 https://{server_URL}/ims/oneroster/v1p1 」 之後The 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. 所有的端點必須支援分頁,亦即,限制和位移的參數 (例如: 限制 = 10&offset = 20)。All endpoints must support paging, i.e., limit and offset parameters (ex: limit=10&offset=20).

  4. 某些端點有篩選參數支援要允許使用者篩選狀態,或若要啟用透過 [delta 同步處理需求。這些資料表中所含。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 利用透過 [delta 同步處理 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(a) 或 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. 在開發期間,您可以驗證您與我們郵差集合的端點。During development you can verify your endpoints with our Postman Collection.

測試 ApiTesting the APIs

測試您使用我們郵差工具的 ApiTest your APIs using our Postman tool

郵差是已知的工具,以執行和管理 REST Api。Postman is a well-known tool to run and manage REST APIs. 我們已建立叫用和測試所需的 SDS 的 OneRoster Api 的 OneRoster® API 集合。We have created OneRoster® API collection to invoke and test the OneRoster APIs required by SDS. 下載並執行 OneRoster® 郵差集合提供以下Download and run the OneRoster® postman collection available here. 執行集合叫用 SDS 所需的所有 Api,並對傳回的資料執行簡單的測試。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® Api 建立沙箱環境,並與您指定的 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.

設定為驗證解決方案 E2E 完整的同步處理Configure 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 piloting the solution with customers. 您的系統名稱會新增至 OneRoster® School Data Sync 中的提供者清單,並將會看到 「 flighted 」 的同意試驗整合 Office 365 教育租用戶。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® 提供者小組,則會找出適當的試驗客戶及排定一次部署 SDS 使用 OneRoster® API 整合共同運作。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 customer 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

一旦我們已成功地完成其試驗部署的解決方案 2 的客戶,協力廠商系統將可供 School Data Sync 中做為認證的來源系統。Once we have 2 customers successfully complete their pilot deployments of the solution, 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.