SDS(School Data Sync)를 사용하는 OneRoster API 공급자에 대한 온보딩 지침

아티클
10/15/2024

소개

SDS(Microsoft 학교 데이터 동기화)는 인바운드 데이터 스트림에서 1EdTech OneRoster API(애플리케이션 프로그래밍 인터페이스) 표준을 구현하는 모든 시스템의 ID 및 명단 정보를 동기화할 수 있습니다. 이 문서는 OneRoster API의 모든 새 공급자가 SDS와 성공적으로 통합될 수 있도록 돕기 위한 것입니다. 고객은 REST 기반 OneRoster 1.1 API를 사용하여 공급자에 직접 연결할 수 있습니다. 다음 온보딩 프로세스는 테넌트가 SDS에서 선택하고 사용하기 위해 API 공급자를 추가하기 전에 필요한 단계를 정의합니다.

SDS 정보

SDS에 대해 자세히 알아보려면 SDS 제품 사이트로 이동합니다.
배포 비디오 및 관리자 지침을 포함하여 SDS에 대한 기술 정보는 SDS 설명서 사이트로 이동하세요.
OneRoster API와 데이터를 연결하는 고객 환경에 대한 자세한 내용은 OneRoster API를 사용하여 데이터 연결을 참조하세요.

개요

SDS 파트너 등록 양식에서 양식을 작성합니다.
1. 양식에서 데이터 동기화 통합 지원을 학교로 지정합니다.
2. 양식에 액세스하려면 등록해야 합니다. 자세한 내용은 Microsoft 파트너 네트워크 사이트를 방문하세요. SDS 및 Office 개발 리소스 액세스를 위한 별도의 양식을 제출해야 합니다.
SDS에 필요한 OneRoster API 엔드포인트를 구현합니다.

SDS는 델타 동기화/증분 동기화 처리를 위해 dateLastModified 속성에 대한 필터를 사용하며 SDS와 통합하는 데 필요합니다.
SDS가 OneRoster API 엔드포인트에서 작동하는지 확인합니다.
1. Postman 컬렉션을 사용하여 API를 평가합니다.
2. 샌드박스 환경에 대해 SDS 엔지니어링을 사용하여 테스트합니다.
3. 솔루션 E2E의 유효성을 검사하도록 SDS를 구성합니다.
두 명의 프로덕션 고객을 사용하여 솔루션을 파일럿합니다.
모든 Office 365 EDU 테넌트에서 커넥터를 SDS에서 일반적으로 사용할 수 있도록 합니다.

시작

OneRoster API를 새로 개발하는 경우 핵심 명단 작성에 대한 OneRoster API v1.1 사양을 따릅니다.
1EdTech를 사용하는 공급자로 인증하는 것이 좋지만 필요하지는 않습니다. 
SDS에서 지원하는 값의 기본 목록에 대한 자세한 내용은 기본값 목록을 참조하세요.

SDS에 필요한 API 엔드포인트

작업	URL	필수 필터 속성	선택적/권장 필터	예제
GetAllAcademicSessions	/academicSessions	상태	dateLastModified	/academicSessions?offset=0&limit=5000&filter=상태='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}'
GetAllOrgs	/orgs	상태	dateLastModified	/orgs?offset=0&limit=5000&filter=상태='active'/orgs?filter=dateLastModified>'{deltaDateTime}'
GetAllUsers	/사용자	상태	dateLastModified	/users?offset=0&limit=5000&filter=상태='active'/users?filter=dateLastModified>'{deltaDateTime}'
GetAllClasses	/클래스	상태	dateLastModified	/classes?offset=0&limit=5000&filter=상태='active'/classes?filter=dateLastModified>'{deltaDateTime}'
GetAllEnrollments	/등록	상태	dateLastModified	/enrollments?offset=0&limit=5000&filter=상태='active'/enrollments?filter=dateLastModified>'{deltaDateTime}'

SDS에 대한 선택적 API 엔드포인트

참고

인구 통계, 학생 연락처 관계 및 학생 사용자 플래그에 대한 선택적 데이터 조각의 경우 고객이 이 데이터를 포함하거나 포함하지 않을 수 있는 기능은 Microsoft에서 만들 공급자 프로필에서 지원되는 선택적 데이터 기능을 기반으로 합니다. 명시된 테스트 및 확인 단계에 따라 SDS를 사용하는 고객에 대해서도 이 데이터를 지원하도록 선택하면 추가 데이터를 포함하기 위해 켜기(기본값)가 선택됩니다. 원하는 경우 해제할 토글을 선택할 수 있습니다. 토글을 사용할 수 없는 경우 표시되었지만 꺼져 있고 상호 작용에 사용할 수 없는 경우 공급자 프로필이 현재 해당 데이터 제공을 지원하지 않습니다.

