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' 的欄位數據,註明的欄位 「否」是「選擇性」數據。 標示為「必要」的字段標頭必須存在於提供的檔案中,否則將不會被接受。 如果未傳遞對應的選擇性數據,則標記為「選擇性」的欄位標頭不需要出現在檔案中。
在 [數據類型] 數據列中標示已定義列舉值的欄位,有一組其支援的特定值。 列舉欄位支援的預設值集 ,請參閱預設值清單。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
sourcedId | 是 | 10001 | 唯一標識碼 |
name | 是 | 工程學院 | 字串 |
類型 | 是 | 大學 | Enum |
parentSourcedId | 否 | 10000 | 唯一標識碼 |
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
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 不再用來提供建立新用戶的默認密碼。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
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』。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
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 檔案的相依性。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
classSourcedId | 是 | 12001 | 唯一標識碼 |
userSourcedId | 是 | 14001 | 唯一標識碼 |
角色 | 是 | 學生 | Enum |
- 這需要使用 『classSourcedId』 欄位參考相關聯的類別。 這會產生對 classes.csv 檔案的相依性。
- 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
提交 | 必要? | 範例 | 資料類型 |
---|---|---|---|
sourcedId | 是 | FS2021 | 唯一標識碼 |
title | 是 | 秋季半年度 | 字串 |
類型 | 是 | 學期 | Enum |
schoolYear | 是 | 2021 | Enum |
startDate | 是 | 2020-08-24 | Date |
endDate | 是 | 2020-12-11 | Date |
- 預期會以ISO8601格式提供日期值。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
sourcedId | 是 | C12001 | 唯一標識碼 |
orgSourcedId | 是 | 10001 | 唯一標識碼 |
title | 是 | 計算機科學 101 | 字串 |
code | 否 | CS101 | 字串 |
schoolYearSourcedId | 否 | Y2021 | 唯一標識碼 |
主題 | 否 | 10 | Enum |
年級 | 否 | 本科 | Enum |
- 這需要使用 orgSourcedId 字段 (組織) 參考相關聯的組織。 這會產生對 orgs.csv 檔案的相依性。
- 如果通過:這需要使用 'schoolYearSourcedId' 字段參考相關聯的學術會話年記錄,其中類型 = schoolYear。 這會產生對 academicSessions.csv 檔案的相依性。
- 等級列舉的傳入值遺漏前置零 『0』,例如 『1』,會符合定義的值清單 (列舉) 『01』,並且會儲存為 『01』。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
userSourcedId | 是 | 14001 | 唯一標識碼 |
relationshipUserSourcedId | 是 | P14001 | 唯一標識碼 |
relationshipRole | 是 | 監護人 | Enum |
- 如果您也要將聯繫人關聯性同步 (守護者) ,則必須在 users.csv 中包含其記錄。
- 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
- 這需要使用 『relationshipUserSourcedId』 字段來參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
- 此外,具有聯繫人關係角色的使用者需要familyName、givenName和電子郵件。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
userSourcedId | 是 | 14001 | 唯一標識碼 |
性 | 否 | 雄 | Enum |
生日 | 否 | 2001-07-20 | Date |
birthCity | 否 | 馬羅維斯 | 字串 |
birthState | 否 | WA | Enum |
birthCountry | 否 | 美國 | 字串 |
ethnicityCodes | 否 | 函式orLatinoEthnicity | Enum[] |
raceCodes | 否 | demographicRaceTwoOrMoreRaces | Enum[] |
- 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。
- 對應至 『raceCodes』 的多個值應該結合成單一字串,並以引弧括住值,並以逗號分隔。
欄位 | 必要? | 範例 | 資料類型 |
---|---|---|---|
userSourcedId | 是 | 14001 | 唯一標識碼 |
旗 | 是 | lep | Enum |
- 這需要使用 『userSourcedId』 欄位參考相關聯的使用者。 這會產生對 users.csv 檔案的相依性。