学校データ同期 (SDS) を使用した OneRoster API プロバイダーのオンボード ガイダンス
概要
Microsoft 学校データ同期 (SDS) は、受信データ ストリームに 1EdTech OneRoster API (アプリケーション プログラミング インターフェイス) 標準を実装する任意のシステムから ID と名簿の情報を同期できます。 このドキュメントは、OneRoster API の新しいプロバイダーが SDS と正常に統合できるように支援することを目的としています。 次のオンボード プロセスでは、テナントが SDS で選択して使用するために API プロバイダーを追加する前に必要な手順を定義します。
SDS について
SDS の詳細については、 SDS 製品サイトにアクセスしてください。
展開ビデオや管理者向けガイダンスなど、SDS に関する技術情報については、 SDS ドキュメント サイトを参照してください。
OneRoster API で SDS を使用する方法の詳細については、OneRoster API® での データ インジェストに関するページを参照してください。
概要
SDS パートナーサインアップ フォームのフォームに入力します。
フォームで School Data Sync Integration の支援を行うことを示します。
フォームにアクセスするには、登録が必要です。詳細については、 Microsoft Partner Network サイト を参照してください。 SDS と Office 開発リソースアクセス用の別のフォームを送信する必要があります。
SDS で必要な OneRoster API エンドポイントを実装します。
SDS では、差分同期/増分同期処理に dateLastModified プロパティのフィルターが使用され、SDS との統合に必要です。
SDS が OneRoster API エンドポイントと連携することを確認します。
Postman コレクションを使用して API を評価します。
サンドボックス環境に対して SDS エンジニアリングを使用してテストします。
ソリューション E2E を検証するように SDS を構成します。
2 人の運用顧客でソリューションをパイロットします。
OFFICE 365 EDU テナントすべてに対して、コネクタを SDS で一般公開します。
はじめに
OneRoster API を新しく開発する場合は、 コア 名簿の OneRoster API v1.1 仕様に従ってください。
C# を使用 ASP.NET MVC のサンプル実装。
IMS Global を使用したプロバイダーとしての認定をお勧めしますが、必要ありません。
SDS でサポートされる値の既定の一覧の詳細については、「 既定の値の一覧」を参照してください。
SDS に必要な API エンドポイント
| アクション | 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=status='active'/enrollments?filter=dateLastModified>'{deltaDateTime}' |
SDS 用の省略可能な API エンドポイント
注:
人口統計、学生の連絡先関係、学生ユーザー フラグのオプションのデータの場合、顧客がこのデータを含めるか含めないようにする機能は、Microsoft が作成するプロバイダー プロファイルでサポートされているオプションのデータ機能に基づいて行われます。 記載されているテストと検証の手順に従って、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}' |
省略可能なユーザー学生の連絡先関係
学生の保護者とのコミュニケーションに関する教育者エクスペリエンスを向上させるために、学生ユーザーに対して学生の接触関係を指定できます。 連絡先は、/users と共に提供されるより多くのユーザーであり、学生への関連付けは、学生のユーザー レコードの [エージェント] の下にあります。
- 詳細については、SDS でサポートされている学生の連絡先関係の役割に関する 記事の「既定の値の一覧: 連絡先関係ロール」を参照してください。
- familyName、givenName、および電子メールは、連絡先/保護者の役割を持つユーザーに必要です。
- 電話とSMSがE.164にあり、+ が含まれている必要があります。 (例: +1234567890)。
- 連絡先関係の保護者レコードから連絡先ユーザーの [エージェント] フィールドの学生に逆データが指定されている場合、これらのレコードは除外されます。
省略可能なユーザー人口統計フラグ
学生ユーザーがプログラムまたはコーホートに参加することを示すために、ユーザー フラグを指定できます。 ユーザー フラグが含まれる (ユーザーに対して true の場合)、または該当しない場合は含まれません。
フラグは、ユーザーのメタデータ拡張機能として、メタデータ フィールドで Key| に従って指定されます。microsoft.userFlags という名前のキーを持つ値ペア。コンマ区切りリストとして書式設定する必要があります。 ユーザー フラグは任意の順序で表示され、大文字と小文字は区別されません。
詳細については、SDS でサポートされているユーザー フラグ値の既定の一覧については、「 値の既定の一覧: ユーザー フラグ」を参照してください。
例:
{
"user" : {
…
…
"metadata" : {
"microsoft.userFlags" : "freeLunch,homeless,giftedOrTalented“
}
}
データ照合と検証ルール
データ照合ルールと検証ルールの詳細については、「 検証ルールと説明」を参照してください。
重要
1EdTech では、データ要求が行われたときに使用可能なデータに対してデータ プライバシーを適用する必要があります。 School Data Sync は、要求の時刻に基づいてアクティブ データの要求を行います。
役に立つメモとヒント
エンドポイントは、常に https URL {server_URL}/ims/oneroster/v1p1 の後にあります。
すべてのエンドポイントでは、ページング 、つまり limit パラメーターと offset パラメーターをサポートする必要があります (例: limit=10&offset=5000)。
エンドポイントには、状態によるフィルター処理を許可したり、差分同期を有効にしたりするためのフィルター パラメーターのサポートに関する要件があります。
お客様は、オプション 'Is Active' を有効にする方法、または School Data Sync で使用する接続でアクティブなデータのみを使用できるようにする方法を知っています。これにより、学年が進むにつれて、アクティブな学年とセッションのアクティブなデータのみが確実に提供されます。
SDS は、差分同期/増分同期処理の dateLastModified プロパティにフィルターを適用し、SDS との統合に必要です。
プロバイダーは、OAuth1(a) または OAuth 2.0 (クライアント資格情報の許可) 認証スキーム (OAuth 2.0 を推奨) を実装することを選択する必要があります。
開発中は、 Postman コレクションを使用してエンドポイントを確認できます。
サポートされている認証プロトコルが "OAuth 2" である場合 - クライアント資格情報の許可の種類は、SDS によって "Authorization" ヘッダーに資格情報が送信されます。 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教育顧客がソリューションを一般公開する前に対処する必要があります。
公開する
2 人の顧客がパイロットデプロイを正常に完了すると、パートナー システムは認定された OneRoster プロバイダー ソース システムとして SDS で利用できるようになります。 SDS では、OneRoster API を使用してデータ インジェストを設定するときに、プロバイダーの名前がテナントに表示されます。 また、SDS チームは、SDS オンライン ドキュメントの OneRoster API プロバイダーの概要 ページでパートナー システムを文書化します。
SDS チームには次のものが必要です。
- ソフトウェアの最小バージョン
- 構成の前提条件
- クライアント ID、クライアント シークレット、URL を取得する方法
- その他の特定の手順
- ヘルプに問い合わせるユーザー
また、SDS チームは、さまざまなマーケティング チャネルを通じて統合をより広範に促進するために、チームと連携します。