汎用 CSV コネクタ - テクニカル リファレンス ガイド (プレビュー)

この記事では、汎用 CSV (GCSV) コネクタについて説明します。 この記事は、次の製品に適用されます。

• Microsoft Entra Connect プロビジョニング エージェント (ECMA2Host)
• Microsoft Identity Manager 2016 (MIM2016)

MIM 2016 の場合、コネクタは Microsoft ダウンロード センターからダウンロードできます。

このコネクタの動作を確認するには、 汎用 SQL コネクタの詳細 な記事を参照してください。

汎用 CSV コネクタの概要

汎用 CSV (GCSV) コネクタを使用すると、CSV ファイルに保持されているユーザーとグループの ID データを、Microsoft Entra Connect Provisioning Agent (ECMA2Host) や Microsoft Identity Manager 2016 (MIM2016) などの Microsoft 製品と統合できます。

PowerShell を使用してインポート操作またはエクスポート操作の前後に ID データを管理する機能など、さまざまな機能があります。 バイナリと参照を含む複数のデータ型、修飾文字列値のサポート、および複数値の文字列のサポートを提供します。

この記事では、汎用 CSV コネクタの機能と、MIM 2016 用に構成する方法について説明します。

次の表に、コネクタの現在のリリースでサポートされている機能を高いレベルで概観しています。

[前提条件]

コネクタを使用する前に、同期サーバーに次のものがインストールされていることを確認します。

• Microsoft .NET 4.6.2 Framework 以降
• 次の ID の種類の目的のスキーマを含む CSV ファイル:
  • ユーザー ファイル (必須)
  • グループ (省略可能)
  • グループ メンバー (グループを使用する場合は必須)
• (省略可能)次の操作の種類のイベントの前処理と後処理を管理するための PowerShell スクリプト:
  • インポート前 – このスクリプトは、インポート操作が実行される前に実行されます。
  • インポート後 – このスクリプトは、インポート操作の実行後に実行されます。
  • エクスポート前 – このスクリプトは、エクスポート操作が実行される前に実行されます。
  • エクスポート後 – このスクリプトは、エクスポート操作の実行後に実行されます。

MIM 同期サービス アカウントのアクセス許可

新しいコネクタを作成する

このガイドで説明する手順の概要を次に示します。 開始するには、 MIM 同期管理者 ロールを持つアカウントを使用して、次のタスクを実行する必要があります。

• MIM 同期サービス マネージャーから [新しい管理エージェント (MA) の作成] ウィンドウを開きます。
• コネクタの種類として 汎用 CSV コネクタ を選択します。
• インポートまたはエクスポートする CSV ファイルのファイル パスと名前を指定します。
• CSV ファイルのファイル エンコード、値の区切り記号、複数値の区切り記号、およびテキスト修飾子を指定します。
• 最初の行の値をヘッダー フィールドとして使用するかどうかを選択します。
• CSV ファイルからインポートまたはエクスポートするオブジェクトの種類と属性を選択します。
• MA のパーティション、実行プロファイル、マッピングの詳細を構成します。
• PowerShell スクリプトのスクリプト パスとパラメーター (存在する場合) を指定します。
• MA を実行して、インポート、同期、またはエクスポートの操作を実行します。

汎用 CSV コネクタを作成するには、 Synchronization Service で 管理エージェント と 作成を選択します。 汎用 CSV (Microsoft) コネクタを選択します。

Connectivity

[接続] ページには、ユーザー、グループ、およびグループ メンバーの CSV ファイルのファイルの場所が含まれています。

次の図は、[ 接続] ページの例です。

このページでは、次の CSV ファイルの場所を指定します。

• ユーザー ファイル: ユーザー レコードとその属性値を含む CSV ファイルの完全修飾パス。 このファイルは必須です。
• グループ ファイル: グループ レコードを含む CSV ファイルの完全修飾パス。 このファイルは省略可能です。
• メンバー ファイル: グループ メンバー参照レコードを含む CSV ファイルの完全修飾パス。

接続画面は、新しい Generic SQL コネクタを作成する最初の画面です。 最初に、次のセクション情報を指定する必要があります。

能力

