コネクタの構成と有効化
この記事では、コネクタを取り上げ、Microsoft Dynamics 365 Commerce での構成および有効にする方法について説明します。
コネクタを使用すると Dynamics 365 Commerce サイトを外部のサード パーティ サービスに接続して、分析の収集、ログの記録、テストなどのタスクを実行できます。 一部のサード パーティ サービス プロバイダーは、そのサービスを使用する前に、サービスのライセンスを支払う必要があります。 詳細については、サービス プロバイダーに問い合わせてください。
Commerce バージョン 10.0.13 の場合、サポートされている唯一のコネクタのタイプは、実験コネクタのみです。 Commerce バージョン 10.0.17では、geoLookup コネクタのサポートが追加されました。 Commerce バージョン 10.0.21では、セグメントのプロバイダー コネクタがサポートされています。 将来のバージョンでは、他のタイプのコネクタを構成して有効化することができます。
コネクタの構成と有効化
package.json に依存関係として追加することで、Commerce サイトにコネクタを追加できます。 また、\src\connectors ディレクトリの構成パッケージ コードで直接実装することもできます。
コネクタの設定ファイル
コネクタは、\src\settings ディレクトリの connector.settings.json ファイルで、構成および有効化されます。 connector.settings.json ファイルが存在しない場合は、手動で作成できます。 このファイルでは、必要に応じて使用および構成したい実験コネクタを指定できます。 1 つの実験コネクタのみを、一度に使用できます。
次の例では、複数のコネクタ定義する connector.settings.json ファイルの内容を示します。
{
"experimentation": {
"name": "msdyn365-exp-test-2",
"config": {
"sdkKey": "EXPERIMENTATION_PROVIDER_KEY",
"key2": "value2"
},
"cacheConfig": {
"ttlInSeconds": {
"experimentation": 1800,
"experimentationDataFile": 300
},
"ttrInSeconds": {
"experimentation": 10
}
}
},
"geoLookup": {
"name": "GeoLocationTest",
"config": {
"apiKey": "GEOLOCATION_SERVICE_PROVIDER_API_KEY"
},
"cacheConfig": {
"ttlInSeconds": {
"geoLookup": 10
}
}
},
"segmentation": [
{
"id": "100",
"config": {
"apiKey": "testApiKey"
}
}
]
}
コネクタの設定ファイル スキーマ
| 要素 | 詳細 |
|---|---|
| 実験 | このオブジェクトには、テスト コネクタの開始と有効化に必要なすべての情報が含まれています。 |
| name | この設定では、使用するテスト コネクタの名前を指定します。 コネクタの名前は、コネクタの定義ファイル内に表示されます。 コネクタのタイプは、experimentationConnector である必要があります |
| config | このセクションでは、コネクタが初期化に必要な構成オブジェクトと、サード パーティ サービスとの通信を開始できます。 必要な情報については、コネクタの定義ファイルの configSchema セクション、またはコネクタの README ファイルで参照してください。 |
| cacheConfig | 一部のテスト関連のエンティティがキャッシュされる際に使用されるタイミングを指定できます。 このセクションでは、ttlInSeconds はキャッシュが古いと見なされる前にキャッシュに残ることができる時間を参照し、ttrInSeconds は、エンティティが更新される前に時間を示します。 コネクタの README ファイルには、推奨されるキャッシュ タイミングの一覧を含める必要があります。 |
| 実験 | この設定では、getExp分ments() 中に、サード パーティ プロバイダーで構成されている利用可能なテストの一覧を取得する際のキャッシュ タイミングを制御します。 既定の TTL (存続時間) は 1,800 秒 で、既定の TTR (更新時間) は 60 秒です。 |
| experimentationDataFile | この設定は、getConfigForClientClientClient() の中に、構成をクライアントに渡す際のキャッシュ タイミングを制御します 既定の TTL は 1,800 秒で、既定の TTR は 60 秒です。 |
実験コネクタ
テスト コネクタを使用すると、アプリケーションを外部テスト サービス プロバイダーに接続できます。 このタイプのコネクタをアプリケーションに追加し、それを構成して有効化することで、Commerce サイト ビルダーでテストを作成および実行し、結果を追跡して顧客に最適なエクスペリエンスを提供できます。
実験コネクタは、次の 3 つの部分で構成されます:
- JSON 形式のコネクタ定義ファイル
- プロバイダー ファイル
- リスナー ファイル
コネクタ定義ファイル
コネクタ定義ファイルは、アプリケーションに構成メタデータのデータを登録および提供するために使用されます。 このメタデータには、コネクタのタイプ、コネクタの名前、コネクタの説明、および構成スキーマが含まれます。 コネクタ定義ファイルの名前は、フォーマットの <CONNECTOR_NAME>.connector.json であります。
次の例は、コネクタ定義ファイルのコンテンツを示します。
{
"$type": "experimentationConnector",
"name": "msdyn365-exp-test",
"description": "Test connector implementation",
"configSchema": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "The project ID to use for experimentation"
}
},
"required": ["projectId"]
}
}
コネクタ定義ファイルのスキーマ
| 要素 | 詳細 |
|---|---|
| $type | コネクタのタイプ。 前の例の定義ファイルは実験コネクタ用で、タイプは experimentationConnector です。 |
| name | コネクタの名前。 この名前は、すべてのコネクタ間で一意でなければなりません。 |
| 説明 | コネクタの説明。 |
| configSchema | 構成スキーマ。 構成スキーマを使用すると、アプリケーションの起動時に提供された構成を検証する JSON スキーマが提供され、コネクタが正しく初期化できます。 たとえば、コネクタを初期化する場合は、サード パーティのテスト サービスとの通信に必要な API 呼び出しを行うための projectId 値が必要です。 上記の JSON ファイルの値を特定し、提供される構成がコネクタの要件に一致することを確認します。 |
プロバイダー ファイル
実験プロバイダー ファイルでは、コネクタを初期化が必要です。 これにより、コネクタは Commerce サイト ビルダーと対話して、サード パーティのテスト サービスで構成されている使用可能なテストの一覧を表示できます。 プロバイダー ファイル名は、フォーマットの <CONNECTOR_NAME>.provider.ts にあります。
プロバイダー ファイルには、次のインターフェイスを実装する必要があります。
export interface IExperimentationProvider {
/**
* Allows the experimentation connector to do any startup related tasks
* using the config provided by the partner.
*
* This method is only called once during server startup.
* @param config The configuration provided in connector.settings.json
*/
initialize(config: any): Promise<boolean>;
/**
* Returns the configuration that should be passed to the experimentation connector
* when it is initialized client-side
*/
getConfigForClientSideInit(): Promise<any>;
/**
* Initializes the experimentation provider on the browser (client-side) so that
* it may activate experiments for a user.
*
* @param config The config that is required to initialize the experimentation connector
* client-side. The result of getConfigForClientSideInit() is passed into this method
*/
initializeClientSide(config: any): boolean;
/**
* Returns a list of all the experiments currently configured whether active or not.
* This list will be cached and periodically refreshed.
* @param page Optional argument that specifies the page to return.
* @param items Optional argument that specifies the maximum number of objects to return per request.
*/
getExperiments(page?: string, items?: string): Promise<IExperiments[]>;
/**
* Returns a list of experiments and variants a user will be a part of based
* off the userId. Optional attributes can provide the connector with additional criteria
* to determine which experiments a user should be a part of.
*
* @param userId userId unique to a user if signed in or unique to a session if user is anonymous.
* userId will be generated from hash if user is signed-in to deterministically generate sanitized userIds.
* @param attributes Optional user related attributes
*/
getVariantsForUser(userId: string, attributes?: {
[index: string]: string;
}): IVariants[];
/**
* Activates experiment(s) a user is currently being served. This call will be made
* client-side after the connector has been initialized client-side
*
* @param userId userId unique to a user if signed in or unique to a session if user is anonymous.
* userId will be generated from hash if user is signed-in to deterministically generate sanitized userIds.
* @param experiments The experiments the user is participating in.
* @param attributes Optional user related attributes
*/
activateExperiment(userId: string, experiments: IVariants[], attributes?: {
[index: string]: string;
}): boolean;
}
また、関数の中には、戻りタイプと引数に次のタイプを使用する機能があります。
/**
* Variations on each experiment
*/
export interface IVariations {
friendlyName: string;
id: string;
status: State;
weight?: string;
}
/**
* Experiments
*/
export interface IExperiments {
friendlyName: string;
id: string;
status: State;
variations: IVariations[];
createdDate?: string;
lastModifiedDate?: string;
lastModifiedBy?: string;
description?: string;
type?: string;
link?: string;
resultLink?: string;
}
/**
* Experiments
*/
export interface IVariants {
variantId: string;
experimentId: string;
moduleId?: string;
}
リスナー ファイル
実験リスナー ファイルでは、ユーザー変換イベントの追跡が必要です。 リスナー ファイルは、ソフトウェア開発キット (SDK) のイベント ログ記録フレームワークに接続するログ インターフェイスを実装し、特定のユーザー アクションを登録します。 リスナー ファイル名は、フォーマットの <CONNECTOR_NAME>.listener.ts にあります。
リスナー ファイルには、次のインターフェイスを実装する必要があります。
export interface IExperimentationListener {
/**
* Initializes the experimentation listener on the browser (client-side) so that
* it may keep track of any conversion events related to the current experiments.
*
* @param config The config that is required to initialize the experimentation connector
* client-side. The result of the provider file's getConfigForClientSideInit() is passed into this method
* @param userId The user ID of the current user being served the experiment
*/
initializeClientSide(config: any, userId: string): boolean;
/**
* Tracks a successful user conversion event.
*
* @param eventType The name of the event that occurred
* @param payload Any additional tags or data related to the conversion event
* @param attributes Optional parameter containing user attributes pertaining to the user that triggered the event
*/
trackEvent(eventType: string, payload: any, attributes?: any): void;
}
GeoLookup コネクタ
geoLookup コネクタを使用すると、位置情報サービス プロバイダーに接続できます。 このタイプのコネクタを e コマース サイトに追加し構成することで、e コマース サイト ユーザーの位置情報を生成できます。
geoLookup コネクタは、次の 2 つの部分で構成されています。
- JSON 形式のコネクタ定義ファイル
- プロバイダー ファイル
コネクタ定義ファイル
コネクタ定義ファイルは、アプリケーションに構成メタデータのデータを登録および提供するために使用されます。 プロバイダー ファイルの名前は、フォーマットの <CONNECTOR_NAME>.connector.json にあります。 メタデータには、次のコネクタ定義ファイルの例に示すように、コネクタのタイプ、コネクタの名前、コネクタの説明、および構成スキーマが含まれます。
{
"$type": "geoLookupConnector",
"name": "msdyn365-geoLookup-test",
"description": "Test connector implementation",
"configSchema": {
"type": "object",
"properties": {
"apiKey": {
"type": "string",
"description": "Api key for using the geoLookup API"
}
},
"required": ["apiKey"]
}
}
コネクタ定義ファイルのスキーマ
| 要素 | 詳細 |
|---|---|
| $type | コネクタのタイプ。 前の例の定義ファイルは geoLookup コネクタ用で、タイプは geoLookupConnector です。 |
| name | コネクタの名前。 この名前は、すべてのコネクタ間で一意でなければなりません。 |
| 説明 | コネクタの説明。 |
| configSchema | 構成スキーマ。 構成スキーマを使用すると、アプリケーションの起動時に提供された構成を検証する JSON スキーマが提供され、コネクタが正しく初期化できます。 たとえば、コネクタを初期化する場合は、サード パーティ サービスとの通信に必要な API 呼び出しを行うための projectId 値が必要です。 上記の JSON ファイルの値を特定し、提供される構成がコネクタの要件に一致することを確認します。 |
プロバイダー ファイル
プロバイダー ファイルでは、コネクタを初期化が必要です。 プロバイダー ファイル名は、フォーマットの <CONNECTOR_NAME>.provider.ts にあります。
geoLookup プロバイダー ファイルには、次の IGeoLookupProvider インターフェイスを実装する必要があります。
export interface IGeoLookupProvider {
/**
* Allows the geoLocation connector to do any startup related tasks
* using the config provided..
*
* This method is only called once during server startup.
* @param config The configuration provided in connector.settings.json
*/
// tslint:disable:no-any
initialize(config: any): Promise<boolean>;
/**
* Geolocation lookup connector will get location information based on the ip address
* @param ip The ip address
*/
getGeoInformation(ip: string): Promise<IGeoLocation>;
}
また、関数の中には、戻りタイプと引数に次のタイプを使用する機能があります。
export interface IGeoLocation {
country?: string;
region?: string;
city?: string;
zipCode?: string;
[otherProperty: string]: string | undefined;
}
生成された位置情報は、equestContext.geoLocation オブジェクトに保存されます。
geoLookup コネクタの有効化と構成
コネクタは、SDK の \src\settings ディレクトリの connector.settings.json ファイルで、有効化および構成されます。
次の例では、connector.settings.json ファイルで有効となっている geoLookup コネクタを表示します。
{
"geoLookup": {
"name": "GeoLocationTest",
"config": {
"apiKey": "GEOLOCATION_SERVICE_PROVIDER_API_KEY"
},
"cacheConfig": {
"ttlInSeconds": {
"geoLookup": 10
}
}
}
}
コネクタの設定ファイル スキーマ
| 要素 | 詳細 |
|---|---|
| geoLookup | このオブジェクトには、geoLookup コネクタの開始と有効化に必要なすべての情報が含まれています。 |
| name | この設定では、geoLookup コネクタの名前を指定します。 コネクタの名前は、geoLookup コネクタの定義ファイル内に表示されます。 コネクタ タイプは、必ず geoLookupConnector です。 |
| config | このセクションでは、コネクタが初期化と通信に必要な構成オブジェクトと、サード パーティ サービスとの通信を開始できます。 必要な情報については、geoLookup コネクタの定義ファイルの configSchema セクション、またはコネクタの README ファイルで参照してください。 apiKey 値を、サービス プロバイダーによって提供される値へ変更します。 |
| cacheConfig | 位置情報エンティティがキャッシュされる際に使用されるタイミングを指定できます。 ttlInSeconds 値は、エンティティが古いとみなされる前にキャッシュに残る時間を秒単位で示します。 ttrInSeconds 値は、エンティティが更新される前の時間を秒単位で指定します。 geoLookup コネクタの README ファイルには、推奨されるキャッシュ タイミングの一覧を含める必要があります。 |
| geoLookup | この設定は、サード パーティのサービス プロバイダーによって生成される位置情報を取得するキャッシュのタイミングを制御します。 既定値 TTL は 120 秒です。 |
セグメント プロバイダー コネクタ
セグメント プロバイダーは、サード パーティのソースから作業データ ソース属性 (年、市区町会、郵便番号、国など) を取得および分析するビジネス ロジックを含み、e コマース サイト内で使用できる 1 つ以上の単純なターゲット セグメントに減らします。 複数のセグメント プロバイダーを同時に登録できます。
セグメント コネクタは、次の 2 つの部分で構成されています。
- JSON 形式のコネクタ定義ファイル
- プロバイダー ファイル
コネクタ定義ファイル
コネクタ定義ファイルは、アプリケーションに構成メタデータのデータを登録および提供するために使用されます。 プロバイダー ファイルの名前は、フォーマットの <CONNECTOR_NAME>.connector.json にあります。 メタデータには、次のコネクタ定義ファイルの例に示すように、コネクタのタイプ、コネクタの名前、コネクタの説明、および構成スキーマが含まれます。
{
"$type": "segmentationConnector",
"name": "msdyn365-seg-test-1",
"id": "100",
"description": "Test connector implementation",
"configSchema": {
"type": "object",
"properties": {
"apiKey": {
"type": "string",
"description": "Api key for using the third party service API"
}
},
"required": ["apiKey"]
},
"segmentations": [
{
"id": "101",
"name": "Age",
"type": "integer",
"maxValue": 100,
"minValue": 1
},
{
"id": "102",
"name": "Gender",
"type": "enum",
"enum": ["male", "female"],
"enumNames": ["Male", "Female"]
},
{
"id": "103",
"name": "Home type",
"type": "enum",
"enum": ["house", "condo", "townhouse", "apartment"],
"enumNames": ["House", "Condo", "Townhouse", "Apartment"]
},
]
}
コネクタ定義ファイルのスキーマ
| 要素 | 詳細 |
|---|---|
| $type | コネクタのタイプ。 前の例の定義ファイルは geoLookup コネクタ用で、タイプは segmentationConnector です。 |
| name | コネクタの名前。 この名前は、すべてのコネクタ間で一意でなければなりません。 |
| id | コネクタの ID。 ID は、すべてのコネクタ間で一意でなければなりません。 |
| 説明 | コネクタの説明。 |
| configSchema | 構成スキーマ。 構成スキーマを使用すると、アプリケーションの起動時に提供された構成を検証する JSON スキーマが提供され、コネクタが正しく初期化できます。 たとえば、コネクタを初期化する場合は、サード パーティ サービスとの通信に必要な API 呼び出しを行うための projectId 値が必要です。 上記の JSON ファイルの値を特定し、提供される構成がコネクタの要件に一致することを確認します。 |
セグメント スキーマ
| 要素 | 詳細 |
|---|---|
| ID | 現在のセグメント プロバイダーの範囲の固有 ID。 |
| Name | ユーザー インターフェイスに表示されるセグメント名。 |
| 型 | 整数、文字列、列挙、bool |
| 列挙型 | 列挙タイプ、列挙値の配列にのみ適用されます。 |
| enumName | 列挙タイプのみに適用されるのは、ユーザー インターフェイスに表示される列挙名の配列です。 |
| maxValue | 整数タイプのみに適用されるのは、整数セグメントで許容される最大値です。 |
| minValue | 整数タイプのみに適用されるのは、整数セグメントで許容される最小値です。 |
プロバイダー ファイル
プロバイダー ファイルでは、コネクタを初期化が必要です。 プロバイダー ファイル名は、フォーマットの <CONNECTOR_NAME>.provider.ts にあります。
プロバイダー ファイルには、次のインターフェイスを実装する必要があります。
export interface ISegmentationProvider {
/**
* Allows the segmentation connector to do any startup related tasks
* using the config provided.
*
* This method is only called once during server startup.
* @param config The configuration provided in connector.settings.json
*/
initialize(config: any): Promise<boolean>;
/**
* Geolocation lookup connector will get location information based on the ip address
* @param ip The ip address
*/
getSegmentations(userId: string, segmentationIds: string[], requestContext: IRequestContext): Promise<ISegmentations>;
}
また、関数の中には、戻りタイプと引数に次のタイプを使用する機能があります。
declare type ISegmentation = number | string | bool;
export interface ISegmentations {
[segmentationID: string]: ISegmentation;
}
getSegmentations() 関数の出力は、「キー」がセグメント ID で「値」はセグメントについて解決された値であるキー値オブジェクトです。
セグメント プロバイダー コネクタの有効化と構成
コネクタは、SDK の \src\settings ディレクトリの connector.settings.json ファイルで、有効化および構成されます。
次の例では、connector.settings.json ファイルで有効となっているセグメント プロバイダー コネクタを表示します。
{
"geoLookup": {
"name": "GeoLocationTest",
"config": {
"apiKey": "GEOLOCATION_SERVICE_PROVIDER_API_KEY"
},
"cacheConfig": {
"ttlInSeconds": {
"geoLookup": 10
}
}
},
"segmentation": [
{
"id": "100",
"config": {
"apiKey": "testApiKey"
}
}
]
}
Connector.settings.json 定義ファイルのスキーマ
| 要素 | 詳細 |
|---|---|
| セグメント | このオブジェクトには、セグメント コネクタの開始と有効化に必要なすべての情報が含まれています。 |
| id | この設定では、セグメント コネクタの ID を指定します。 コネクタの ID は、セグメント コネクタの定義ファイル内に表示されます。 |
| config | このセクションでは、コネクタが初期化と通信に必要な構成オブジェクトと、サード パーティ サービスとの通信を開始できます。 必要な情報については、geoLookup コネクタの定義ファイルの configSchema セクション、またはコネクタの README ファイルで参照してください。 apiKey 値を、サービス プロバイダーによって提供される値へ変更します。 |