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

簡介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. 本檔旨在協助 OneRoster® Api 的任何新提供者順利與 School Data Sync 整合。下列上架程式會定義 API 提供者在加入 School Data Sync 入口網站之前所需執行的步驟。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. 使用Postman 集合測試您的 api。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

關於學校資料同步處理About 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.

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

  • 如果您想要將您的系統與學校資料同步處理和 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 規格 for Core 名冊登記。 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.

建議使用 IMS 通用的提供者認證, 但不需要它。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? filter = schoolYear = ' 2019 ' 和 status = ' active '/academicSessions?filter=schoolYear='2019' AND status='active'
getAcademicSessiongetAcademicSession
/academicSessions/{academicSession_id}/academicSessions/{academicSession_id}


getAllUsersgetAllUsers
/users/users
狀態、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
狀態、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
狀態、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
狀態、dateLastModifiedstatus, dateLastModified
/schools/{school_id}/students?/schools/{school_id}/students?
filter = dateLastModified> ' 2018-01-25T03:22: 07.209 Z 'filter=dateLastModified>'2018-01-25T03:22:07.209Z'
getTeachersForSchoolgetTeachersForSchool
/schools/{school_id}/teachers/schools/{school_id}/teachers
狀態、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'
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
/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. 所有端點都必須支援分頁, 例如, 限制和位移參數 (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 (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. 在開發期間, 您可以使用我們的Postman 集合來驗證您的端點。During development you can verify your endpoints with our Postman Collection.

  8. 如果支援的驗證通訊協定是「OAuth 2」-用戶端認證授與類型, School Data SYnc 會在「授權」標頭中傳送認證。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.

測試 ApiTesting the APIs

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

Postman 是一個已知的工具, 可以執行和管理 REST Api。Postman is a well-known tool to run and manage REST APIs. 我們已建立 OneRoster® API 集合, 以叫用並測試 SDS 所需的 OneRoster Api。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 所需的所有 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.

設定完整同步處理以驗證方案 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. 如果您看到任何錯誤或問題, 請升級至您的 School Data Sync 工程師。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. 您的系統名稱將會新增至 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 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.