このページでは、コネクタの機能について説明します。 コネクタの機能は固定されており、変更することはできませんが、コネクタの動作に関する情報を提供するために、ここで説明します。

次の図は、[ 機能] ページの例です。

次のセクションでは、個々の構成とその意味の一覧を示します。

• 識別名スタイル (LDAP): GCSV コネクタは、LDAP (ライトウェイト ディレクトリ アクセス プロトコル) 構文を使用して DN (識別名) を構築し、コネクタ スペース内の各ユーザーまたはグループ オブジェクトを一意に識別します。 すべての DN 値は、次の形式で表されます: CN=[ANCHOR_VALUE]、Object=[User|グループ]、O=CSV。
• オブジェクトの確認 (標準): 通常、同期エンジンは、エクスポート後の後続の差分インポートでオブジェクトを再度取得できることを前提としています。 これは通常、同期エンジンの動作方法ですが、すべての接続されたシステムがこのように動作するわけではありません。 この Normal の設定により、フォローアップ インポートに exported-change-not-reimported 警告が表示されなくなります。
• エクスポートの種類 (MultivaluedReferenceAttributeUpdate): エクスポートの種類は、同期中にオブジェクトを書式設定し、ターゲット システムに送信する方法を指定します。 MultivaluedReferenceAttributeUpdate は、Microsoft Entra ID を使用するように設計されたエクスポートの種類です。 変更された属性のみが送信されます。 値型属性の場合は AttributeReplace を使用し、参照属性には AttributeUpdate を使用します。
• 正規化 (なし): 正規化とは、データを一貫した形式に標準化することを指します。 None は、特定の正規化ルールが適用されていないことを意味します。 データは、コネクタによる追加の変換なしで as-is のままです。

スキーマ 1 (CSV ファイル形式の構成)

GCSV コネクタでは、3 種類の区切り記号 (または区切り記号) を使用して、CSV フィールドとその値を区切り、解析します。

このページには、これらの区切り記号の文字値の設定と、ファイルを CSV として作成するために使用されたエンコードの種類が含まれています。

次の図は、 スキーマ 1 (CSV ファイル形式の構成) ページの画像です 。

次のセクションでは、個々の構成の一覧を示します。

