増分ユーザーレポート（ジョブAPI）
概要
Adobe Learning Managerの増分ユーザーレポートは、管理者や統合開発者が、指定された日時枠内にデータが変更されたユーザーのみを書き出すことができる新しいジョブAPI機能です。 毎回完全なユーザーリストを取得する代わりに、新規ユーザーまたは変更されたユーザーのみを対象とするターゲットスライスをリクエストできます。
この文書では、次の内容について説明します。
- 増分レポートが存在する理由と使用するタイミング
- この機能の仕組み（変更追跡モデルなど）
- 増分ユーザーレポート（ペイロード、パラメーター、ページ割り当て）用の新しいジョブAPI
- 大規模アカウントを処理する方法（5,00,000人以上のユーザー）
- 追跡対象フィールドと追跡対象外フィールド
- 制限と目標以外
増分レポートを使用する理由
このセクションでは、機能の目的を説明し、統合に最適な増分エクスポートと完全エクスポートのどちらかを決定するのに役立ちます。
完全なユーザーの書き出しの問題
現在の完全なユーザー書き出し（generateUsersジョブタイプ）は、実行のたびにアカウント内のすべてのユーザーを返します。 大企業のアカウントでは、次の2つの重要な問題が発生します。
* これらのスケールでは、データの取得、処理、保存を行う際に、書き出しパイプラインがCPU使用率の約90%で実行されます。
* ダウンストリームダッシュボード（PowerBI、Salesforce、カスタム統合）は、実行ごとに変更されていないユーザーレコードを再取り込みするため、帯域幅と処理時間が無駄になります。
* 「前回の書き出し以降に変更されたユーザー」を確認する方法はありません。 を返します。
増分レポートを使用する場合
外部システムをAdobe Learning Managerユーザーデータに同期させる必要がある場合は、増分書き出しを使用します。 一般的な使用例：
* エンタープライズダッシュボード(PowerBI、Tableau、SFDC)をユーザープロファイルの変更に合わせて最新の状態に保ちます。
* 役割、状態、またはメタデータの変更をダウンストリームのID管理システムに提供する。
* 完全なリロードではなく、毎晩または毎時間のデルタ同期パイプラインを実行する。
* 数百万人のユーザーを持つアカウントのAPI読み込みとデータ転送のコストを削減します。
完全な書き出し(generateUsers)は、権限のあるベースラインが必要な場合（例えば、最初の設定時や同期間の長いギャップの後）に使用します。
現在の完全なユーザーレポート
(generateUsers)このセクションでは、参照用に既存のジョブAPIユーザーレポートを文書化します。 既に使い慣れている場合は、次のセクションに進んでください。
仕組み
現在のユーザーCSVレポートは、ジョブAPIを介してジョブとして送信されます。 Snaplogicパイプラインがタスクを取得し、CAPTIVATEデータベース（user、usergroup、usergroup_userテーブル）に対してMySQLクエリを実行し、CSVファイルを生成します。
使用可能なフィルター
ペイロードは、次の3つのオプションフィルターをサポートしています。
* expandMetadata – メタデータを別の列としてエクスポートするにはtrueを渡します。
* fetchActiveUsers – アクティブなユーザーのみをエクスポートするには、trueを渡します。
* peerAccountId – ピアアカウントのユーザーレポートを生成します。
CSV列
書き出されたCSVには、次の列が含まれます。
internalUserID, userEmail, customerDefinedUniqueUserId, name, managerEmail,
userType, state, excludedFromGamification, pointsEarned, profile, roles,
dateCreated, lastLoginDate, dateDeleted, uiLocale, contentLocale,
timeZoneCode, userSource, group, AF_location, AF_login, AF_externalaf,
lastSocialActivityDate
要求ペイロード
ジョブの種類： generateUsers 管理者ロールのみ。
{
"data": {
"type": "job",
"attributes": {
"description": "<description of your choice>",
"jobType": "generateUsers",
"payload": {
"expandMetadata": "<true to export metadata as separate column>",
"fetchActiveUsers": "<true to export ACTIVE users only>",
"peerAccountId": "<peerAccountId for peer account report>"
}
}
}
}
制限
* 日付ベースのフィルタリングなし – すべての実行ですべてのユーザーが書き出されます。
* 大規模アカウントには適していません。パイプラインリソースの枯渇が100万ユーザーを超えています。
* 差分または差分の機能はありません。
増分ユーザーレポート(generateUserIncrementalReport)
このセクションでは、M46で導入された新しい増分ユーザーレポート機能について説明します。 これがこの文書の主な主題です。
増分エクスポートとは
増分エクスポートでは、指定した開始日時と終了日時の期間内に追跡データが変更されたユーザーのみが戻されます。 バックエンドには、各ユーザーの追跡フィールドの最終変更タイムスタンプが保存されます。 特定のウィンドウのレポートを要求すると、そのウィンドウ内に最新の変更があるユーザーのみが含まれます。
変更追跡モデルの仕組み
Adobe Learning Managerでは、ユーザーの記録フィールドが変更されるたびに更新される、最終変更タイムスタンプを保持します。
start_date_timeとend_date_timeを指定した増分レポートを要求すると、最終変更タイムスタンプが[start_date_time, end_date_time]以内のユーザーが戻されます。 ウィンドウ内とウィンドウ後の両方でユーザーが変更された場合（つまり、end_date_time以降に再度変更された場合）、そのユーザーはレポートに含まれません。これは、最後に変更されたタイムスタンプがウィンドウを超えるようになったためです。
変更を追跡するフィールド
次のいずれかのフィールドが変更された場合、ユーザーは増分レポートに含まれます。
変更が記録されないフィールド
次のフィールドはCSV出力に表示されますが、変更されたときに増分書き出しに含めるトリガーされません。
* excludedFromGamification
* pointsEarned（獲得ポイント）
* lastLoginDate（最終ログイン日）
* dateDeleted
* dateCreated
* userSource
* lastSocialActivityDate
出力形式
増分CSVレポートには、フルユーザーのCSVレポートと同じ列および形式が含まれます。 書き出されたユーザーに対して変更されたフィールドに関係なく、すべての列（アクティブなフィールドとメタデータの列をすべて含む）が同じ順序で表示されます。
増分ユーザーレポートの新しいジョブAPI
増分ユーザーレポートでは、ジョブAPIを使用して、指定された日時枠内に変更された追跡データを持つユーザーを含むCSVファイルが生成されます。 結果セットが大きい場合は、後で説明する同じページネーションモデルを使用します。それぞれのリクエストで同じ日付ウィンドウを送信し、前の応答で受け取った最後のuserIdをfromUserIdとして渡して、次のチャンクを取得します。
ジョブの種類
ジョブの種類： generateUserIncrementalReport
要求ペイロード
{
"data": {
"type": "job",
"attributes": {
"description": "description of your choice",
"jobType": "generateUserIncrementalReport",
"payload":{
"fullExport": <Pass true to export all users. If fullExport is true, fromDate and toDate are ignored>,
"expandMetadata": <Pass true to export metadata as separate columns>,
"fromDate": <Start of the change window in ISO format, for example 2020-01-01T18:30:00.000Z>,
"toDate": <End of the change window in ISO format, for example 2020-01-31T18:30:00.000Z>,
"fromUserId": <For paginated requests, pass the last userId received in the previous response>
}
}
}
}
ペイロードパラメーター
増分エクスポートの場合は、fromDateとtoDateを渡して変更ウィンドウを定義します。 結果セットが1つのチャンクよりも大きい場合、同じfromDateとtoDateを送信し、以前の応答の最後のuserIdをfromUserIdとして渡すことで、ページ割り当てを続行します。 fullExportがtrueの場合、日付ウィンドウは無視され、APIは完全なユーザー書き出しを生成します。
大規模アカウントの処理（500,000人以上のユーザー）
ユーザーレポートはデータプラットフォームパイプラインを使用して生成され、出力は大きなアカウントをサポートするためにチャンクで返されます。 500,000人を超えるユーザーが増分書き出しによって対象になっている場合、レポートにはページ番号が付けられます。
ページ割り付けモデル
大量の差分エクスポートのためにすべてのページを取得するには、各リクエストで同じstartDateTimeとendDateTimeを渡し、さらにfromUserIdとして、以前のチャンクで受け取った最後のユーザーのuserIdを渡します。 APIは、最大500,000人のユーザーから成る次のセットを、渡されたfromUserIdよりも大きいuserIdで返します。
ページ割り付けワークフロー
手順1:fromUserIdを指定せずに最初のリクエストを送信する。
// First request – no fromUserId
{
"payload": {
"startDateTime": "2026-05-01T00:00:00Z",
"endDateTime": "2026-05-31T23:59:59Z"
}
}
ステップ2：最初のチャンク（最大500,000ユーザー）を受け取ります。 応答の最後のuserIdをメモします。
ステップ3：同じ日付ウィンドウと、前の応答の最後のユーザーIDをfromUserIdとして渡して、次のリクエストを送信する。
// Subsequent request – pass last userId from previous response as fromUserId
{
"payload": {
"startDateTime": "2026-05-01T00:00:00Z",
"endDateTime": "2026-05-31T23:59:59Z",
"fromUserId": "<last userId from previous response>"
}
}
ステップ4：応答で返されるレコードが500,000未満になるまで繰り返します。これは、最後のページに到達したことを示します。
startDateTimeとendDateTimeが同一であることを確認してください。 日付ウィンドウのページ割り付け中に日付ウィンドウを変更すると、一貫性のない結果が生成されます。制限
増分ユーザーレポートは、意図的にスコープが設定されています。 次の機能は範囲外です：
* ユーザー監査レポートではありません。変更された特定のフィールドは一覧表示されません。
* 古い値と新しい値の比較なし：レポートには、現在のフィールド値のみが表示されます。
* 変更ごとのタイムスタンプなし – 個々のフィールドの変更時間が表示されません。
* 変更の回数は表示されません。1回変更されたユーザーと10回変更されたユーザーは、書き出しに同じように表示されます。
* 既存のレポート形式が変更されない – CSV列の構造は、完全なユーザーレポートと同じです。
コネクタの統合
増分ユーザーレポートは、通常の同期パイプラインでの完全なユーザーレポートの代わりにAdobe Learning Managerコネクタ（PowerBI、Salesforceなど）で使用できるように設計されています。 これにより、現在generateUsersを使用するコネクタは、ダウンストリームデータスキーマに変更を加えることなく、増分モデルに移行できます。
* 出力されたCSVは、完全なユーザーレポートと列互換性があります。
* コネクタは、差分レポートをデルタ同期に使用し、ブートストラップまたはリカバリ用の完全なレポートにフォールバックできます。
* コネクタ統合(PowerBI、SFDC)のサポート