SDS V2.1 CSV 檔案格式

您可以使用 CSV (以逗號分隔的值) SDS V2.1 格式的檔案,將您的學校資訊系統 (SIS) 與 Office 365 同步。 使用 SDS V2.1 CSV 檔案格式來擷取數據類別,可讓您亮起用於布建的核心 SDS 功能。 它也可協助您增強Microsoft 365產品和功能的體驗。 SDS V2.1 CSV 檔案格式會繼續擴充其支援的數據類別。

如果您使用 SDS V2.1 格式,則必須適當地格式化檔案。 上傳檔案,其名稱完全如詳細。 數據行標頭會區分大小寫。 CSV 檔案必須是UTF-8格式且符合 RFC 規範。 此外,我們不接受傳入數據中的換行符。 若要檢閱和下載 SDS V2.1 CSV 檔案的範例集,請 參閱 SDS GitHub 存放庫

重要

在建立輸入流程期間初始上傳之後,無論選擇性檔案中是否進行數據變更,您都必須一律為後續上傳提供相同的檔案集。 如果您未這麼做,系統會判斷記錄已不再作用中,而且會將它們標示為這類記錄。

必要:必須提供下列三個檔案。 如果您只管理使用者而非類別,則只需要提供這些檔案。 

  • orgs.csv

  • users.csv

  • roles.csv

選擇性/必要:如果您只管理使用者,則不需要下列兩個檔案。 如果您也管理類別和類別註冊,您必須提供下列兩個檔案,以及上述三個檔案。

  • classes.csv

  • enrollments.csv

選擇性:下列是選擇性檔案,可用來增強體驗。 除非上述檔案有以下列附註為基礎的數據參考,否則不需要這些檔案。 

  • academicSessions.csv (如果您的 roles.csv、classes.csv 或 courses.csv 包含學術會話數據,則應該提供對應的數據以避免在處理數據時收到錯誤訊息。)

  • courses.csv (如果您的 classes.csv 數據包含課程的連結,則應該提供對應的數據以避免在處理數據時收到錯誤訊息。)

  • demographics.csv

  • userFlags.csv

  • relationships.csv

每個 CSV 檔案都必須包含 'Required' 底下註明 'Yes' 的欄位數據,註明的欄位 「否」是「選擇性」數據。 標示為「必要」的字段標頭必須存在於提供的檔案中,否則將不會被接受。 如果未傳遞對應的選擇性數據,則標記為「選擇性」的欄位標頭不需要出現在檔案中。

在 [數據類型] 數據列中標示已定義列舉值的欄位,有一組其支援的特定值。 列舉欄位支援的預設值集 ,請參閱預設值清單

orgs.csv

欄位 必要? 範例 資料類型
sourcedId 10001 唯一標識碼
name 工程學院 字串
類型 大學 Enum
parentSourcedId 10000 唯一標識碼

users.csv

