SDS V2.1 CSV 檔案格式

您可以使用 CSV (逗號分隔的值) 檔案,以 SDS) (V2.1 格式將學校資訊系統與 Office 365 同步處理 SIS) (SIS 。 使用 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 檔案都必須包含「必要」下註明為「是」欄位的資料,註明為「否」的欄位為「選用」資料。 標示為「必要」的欄位標頭必須存在於提供的檔案中,否則將不會接受這些欄位標頭。 如果未傳遞對應的選擇性資料,則不需要在檔案中存在標示為「選擇性」的欄位標頭。

具有「資料類型」欄中標記的已定義列舉值的欄位具有它們支援的特定值集。 列舉欄位支援的預設值集 請參閱預設值清單。

orgs.csv

欄位 必要? 範例 資料類型
來源dId 是 10001 唯一 ID
name 是 工學院 字串
類型 是 學院 Enum
parentSourcedId 否 10000 唯一 ID

users.csv

欄位 必要? 範例 資料類型
來源dId 是 14001 唯一 ID
用戶名 是 cbeane@domain.com 字串
familyName (家族名稱) 是 (僅在建立使用者) 時 克雷格 字串
givenName 是 (僅在建立使用者) 時 比恩 字串
activeDirectoryMatchId 否 craig.beane@domain.com 字串
電子郵件 否 cbeane@domain.com 電子郵件
電話 否 +1234567890 Phone
簡訊 否 +1234567890 Phone
使用者編號 否 14001 字串
  • 如果使用「建立不相符的使用者」選項,則使用者需要 familyName 和 givenName。
  • 如果對在 relationships.csv 中具有連絡關係角色的使用者使用「學生連絡人關聯」選項,則使用者需要 familyName、givenName 和電子郵件。 對於員工和連絡人的使用者,我們建議他們列出兩個使用者記錄,並將連絡人使用者記錄與其私人電子郵件地址相關聯。
  • 預計電話和簡訊欄位將根據 E.164 標準進行格式化。 加號字元後面跟著電話號碼,或者加號字元後面跟著國家/地區代碼、區號、電話字首和線路號碼。
  • password 不再用來提供建立新使用者的預設密碼。

roles.csv

欄位 必要? 範例 資料類型
userSourcedId 是 14001 唯一 ID
orgSourcedId 是 10001 唯一 ID
角色 是 學生 Enum
sessionSourcedId 否 FS2021 唯一 ID
級 否 PS1的 Enum
是主要 否 實 布林值
角色開始日期 否 2020-08-24 Date
角色結束日期 否 2020-12-11 Date
  • 需要使用 'userSourcedId' 欄位參考相關聯的使用者,並產生 users.csv 檔案的相依性。
  • 需要使用 'orgSourcedId' 欄位對相關聯組織的參考,並產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要使用 'sessionSourcedId' 欄位) 參考學術會議 (相關術語,並產生對 academicSessions.csv 檔案的依賴關係。
  • isPrimary 指出此角色是該組織的主要 (true) ,還是次要 (false) 角色。如果傳遞多個角色,則針對相同的使用者和相同的組織,應該有一個且只有一個主要角色,為每個組織設定 (真實) 。
  • 日期值將以ISO8601格式提供。
  • 年級列舉的傳入值缺少前導零“0”,例如,“1”將匹配定義的列舉 (值列表) “01”,並存儲為“01”。

classes.csv

欄位 必要? 範例 資料類型
來源dId 是 12001 唯一 ID
orgSourcedId 是 10001 唯一 ID
title 是 計算機科學 101 字串
sessionSourcedIds 否 FS2021 唯一 ID[]
courseSourcedId 否 C12001 唯一 ID
code 否 12001 字串
  • 這需要使用 'orgSourcedId' 欄位) 參考相關聯的學校 (組織,並產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要使用 'sessionSourcedIds' 欄位) 對學術會議 (相關術語的引用,並產生對 academicSessions.csv 檔案的依賴關係。
  • 如果通過:如果班級與相同學年中的多個會話相關聯,例如秋季學期和春季學期,您可以為記錄上的會話提供兩個 sourcedId。 值應組合成單一字串,其中值以引號括住,並以逗號分隔。
    • 與多個 sessionSourcedId 的關聯只會儲存在 Data Lake 中。
    • 工作階段識別碼的 Microsoft 365 群組延伸模組屬性不支援多個關聯。
  • 如果通過:這需要使用 'courseSourcedId' 欄位對相關課程的引用,並產生對 courses.csv 檔案的依賴關係。

enrollments.csv

欄位 必要? 範例 資料類型
類別來源dId 是 12001 唯一 ID
userSourcedId 是 14001 唯一 ID
角色 是 學生 Enum
  • 這需要使用 'classSourcedId' 欄位對相關聯類別的引用,並產生對 classes.csv 檔案的依賴關係。
  • 這需要使用 'userSourcedId' 欄位對關聯使用者進行參考,並產生對 users.csv 檔案的依賴關係。

academicSessions.csv

欄位 必要? 範例 資料類型
來源dId 是 FS2021 唯一 ID
title 是 秋季學期 字串
類型 是 學期 Enum
學年 是 2021 Enum
開始日期 是 2020-08-24 Date
結束日期 是 2020-12-11 Date
  • 預期日期值會以ISO8601格式提供。

courses.csv

欄位 必要? 範例 資料類型
來源dId 是 C12001 唯一 ID
orgSourcedId 是 10001 唯一 ID
title 是 計算機科學 101 字串
code 否 CS101 字串
schoolYearSourcedId 否 2021年度 唯一 ID
主題 否 10 Enum
級 否 大學生 Enum
  • 這需要使用 orgSourcedId 欄位參照相關聯的組織 (組織) ,並產生對 orgs.csv 檔案的相依性。
  • 如果通過:這需要使用 'schoolYearSourcedId' 欄位來參考相關聯的學期年度記錄,其中類型 = schoolYear。 這會產生對 academicSessions.csv 檔案的相依性。
  • 年級列舉的傳入值缺少前導零“0”,例如,“1”將匹配定義的列舉 (值列表) “01”,並存儲為“01”。

relationships.csv

欄位 必要? 範例 資料類型
userSourcedId 是 14001 唯一 ID
關係UserSourcedId 是 編號 P14001 唯一 ID
關係角色 是 監護人 Enum
  • 如果您也同步處理 (監護人) 的聯絡人關係,則必須在 users.csv 中包含他們的記錄。
  • 這需要使用 'userSourcedId' 欄位對關聯使用者進行參考,並產生對 users.csv 檔案的依賴關係。
  • 這需要使用 'relationshipUserSourcedId' 欄位對關聯使用者進行參考,並產生對 users.csv 檔案的依賴關係。
  • 此外,具有「連絡人關係」角色的使用者需要 familyName、givenName 和 email。

demographics.csv

欄位 必要? 範例 資料類型
userSourcedId 是 14001 唯一 ID
性 否 男 Enum
出生日期 否 2001-07-20 Date
出生城市 否 伍登維爾 字串
出生狀態 否 WA Enum
出生國家 否 美國 字串
種族代碼 否 西班牙裔或拉丁裔種族 Enum
種族代碼 否 人口統計種族二或更多種族 Enum
  • 這需要使用 'userSourcedId' 欄位對關聯使用者進行參考,並產生對 users.csv 檔案的依賴關係。
  • 對應至 'raceCodes' 的多個值應合併為單一字串,其中值以引號括住並以逗號分隔。

userFlags.csv

欄位 必要? 範例 資料類型
userSourcedId 是 14001 唯一 ID
旗 是 萊普 Enum
  • 這需要使用 'userSourcedId' 欄位對關聯使用者進行參考,並產生對 users.csv 檔案的依賴關係。