• スキーマ検出にヘッダーを使用する: このオプションを選択すると、各 CSV ファイルの最初のレコードを ID データ レコードではなくヘッダー レコードとして扱うようにコネクタに指示されます。 このオプションが選択されていない場合、コネクタは 属性名に 一意の増分整数値 ( Attribute1、 Attribute2 など) を追加して割り当て、最初の行を ID データ レコードとして扱います。
• 値の区切り記号: この文字は、CSV レコードのフィールド (つまり、値) を区切ります。 既定はコンマ (,) ですが、印刷できる英数字は使用できます。
• 複数値区切り記号: この種類の区切り記号は、複数値の文字列 (プロキシ アドレスなど) または参照属性 (従属など) の個々の値を区切るために使用されます。既定値はセミコロン (;)ですが、印刷可能な英数字は使用できます。
• テキスト修飾子: 文字列値に区切り記号として解釈される文字 (コンマなど) が含まれている場合は、CSV パーサーが文字列を 1 つのフィールドとして正しく解釈できるように、値を修飾する必要があります。 二重引用符 (") は既定ですが、印刷できる英数字は使用できます。

• ファイル エンコード: この設定は、[接続] タブに追加された CSV ファイルで使用されるエンコードを示します。CSV ファイルのエンコードと一致していることを確認します。

スキーマ 2 (ID と参照フィールドの構成)

アンカー値は、CSV ファイル内のレコードの一意の識別子です。 あるレコードを他のレコードと区別します。 GCSV コネクタでは、この値を使用して、関連するコネクタ スペース オブジェクトを識別する識別名 (DN) も作成します。

このページでは、[接続] ページに一覧表示されている CSV ファイルごとにアンカー属性の設定が設定されます。

次の図は、 スキーマ 2 (ID と参照フィールドの構成) ページの例です 。

次のセクションでは、このページの個々の構成の一覧を示します。

• User
  • ユーザー アンカー: ユーザー レコードのアンカー値として機能する Users ファイル内のフィールド。 Users ファイルの最初のヘッダー フィールドが既定の選択肢です。
  • ユーザー アンカー属性の種類: 選択したアンカーの属性の種類です。
• グループ
  • グループ アンカー: グループ レコードのアンカー値として機能する Groups ファイル内のフィールド。 グループ ファイルの最初のヘッダー フィールドが既定の選択肢です。
  • グループ アンカー属性の種類: 選択したアンカーの属性の種類です。
• メンバー
  • 親グループ ID: グループ CSV ファイル内の親グループと同じ (アンカー) 値を持つメンバー ファイル内のフィールド。 メンバー ファイルの最初のフィールドは、既定で使用されます。
  • メンバー ID: Users または Groups CSV ファイルと同じ (アンカー) 値を持つメンバー ファイル内のフィールド。 既定では、メンバー ファイルの 2 番目のフィールドが選択されています。
• メンバー オブジェクトの種類: メンバーのオブジェクト型を示す "User" または "Group" 文字列値を含むフィールド。 このフィールドは、メンバー ファイルに 2 つ以上のフィールドが含まれている場合にのみ必要です。 [オブジェクトの種類] フィールドには、文字列値 "User" または "Group" のみが含まれている必要があります。このフィールドが見つからない場合、コネクタはメンバー ファイル レコードが User オブジェクト メンバーを参照していることを前提としています。 メンバー ファイルで見つかった 3 番目のフィールドは、既定で選択されています。

スキーマ 3 (ユーザー ファイル属性スキーマ構成)

このページでは、Users CSV ファイルのスキーマで識別される各フィールドのデータ型と、複数の値を含めることができるかどうかを指定して説明します。

次の図は、 スキーマ 3 (ユーザー ファイル属性スキーマ構成) ページの例です 。

次のセクションでは、属性データ型の割り当てを行う際の考慮事項を示します。

サポートされるデータ型

GCSV コネクタでは、次のセクションデータ型の使用がサポートされています。

• ブール値: true または false の値を指定します。
• バイナリ: 一連のバイトとして格納される値。通常は、画像やその他のファイルなどのデータを格納するために使用されます。
• 整数: 小数点以下の桁数を含まない整数の値。
• 文字列: テキスト データを格納するために通常使用される一連の文字である値。
• 参照: 別のユーザー オブジェクトへの参照である値。 CSV ファイルで参照値を指定するには、参照されるユーザー オブジェクトのアンカー値をフィールドに設定します。

サポートされている複数値データ型

コネクタでは、次のデータ型に対してのみ、複数値属性の使用がサポートされています。

• 糸

スキーマ 4 (グループ ファイル属性スキーマ構成)

このページでは、グループ CSV ファイルのスキーマで識別される各フィールドのデータ型と、複数の値を含めることができるかどうかを指定して説明します。

次の図は、 スキーマ 4 (グループ ファイル属性スキーマ構成) ページの例です 。

スキーマ 3 で提供されるガイダンス (ユーザー ファイル属性の構成もこのセクションに適用されます)。 .

最初の完全インポート操作を実行すると、コネクタ スペースは次の図のようになります。

グローバル パラメーター (PowerShell スクリプトの構成)

このページでは、インポート操作やエクスポート操作の前後に実行される PowerShell スクリプトを構成できます。 これらの機能により、ID ユーザーとグループ レコードに対してさまざまな前処理アクションと事後処理アクションを実行する機会が提供されます。

次の図は、[ グローバル パラメーター] ページの例です。

次のセクションでは、このページの個々の構成設定の一覧を示します。

• スクリプトのタイムアウト (分): スクリプトが自動的に中止されるまでの時間 (分)。 この設定の既定値は 100 で、0 より大きい値が必要です。
• 事前インポート スクリプト ファイル: インポートの前に実行する必要がある PowerShell スクリプトへの完全修飾パス。 この設定は省略可能であり、値は必要ありません。
• インポート後のスクリプト ファイル: インポート後に実行する必要がある PowerShell スクリプトへの完全修飾パス。 この設定は省略可能であり、値は必要ありません。
• 事前エクスポート スクリプト ファイル: エクスポートの前に実行する必要がある PowerShell スクリプトへの完全修飾パス。 この設定は省略可能であり、値は必要ありません。
• エクスポート後のスクリプト ファイル: エクスポート後に実行する必要がある PowerShell スクリプトへの完全修飾パス。 この設定は省略可能であり、値は必要ありません。

PowerShell スクリプトの実行と入力パラメーター

GCSV コネクタは、構成された各 PowerShell スクリプトを独自のセッションで実行します。また、ステージ間でのパラメーターの渡しはサポートされていません。

コネクタは、OperationType という名前の各スクリプトに 1 つの入力パラメーターを渡します。 このパラメーターの値は、実行される実行プロファイル操作によって異なり、次の 3 つの値のいずれかになります。

PowerShell 入力パラメーター: OperationType

入力パラメーターの使用はサポートされていませんが、GCSV コネクタは、すべての PowerShell スクリプトの実行に 1 つの入力パラメーター ( OperationType) を渡します。

• Full – この値は、フル インポート操作または完全エクスポート操作中に指定されます。
• Delta – この値はエクスポート操作中に提供されます。

このパラメーター値は、PowerShell スクリプトのロジック内で使用して、実行する適切な前処理/後処理操作またはアクションを決定できます。  

プロビジョニング階層

CSV ファイルは階層構造に情報を格納しないため、GCSV コネクタは階層型プロビジョニング構成をサポートしていません。

次の図は、[ プロビジョニング階層 ] ページの例です。

パーティションと階層

GCSV コネクタは、次の LDAP 形式に従って、コネクタ スペース内のすべてのユーザーおよびグループ レコードに対して個別の識別名 (DN) を作成します。

CN=[ANCHOR_VALUE],Object=User|Group,O=CSV

次の図は、[ パーティションと階層] ページの例です。

オブジェクトの種類

GCSV コネクタでは、少なくともユーザー オブジェクトの種類を選択する必要があります。 Group オブジェクトの種類の選択は省略可能です。

次の図は、[ オブジェクトの種類] ページの例です。

Attributes

このページには、選択したすべてのオブジェクト型スキーマのすべての属性の正規化された一覧が表示されます。

次の図は、[ 属性] ページの例です。

アンカー

GCSV コネクタは、対応する CSV ファイルのアンカー ID フィールドとは異なる複雑なアンカーやアンカー属性の構成の使用をサポートしていません。

このページに表示されるアンカーの指定を変更するには、スキーマ 2 (アンカー構成) に戻ります。

次の図は、[ アンカー] ページの例です。

CSV レコードのプロビジョニング

GCSV コネクタが対応する CSV ファイルに新しい User オブジェクトまたは Group オブジェクトを追加するには、新しいコネクタ スペース オブジェクトをプロビジョニングする必要があります。

MIM 2016 宣言型プロビジョニングを使用するか、独自の MIM 同期規則拡張機能を記述するかにかかわらず、新しいコネクタ スペース オブジェクトには、次の形式を使用して DN が構築されている必要があります。

CN=[ANCHOR_VALUE],Object=ユーザー|グループ,O=CSV

次の表に、各コンポーネント値の詳細を示します。

次の図は、新しいユーザー オブジェクトを GCSV コネクタにプロビジョニングするときに DN を適切に構築する方法を示す 同期規則 です。

次のコードは、 Metaverse Rules Extensions を使用した同等のプロビジョニング ロジックを示しています。

void IMVSynchronization.Provision(MVEntry mventry)
{
	if (mventry["employeeID"].IsPresent)
	{
		ConnectedMA GCSVConnector = = mventry.ConnectedMAs["Generic CSV Conenctor"];

		if (GCSVConnector.Connectors.Count == 0)
		{
			CSEntry csentry = GCSVConnector.Connectors.StartNewConnector("user");

			//Sets DN to "CN=[ANCHOR_VALUE],OBJECT=[User|Group],O=CSV"
			csentry.DN = GCSVConnector.EscapeDNComponent("CN=" + mventry["employeeID"].Value).Concat("OBJECT=User,O=CSV");

			csentry["AccountName"].StringValue = mventry["accountName"].StringValue;
			csentry["CountryCode"].IntegerValue = 1;
			csentry["DisplayName"].Value = mventry["displayName"].Value;
			csentry["ProxyAddresses"].Value = mventry["proxyAddressCollection"].Value;
			csentry["IsActive"].BooleanValue = true;
			csentry["Manager"].Value = mventry["manager"].Value;
			csentry["ProfilePic"].Value = mventry["pic"].Value;

			csentry.CommitNewConnector();
		}
	}
}

前の図では、 EcapeDNComponent() 関数を使用して、アンカー値が LDAP 構文に準拠するように適切にエスケープされていることを確認します。

CSV フィールドの書式設定の例

次のセクションでは、CSV ファイル内のさまざまなデータ型を書式設定する方法の例を示します。 すべての例 次のセクションでは、コネクタの既定のフィールド区切り記号設定を使用することを前提としています。

• 値の区切り: コンマ (,)
• 複数値区切り記号: Semi-Colon (;)
• テキスト修飾子: 二重引用符 (")

例: テキスト修飾

文字列値に区切り記号として解釈される文字 (コンマなど) が含まれている場合は、CSV パーサーが文字列を 1 つのフィールドとして正しく解釈できるように、値を修飾する必要があります。

次のセクションの CSV の例では、 DisplayName フィールドに修飾テキストとして書式設定された値がどのように含まれているかを示します。

EmployeeID,DisplayName
E001,"Smith, John"
E002,"Doe, Jane"
E003,"Perez, Juan"

例: 複数値を持つ文字列を区切る

1 つの文字列フィールド内に複数の文字列値を指定するには、 値を複数値区切り記号で区切ります。 次のセクション CSV の例では、複数の値を持つ ProxyAddress フィールドの方法を示します。

EmployeeID,DisplayName,ProxyAddresses
E001,"Smith, John",SMTP:john.smith@contoso.com;smtp:js001@contoso.com
E002,"Doe, Jane",SMTP:jane.doe@contoso.com;smtp:jd002@contoso.com

例: 参照フィールド

CSV ファイルで参照値を指定するには、参照されるユーザー オブジェクトのアンカー値をフィールドに設定します。 次のセクション CSV の例では、[マネージャー] フィールドに参照先のユーザー レコードのアンカー値が含まれています。

EmployeeID,DisplayName,Manager
E001,"Smith, John",
E002,"Doe, Jane",E001
E003,"Doe, Jane", 
E004,"Perez, Juan",

例: バイナリ フィールド

CSV ファイルでバイナリ値を表現するには、CSV ファイルと同じエンコードの種類を使用する base64 文字列に変換する必要があります。 次のセクション PowerShell 関数では、文字列値を Unicode で base64 でエンコードされた文字列にエンコードする方法を示します。

function ConvertTo-Base64([string]$text) 
{
    $bytes = [System.Text.Encoding]::Unicode.GetBytes($text)
    $encodedText = [System.Convert]::ToBase64String($bytes)
    return $encodedText
}

テキストと呼ばれる入力パラメーターを受け取り、Unicode で base64 でエンコードされた文字列を返す C# の同等の関数を次に示します。

public static string ConvertToBase64(string text)
{
    byte[] bytes = System.Text.Encoding.UTF8.GetBytes(text);
    string encodedText = System.Convert.ToBase64String(bytes);
    return encodedText;
}

例: ブール型フィールド

ブール型フィールドを含む CSV ファイルでは、値を示すために True または False のテキストを使用する必要があります。 次のセクションは、

EmployeeID,DisplayName,IsActive
E001,"Smith, John",true
E002,"Doe, Jane",true
E003,"Perez, Juan",false

既知の制限事項

次の一覧には、GCSV コネクタの既知の制限事項が含まれています。

• 参照属性
  • グループ メンバー 属性以外の複数値参照属性はサポートされていません。
  • 参照値は、ユーザー オブジェクトを参照する必要があります。 グループ オブジェクトへの参照はサポートされていません。
• アンカー
  • ユーザー オブジェクトとグループ オブジェクト間のアンカー値の重複はサポートされていません。
  • アンカー属性の名前は、ユーザー スキーマとグループ スキーマ間で一意である必要があります。
• PowerShell
  • PowerShell スクリプトへの入力変数の渡しはサポートされていません。