작업	URL	필수 필터 속성	선택적/권장 필터	예제
GetAllCourses	/코스	상태	dateLastModified	/courses?offset=0&limit=5000&filter=상태='active'/courses?filter=dateLastModified>'{deltaDateTime}'
GetAllDemographics	/인구 통계	상태	dateLastModified	/demographics?offset=0&limit=5000&filter=상태='active'/demographics?filter=dateLastModified>'{deltaDateTime}'

선택적 사용자 학생 연락처 관계

팁

SDS는 OneRoster API를 통해 명단 데이터가 제공되는 경우 CSV를 통해 학생 연락처 날짜를 로드하는 쪽을 지원하지 않으므로 모든 공급자가 OneRoster API 접근 방식을 사용하여 연락처 제공을 지원하는 것이 좋습니다.

학생 사용자에 대해 학생 연락처 관계를 지정하여 학생 부모 및 보호자와의 커뮤니케이션을 위한 교육자 환경을 개선할 수 있습니다. 연락처는 /users 엔드포인트와 함께 제공되는 더 많은 사용자이며 학생과의 연결은 '에이전트'에 있는 학생의 사용자 레코드에서 찾을 수 있습니다.

자세한 내용은 SDS에서 지원하는 지원되는 학생 연락처 관계 역할에 대한 기본 값 목록: 연락처 관계 역할을 참조하세요.
familyName, givenName 및 메일은 연락처/보호자 역할이 있는 사용자에게 필요합니다.
전화 및 SMS가 E.164에 있고 +가 포함되어야 합니다. (예: +1234567890).
역방향 데이터가 제공되면 연락처 관계 보호자 레코드에서 연락처 사용자 '에이전트' 필드의 학생에 이르기까지 이러한 레코드가 필터링됩니다.

선택적 사용자 인구 통계 플래그

학생 사용자가 프로그램 또는 코호트에 참여했음을 나타내기 위해 사용자 플래그를 지정할 수 있습니다. 사용자 플래그가 포함되거나(사용자의 경우 true인 경우) 해당되지 않는 경우 포함되지 않습니다.

플래그는 메타데이터 필드에서 사용자의 메타데이터 확장으로 지정됩니다. 이 방법은 키|microsoft.userFlags라는 키가 있는 값 쌍이며 쉼표로 구분된 목록으로 서식을 지정해야 합니다. 사용자 플래그는 순서대로 표시할 수 있으며 대/소문자를 구분하지 않습니다.

자세한 내용은 SDS에서 지원하는 사용자 플래그 값의 기본 목록에서 기본값 목록: 사용자 플래그를 참조하세요.

예:

{ 
  "user" : { 
   … 
   … 
    "metadata" : { 
     "microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“ 
    } 
}

데이터 일치 및 유효성 검사 규칙

데이터 일치 및 유효성 검사 규칙에 대한 자세한 내용은 유효성 검사 규칙 및 설명을 참조하세요.

중요

1EdTech당 데이터 요청 시 사용할 수 있는 데이터에 대해 데이터 개인 정보를 적용하는 것은 공급자의 책임입니다. 학교 데이터 동기화는 요청 시간에 따라 활성 데이터에 대한 요청을 만듭니다.

유용한 참고 사항 및 팁

엔드포인트는 항상 https URL {server_URL}/ims/oneroster/v1p1 다음에 표시됩니다.
모든 엔드포인트는 페이징, 즉 제한 및 오프셋 매개 변수(예: limit=10&offset=5000)를 지원해야 합니다.
엔드포인트에는 상태 필터링을 허용하거나 델타 동기화를 사용하도록 설정하기 위한 필터 매개 변수 지원에 대한 요구 사항이 있습니다.
고객은 '활성 상태' 옵션을 사용하도록 설정하는 방법 또는 학교 데이터 동기화에서 사용할 연결에 활성 데이터만 사용할 수 있도록 허용하는 방법을 알고 있습니다. 이렇게 하면 학년이 진행됨에 따라 활성 학년 및 세션에 대한 활성 데이터만 제공됩니다.
특정 학교가 SIS에서 SDS로 제공되는 데이터에 포함되지 않도록 하기 위해 고객은 SDS를 SIS에 연결하는 데 사용되는 연결/자격 증명에 대해 포함되는 학교를 구성하는 방법을 알고 있습니다.
SDS는 델타 동기화/증분 동기화 처리를 위해 dateLastModified 속성에 필터를 적용하며 SDS와 통합하는 데 필요합니다.
공급자는 OAuth 2.0 기본 설정인 OAuth1(a) 또는 OAuth 2.0(클라이언트 자격 증명 부여) 인증 체계를 구현하도록 선택해야 합니다.
개발하는 동안 Postman 컬렉션을 사용하여 엔드포인트를 확인할 수 있습니다.
지원되는 인증 프로토콜이 "OAuth 2" - 클라이언트 자격 증명 부여 유형인 경우 SDS는 "권한 부여" 헤더에 자격 증명을 보냅니다. SDS는 요청 본문에서 자격 증명 전송을 지원하지 않습니다.

OneRoster API 테스트

Postman 컬렉션 사용

Postman은 REST API를 실행하고 관리하는 잘 알려진 도구입니다. SDS에 필요한 OneRoster API를 호출하고 테스트하기 위해 OneRoster API Postman 컬렉션을 만들었습니다. 컬렉션을 실행하면 SDS에 필요한 모든 API가 호출되고 반환된 데이터에 대해 간단한 테스트가 실행됩니다.

샌드박스 환경에 대해 SDS 엔지니어링을 사용하여 테스트

OneRoster API에 대한 샌드박스 환경을 만들고 지정된 SDS 엔지니어와 자격 증명을 공유합니다. 함께 더 심층적인 테스트 집합을 실행하여 통합이 성공하도록 합니다.

솔루션의 유효성을 검사하도록 구성

모든 테스트가 성공하면 시스템 이름이 SDS의 OneRoster 공급자 목록에 추가됩니다. 그러나 지금은 'InPilot' 모드(공개적으로 사용할 수 없음)로 표시된 공급자 프로필에 대해 플라이트된 테넌트만 볼 수 있습니다. 다음으로, 테스트 Microsoft 365 테넌트에서 OneRoster API와 데이터를 연결하여 샌드박스 OneRoster 엔드포인트의 데이터를 동기화하고 오류 없이 실행이 완료되도록 SDS를 구성합니다. 오류 또는 경고가 표시되고 자체 조사 후 도움이 필요한 경우 지정된 SDS 엔지니어에게 문의하세요.

고객 파일럿

테스트가 성공적으로 완료되면 고객과 함께 솔루션 파일럿을 시작해야 합니다. 시스템 이름은 SDS의 OneRoster® 공급자 목록에 "플라이트"된 공급자 목록에 표시되어 통합 파일럿에 동의하는 'InPilot' 모드인 공급자도 볼 수 있습니다. SDS 팀과 OneRoster 공급자 팀은 함께 협력하여 적절한 파일럿 고객을 식별하고 SDS 배포 시간을 예약합니다. 고객과 긴밀히 협력하여 인바운드 흐름 실행이 성공하고 결과의 유효성을 함께 검사합니다. 확인된 최종 버그는 모든 Office 365 교육 고객이 솔루션을 공개적으로 사용할 수 있도록 하기 전에 해결해야 합니다.

공개로 이동

두 고객이 파일럿 배포를 성공적으로 완료하면 SDS에서 인증된 OneRoster 공급자 원본 시스템으로 파트너 시스템을 사용할 수 있습니다. SDS는 OneRoster API를 사용하여 연결 데이터 구성을 정의할 때 테넌트에게 공급자의 이름을 표시합니다. SDS 팀은 SDS 온라인 문서의 OneRoster API 공급자 개요 페이지에 파트너 시스템을 문서화합니다.

SDS 팀에는 다음이 필요합니다.

소프트웨어의 최소 버전
구성 필수 구성 요소
클라이언트 ID, 클라이언트 암호 및 URL을 가져오는 방법
기타 특정 지침
도움을 요청하기 위해 연락할 사람

SDS 팀은 팀과 협력하여 다양한 마케팅 채널을 통해 통합을 보다 광범위하게 홍보할 수 있습니다.

다음을 통해 공유