欄位 必要? 範例 資料類型
sourcedId 14001 唯一標識碼
username cbeane@domain.com 字串
familyName 只有在建立使用者) 時,才 ( 克雷格 字串
givenName 只有在建立使用者) 時,才 ( Beane 字串
activeDirectoryMatchId craig.beane@domain.com 字串
電子郵件 cbeane@domain.com 電子郵件
電話 +1234567890 Phone
短信 +1234567890 Phone
userNumber 14001 字串
  • 如果使用者使用 [建立不相符的使用者] 選項,則需要familyName和 givenName。
  • 如果針對在 relationships.csv 中具有聯繫人關係角色的使用者使用 [學生聯繫人關聯] 選項,則使用者需要familyName、givenName和電子郵件。 身為員工但也是聯繫人的使用者,建議他們列出兩筆用戶記錄,以及與其私人電子郵件地址相關聯的聯繫人用戶記錄。
  • 預期電話和簡訊欄位會根據E.164標準進行格式化,其中加號會使用加號並由電話號碼成功,或是加上加上字元,後面接著國家/地區代碼、區碼、電話前綴和行號。
  • password 不再用來提供建立新用戶的默認密碼。

roles.csv

欄位 必要? 範例 資料類型
userSourcedId 14001 唯一標識碼
orgSourcedId 10001 唯一標識碼
角色 學生 Enum
sessionSourcedId FS2021 唯一標識碼
年級 PS1 Enum
isPrimary 布林值
roleStartDate 2020-08-24 Date
roleEndDate 2020-12-11 Date
  • 需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
  • 需要使用 『orgSourcedId』 欄位的相關聯組織參考。 這會產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要參考相關聯的詞彙, (使用 'sessionSourcedId' 字段) 學術研討會。 這會產生對 academicSessions.csv 檔案的相依性。
  • isPrimary 指出此角色是否為該組織的主要 (true) 或次要 (false) 角色。如果傳遞多個角色,針對相同的使用者和相同的組織,應該會有一個且只有一個主要角色設定為 (每個組織的實際) 。
  • 要以ISO8601格式提供的日期值。
  • 等級列舉的傳入值遺漏前置零 『0』,例如 『1』,會符合定義的值清單 (列舉) 『01』,並且會儲存為 『01』。

classes.csv

欄位 必要? 範例 資料類型
sourcedId 12001 唯一標識碼
orgSourcedId 10001 唯一標識碼
title 計算機科學 101 字串
sessionSourcedIds FS2021 唯一標識碼[]
courseSourcedId C12001 唯一標識碼
code 12001 字串
  • 這需要使用 『orgSourcedId』 欄位參考相關聯的學校 (組織) 。 這會產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要參考相關聯的詞彙 (學術研討會) 使用 'sessionSourcedIds' 字段。 這會產生對 academicSessions.csv 檔案的相依性。
  • 如果通過:如果某個類別與同一學年的多個會話相關聯,例如秋季半年度和 Spring Fiscal,您可以為記錄上的會話提供這兩個 sourcedId。 值應該結合成單一字串,並以引號括住並以逗號分隔值。
    • 與多個 sessionSourcedIds 的關聯只會儲存在 Data Lake 中。
    • 會話標識碼的 Microsoft 365 群組延伸模組屬性不支援多個關聯。
  • 如果通過:這需要使用 『courseSourcedId』 字段參考相關聯的課程。 這會產生對 courses.csv 檔案的相依性。

enrollments.csv

欄位 必要? 範例 資料類型
classSourcedId 12001 唯一標識碼
userSourcedId 14001 唯一標識碼
角色 學生 Enum
  • 這需要使用 『classSourcedId』 欄位參考相關聯的類別。 這會產生對 classes.csv 檔案的相依性。
  • 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。

academicSessions.csv

提交 必要? 範例 資料類型
sourcedId FS2021 唯一標識碼
title 秋季半年度 字串
類型 學期 Enum
schoolYear 2021 Enum
startDate 2020-08-24 Date
endDate 2020-12-11 Date
  • 預期會以ISO8601格式提供日期值。

courses.csv

欄位 必要? 範例 資料類型
sourcedId C12001 唯一標識碼
orgSourcedId 10001 唯一標識碼
title 計算機科學 101 字串
code CS101 字串
schoolYearSourcedId Y2021 唯一標識碼
主題 10 Enum
年級 本科 Enum
  • 這需要使用 orgSourcedId 字段 (組織) 參考相關聯的組織。 這會產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要使用 'schoolYearSourcedId' 字段參考相關聯的學術會話年記錄,其中類型 = schoolYear。 這會產生對 academicSessions.csv 檔案的相依性。
  • 等級列舉的傳入值遺漏前置零 『0』,例如 『1』,會符合定義的值清單 (列舉) 『01』,並且會儲存為 『01』。

relationships.csv

欄位 必要? 範例 資料類型
userSourcedId 14001 唯一標識碼
relationshipUserSourcedId P14001 唯一標識碼
relationshipRole 監護人 Enum
  • 如果您也要將聯繫人關聯性同步 (守護者) ,則必須在 users.csv 中包含其記錄。
  • 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
  • 這需要使用 『relationshipUserSourcedId』 字段來參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
  • 此外,具有聯繫人關係角色的使用者需要familyName、givenName和電子郵件。

demographics.csv

欄位 必要? 範例 資料類型
userSourcedId 14001 唯一標識碼
Enum
生日 2001-07-20 Date
birthCity 馬羅維斯 字串
birthState WA Enum
birthCountry 美國 字串
ethnicityCodes 函式orLatinoEthnicity Enum[]
raceCodes demographicRaceTwoOrMoreRaces Enum[]
  • 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
  • 對應至 『raceCodes』 的多個值應該結合成單一字串,並以引弧括住值,並以逗號分隔。

userFlags.csv

欄位 必要? 範例 資料類型
userSourcedId 14001 唯一標識碼
lep Enum
  • 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。