Руководство по подключению для поставщиков API OneRoster с синхронизацией данных school (SDS)
Введение
Microsoft School Data Sync (SDS) может синхронизировать сведения об удостоверениях и реестре из любой системы, которая реализует стандарт 1EdTech OneRoster API (интерфейсы программирования приложений) во входящий поток данных. Этот документ предназначен для того, чтобы помочь любым новым поставщикам API OneRoster успешно интегрироваться с SDS. Клиенты могут подключаться непосредственно к своему поставщику с помощью API OneRoster 1.1 на основе REST. Следующий процесс подключения определяет шаги, необходимые поставщику API, прежде чем их можно будет добавить для арендаторов для выбора и использования в SDS.
Сведения о SDS
Если вы хотите узнать больше о SDS, перейдите на сайт продукта SDS.
Технические сведения о SDS, включая видео о развертывании и рекомендации администратора, см. на сайте документации по SDS.
Дополнительные сведения о взаимодействии с клиентами для подключения данных с помощью API OneRoster см. в статье Подключение данных с помощью API OneRoster.
Обзор
Заполните форму в форме регистрации партнера SDS.
Укажите, что вы будете оказывать помощь по интеграции с синхронизацией данных в учебном заведении в форме.
Для доступа к форме требуется регистрация. Дополнительные сведения см. на сайте Microsoft Partner Network . Необходимо отправить отдельную форму для доступа к ресурсам SDS и Office dev.
Реализуйте конечные точки API OneRoster, необходимые для SDS.
SDS использует фильтр в свойстве dateLastModified для разностной синхронизации или добавочной синхронизации и требуется для интеграции с SDS.
Убедитесь, что SDS работает с конечными точками API OneRoster.
Оценка API с помощью коллекции Postman.
Тестирование с помощью проектирования SDS в песочнице.
Настройте SDS для проверки решения E2E.
Опробуйте решение с двумя рабочими клиентами.
Сделайте соединитель общедоступным в SDS для всех клиентов Office 365 EDU.
Начало работы
Если вы только что разрабатываете API OneRoster, следуйте спецификации API OneRoster версии 1.1 для создания основного списка.
Пример реализации в ASP.NET MVC с помощью C#.
Мы предлагаем сертификацию в качестве поставщика с 1EdTech, но не требуем этого.
Дополнительные сведения о списке значений по умолчанию, поддерживаемых SDS, см. в разделе Список значений по умолчанию.
Обязательные конечные точки API для SDS
| Действие | URL-адрес | Обязательные свойства фильтра | Необязательный или рекомендуемый фильтр | Примеры |
|---|---|---|---|---|
| GetAllAcademicSessions | /academicSessions | status | dateLastModified | /academicSessions?offset=0&limit=5000&filter=status='active'/academicSessions?filter=dateLastModified>'{deltaDateTime}' |
| GetAllOrgs | /orgs | status | dateLastModified | /orgs?offset=0&limit=5000&filter=status='active'/orgs?filter=dateLastModified>'{deltaDateTime}' |
| GetAllUsers | /Пользователей | status | dateLastModified | /users?offset=0&limit=5000&filter=status='active'/users?filter=dateLastModified>'{deltaDateTime}' |
| GetAllClasses | /Классы | status | dateLastModified | /classes?offset=0&limit=5000&filter=status='active'/classes?filter=dateLastModified>'{deltaDateTime}' |
| GetAllEnrollments | /Регистрации | status | dateLastModified | /enrollments?offset=0&limit=5000&filter='active'/enrollments?filter=dateLastModified>'{deltaDateTime}' |
Необязательные конечные точки API для SDS
Примечание.
Для дополнительных фрагментов данных для демографических данных, связей контактов с учащимися и флагов пользователей учащиеся возможность включения этих данных или их не будет зависеть от поддерживаемых дополнительных возможностей данных из профиля поставщика, который мы создадим. После описанных шагов тестирования и проверки, если вы решили также поддерживать эти данные для клиентов, использующих SDS, они увидят переключатель (по умолчанию ) для включения дополнительных данных. При желании они могут выбрать переключатель, чтобы отключить его. Если переключатель недоступен, отображается, но отключен и недоступен для взаимодействия, это означает, что профиль поставщика в настоящее время не поддерживает предоставление этих данных.
| Действие | URL-адрес | Обязательные свойства фильтра | Необязательный или рекомендуемый фильтр | Примеры |
|---|---|---|---|---|
| GetAllCourses | /месячные | status | dateLastModified | /courses?offset=0&limit=5000&filter=status='active'/courses?filter=dateLastModified>'{deltaDateTime}' |
| GetAllDemographics | /Демография | status | dateLastModified | /demographics?offset=0&limit=5000&filter=status='active'/demographics?filter=dateLastModified>'{deltaDateTime}' |
Необязательные связи контактов учащихся-пользователей
Совет
Так как SDS не поддерживает загрузку даты контактов учащихся с помощью CSV, если данные списка предоставляются через API OneRoster, мы рекомендуем всем поставщикам работать над поддержкой предоставления контактов с помощью подхода к API OneRoster.
Контактная связь учащихся может быть указана для пользователей учащихся, чтобы улучшить взаимодействие преподавателей с родителями и опекунами учащихся. Контакты — это больше пользователей, которые предоставляются с конечной точкой /users, а связь с учащимся находится в пользовательской записи учащегося в разделе "агенты".
- Дополнительные сведения о поддерживаемых ролях связи учащихся, поддерживаемых SDS, см. в разделе Список значений по умолчанию: Роли связи контактов.
- familyName, givenName и электронная почта необходимы для пользователей, имеющих роли контакта или опекуна.
- Ожидается, что телефон и sms должны быть указаны в E.164 и + должны быть включены. (Пример: +1234567890).
- Если предоставляются обратные данные, из записи опекуна контактных отношений до учащегося в поле "агенты" контактных пользователей эти записи отфильтровываются.
Необязательные флаги демографических данных пользователей
Флаги пользователей можно указать для учащихся, чтобы указать их участие в программе или когорте. Флаги пользователей включаются (если значение true для пользователя) или не включаются, если это неприменимо.
Флаги указываются как расширение метаданных для пользователя в поле метаданных. Подход следует ключу |Пара значений с ключом с именем microsoft.userFlags и должна быть отформатирована в виде списка с разделителями-запятыми. Флаги пользователей могут отображаться в любом порядке и не учитывает регистр.
Дополнительные сведения о списке по умолчанию значений пользовательских флагов, поддерживаемых SDS, см. в разделе Список значений по умолчанию: Флаги пользователей.
Пример:
{
"user" : {
…
…
"metadata" : {
"microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“
}
}
Правила сопоставления и проверки данных
Дополнительные сведения о правилах сопоставления и проверки данных см. в разделе Правила проверки и описания.
Важно!
В 1EdTech поставщик несет ответственность за обеспечение конфиденциальности данных для того, какие данные доступны при запросе данных. School Data Sync выполняет запрос на активные данные на основе времени запроса.
Полезные примечания и советы
Конечные точки всегда поступают после URL-адреса https: {server_URL}/ims/oneroster/v1p1.
Все конечные точки должны поддерживать разбиение по страницам, то есть параметры ограничения и смещения (например, limit=10&offset=5000).
Конечные точки имеют требования к поддержке параметров фильтра, чтобы разрешить фильтрацию по состоянию или включить разностную синхронизацию.
Клиенты знают, как включить параметр "Активен" или как разрешить только активные данные для подключения, которое будет использоваться синхронизацией данных school. Это гарантирует, что по мере прохождения учебного года будут предоставляться только активные данные для активного учебного года и сеанса.
SDS применяет фильтр к свойству dateLastModified для разностной синхронизации и добавочной синхронизации и требуется для интеграции с SDS.
Поставщики должны реализовать схему проверки подлинности OAuth1(a) или OAuth 2.0 (предоставление учетных данных клиента), предпочтительнее OAuth 2.0.
Во время разработки вы можете проверить конечные точки с помощью коллекции Postman.
Если поддерживается протокол проверки подлинности "OAuth 2" — тип предоставления учетных данных клиента, SDS будет отправлять учетные данные в заголовке "Авторизация". SDS не поддерживает отправку учетных данных в тексте запроса.
Тестирование API OneRoster
Использование коллекции Postman
Postman — это хорошо известное средство для запуска REST API и управления ими. Мы создали коллекцию Postman API OneRoster для вызова и тестирования API OneRoster, необходимых для SDS. При запуске коллекции вызываются все ИНТЕРФЕЙСЫ API, необходимые для SDS, и выполняются простые тесты для возвращаемых данных.
Тестирование с помощью SDS Engineering в песочнице
Создайте песочницу для API OneRoster и поделитесь учетными данными с назначенным инженером SDS. Вместе мы выполняем более глубокий набор тестов, чтобы убедиться, что интеграция прошла успешно.
Настройка для проверки решения
После успешного выполнения всех тестов имя системы добавляется в список поставщиков OneRoster в SDS. Однако в настоящее время он виден только для клиентов, которые тестируются для профилей поставщиков, обозначенных как режим InPilot (не является общедоступным). Затем настройте SDS для подключения данных с помощью API OneRoster в тестовом клиенте Microsoft 365 для синхронизации данных из песочницы конечных точек OneRoster и обеспечения выполнения без ошибок. Если вы видите какие-либо ошибки или предупреждения и вам нужна помощь после самостоятельного исследования, обратитесь к назначенному инженеру SDS.
Пилотный проект для клиентов
После успешного завершения тестирования пришло время начать пилотное тестирование решения с клиентами. Имя вашей системы отображается в списке поставщиков OneRoster® в SDS для тех, кто "проехал", чтобы также увидеть поставщиков, которые находятся в режиме InPilot, соглашаясь на пилотную интеграцию. Команда SDS и группа поставщиков OneRoster работают вместе, чтобы определить соответствующих пилотных клиентов и запланировать время для развертывания SDS. Мы тесно сотрудничаем с клиентами, чтобы обеспечить успешное выполнение входящего потока и проверить результаты вместе. Все обнаруженные последние ошибки необходимо устранить, прежде чем сделать решение общедоступным для всех клиентов Office 365 для образования.
Go public
После успешного завершения пилотных развертываний два клиента система партнеров будет доступна в SDS в качестве сертифицированной исходной системы поставщика OneRoster. SDS отображает имя поставщика для клиентов при определении конфигурации данных подключения с помощью API OneRoster. Команда SDS документирует систему партнеров на странице обзора поставщика API OneRoster в наших веб-документах SDS.
Команде SDS требуется:
- Минимальная версия программного обеспечения
- Предварительные требования к настройке
- Получение идентификатора клиента, секрета клиента и URL-адресов
- Любые другие конкретные инструкции
- К кому обращаться за помощью
Команда SDS может координировать работу с вашей командой для более широкого продвижения интеграции с помощью различных маркетинговых каналов.