Marketing Automation Operations API

概要

Marketing Automation Operations API を使用して、コンタクトの登録、イベントの登録、コンタクトのプランへのシードなどの特定の操作を実行する方法。

Marketing Automation Operations API を使用すると、Marketing Automation Engine の外部から特定の操作を実行できます。

Automation Operations API へのアクセス

サービス ロケーターを使用して、Sitecore のコンテキストで IAutomationOperationsClient にアクセスします。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using System.Collections.Generic;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();
            }
        }
    }
}

操作結果

各操作は、要求のコレクションを受け入れます。各操作呼び出しの結果はバッチ結果です。バッチ結果には、バッチ全体が成功したかどうか、または 1 つ以上の要求が失敗したかどうかを示すプロパティが含まれます。また、各リクエストの個別の結果も保持します。

BatchRequestResult
        Success : bool // Indicates whether the entire batch succeeded
        Results : IReadOnlyCollection<TRequestResult> // The results of the request

結果のタイプは、操作によって決定されます。

個々の操作結果には、(少なくとも) 要求に対して実行された操作が成功したかどうかを示すプロパティと元の要求が含まれます。元の要求を表示すると、結果をクライアントからの要求にリンクできます。

RequestResult
        Success : bool // Indicates whether the result is success
        Request : TRequest // The request the result is for

操作の優先度

要求オブジェクトの Priority プロパティは、要求をワーク プールに記録する操作に対して要求の処理優先度を決定します。

注記

RegisterLiveEvent 操作は、プールをバイパスする唯一のオペレーションです。この操作の優先度は無視されます。

操作

コンタクトをプランに登録する

表示されたコンタクトをプランに直接登録し、オプションでプラン内のアクティビティに直接登録します。オペレーション クライアントでのすべての操作は、1 つのバッチであっても、非同期のバッチ要求です。

注記

アクティビティが要求に含まれていない場合、コンタクトはプランのエントリ アクティビティに入れられます。

コンタクトを単一のプランに登録する

次の例は、コンタクトを単一のプランに登録する方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                                    var contactXconnectId = Guid.Parse("{E7B756A1-3769-46F1-AE17-7B3A198F9290}");
                                    var planId = Guid.Parse("{19FDD3A5-DBC2-4947-BEB4-69732ADEB0D8}");
                var request = new EnrollmentRequest(contactXconnectId, planId); // Contact ID, Plan ID

                request.Priority = 1; // Optional
                request.ActivityId = Guid.Parse("{C5B87651-EE70-4684-BDD9-0B464B79476D}"); // Optional
                request.CustomValues.Add("test", "test"); // Optional

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                                            request
                });
            }
            catch (Exception ex)
            {

            }
        }
    }
}

コンタクトを複数のプランに登録する

次の例は、コンタクトを複数のプランに同時に登録する方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;

namespace Documentation
{
    public class EnrollContact
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                                    var contactXconnectId = Guid.Parse("{E7B756A1-3769-46F1-AE17-7B3A198F9290}");
                                    var planId = Guid.Parse("{19FDD3A5-DBC2-4947-BEB4-69732ADEB0D8}");
                var request = new EnrollmentRequest(contactXconnectId, planId); // Contact ID, Plan ID

                request.Priority = 1;
                request.ActivityId = Guid.Parse("{C5B87651-EE70-4684-BDD9-0B464B79476D}"); // Optional
                request.CustomValues.Add("test", "test");

                                    var plan2Id = Guid.Parse("{8F5BCFED-606D-46BF-A5CD-6801AC07DC3F}");
                var secondRequest = new EnrollmentRequest(contactXconnectId, plan2Id); // Contact ID, Plan ID

                secondRequest.Priority = 9;
                secondRequest.ActivityId = Guid.Parse("{3DB8A71A-37D6-4BC7-9F48-980B176A2C43}");
                secondRequest.CustomValues.Add("test", "test");

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                                            request,
                                            secondRequest
                });
            }
                            catch (Exception ex)
            {

            }
        }
    }
}

登録要求の結果

次の例は、登録要求のバッチ全体の結果を取得する方法と、個々の登録要求に関する追加情報を取得する方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using System.Collections.Generic;

namespace Documentation
{
    public class EnrollContactResult
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                BatchEnrollmentRequestResult result = await operationsClient.EnrollInPlanDirectAsync(new[]
                {
                    new EnrollmentRequest(Guid.NewGuid(), Guid.NewGuid())
                });

                IReadOnlyCollection<EnrollmentRequestResult> batchResults = result.Results;
                bool batchSucceeded = result.Success;

                foreach (EnrollmentRequestResult requestResult in result.Results)
                {
                    bool requestSucceeded = requestResult.Success;
                    EnrollmentRequest originalRequest = requestResult.Request;
                }
            }
            catch (Exception ex)
            {
                // Handle exception
            }

        }
    }
}

ライブ イベントを登録する

Operations API を使用すると、イベントが xConnect に送信される前に、 Marketing Automation Engine にイベントを送信できます。この機能は、セッションが終了し、イベントデータが xConnect に送信される前に、Marketing Automation Engine にイベントを送信するために、トラッカーによって使用されます。

単一のライブ イベントを登録する

次の例は、単一のライブ イベントを登録する方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using Sitecore.Xdb.MarketingAutomation.Core.Results;
using Sitecore.XConnect;
using Sitecore.Xdb.MarketingAutomation.Core.Collections;
using Sitecore.Xdb.MarketingAutomation.Core.Pool;
using Sitecore.XConnect.Collection.Model;

namespace Documentation
{
    public class LiveEvent
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                // Sample contact and interaction
                var contact = new Contact();
                Guid channelId = Guid.Parse("{E99C8E17-3C9C-4B10-AC69-6B1BAFAE0711}");
                string userAgent = "Sample User Agent";
                var interaction = new Interaction(new ContactReference(contact.Id.Value), InteractionInitiator.Brand, channelId, userAgent);

                // Sample event
                interaction.Events.Add(new SearchEvent(DateTime.UtcNow) { Keywords = "sitecore" });

                // Automation custom values
                var customValues = new CustomValuesDictionary() { { "test", "test" } };

                var liveEvent = new LiveEventData(contact.Id.Value, interaction, customValues);
                var liveEventRequest = new LiveEventRequest(contact.Id.Value, liveEvent) { Priority = 200 };

                // Live event submitted BEFORE INTERACTION IS SUBMITTED
                // This means that the Automation Engine can respond to an event before it is available in xConnect
                BatchLiveEventRequestResult result = await operationsClient.RegisterLiveEventAsync(new[]
                {
                    liveEventRequest
                });
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

ライブ イベント要求の結果

BatchLiveEventRequestResult は、UpdatedEnrollments プロパティを介して影響を受ける登録の一覧を作成します。

var contact = new Contact();
Guid channelId = Guid.Parse("{E99C8E17-3C9C-4B10-AC69-6B1BAFAE0711}");
string userAgent = "Sample User Agent";
var interaction = new Interaction(new ContactReference(contact.Id.Value), InteractionInitiator.Brand, channelId, userAgent);
var customValues = new CustomValuesDictionary() { { "test", "tst" } };

var eventData = new EventData(contact, interaction, customValues);

var liveEventRequest = new LiveEventRequest(contact.Id.Value, eventData);

BatchLiveEventRequestResult result = await operationsClient.RegisterLiveEventAsync(new[]
{
    liveEventRequest
});

IReadOnlyCollection<LiveEventRequestResult> batchResults = result.Results;
bool batchSucceeded = result.Success;

foreach (LiveEventRequestResult requestResult in result.Results)
{
    bool requestSucceeded = requestResult.Success;
    LiveEventRequest originalRequest = requestResult.Request;

    // Get list of enrollments updated by event
    IEnumerable<ActivityEnrollment> enrollments = requestResult.UpdatedEnrollments;

    // Get first activity enrollment
    var firstEnrollment = enrollments.FirstOrDefault();

    // Activity enrollment properties
    var attemptsToEnroll = firstEnrollment.Attempts;
    var entryDate = firstEnrollment.EntryDate;
    var timeoutDate = firstEnrollment.TimeoutDate;
}

プランからコンタクトをパージする

Operations API を使用して、特定のプランまたはすべてのプランからコンタクトを削除できます。

特定のプランからコンタクトをパージする

次の例は、特定のプランからコンタクトをパージする方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using System.Collections.Generic;

namespace Documentation
{
    public class SinglePlanPurge
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                var contactId = Guid.Parse("{B65CB77F-0338-49C1-B6AF-1360C9560A17}");
                var planId = Guid.Parse("{3F894AC4-926F-4B26-A001-BEAB955C40F8}");

                var purgeRequest = new List<PurgeFromPlanRequest> { new PurgeFromPlanRequest(contactId, planId) };

                var result = await operationsClient.PurgeFromPlanAsync(purgeRequest);
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

すべてのプランからコンタクトをパージする

次の例は、すべてのプランからコンタクトをパージする方法を示しています。

警告

コンタクトのプールに現在あるすべてのワーク アイテムも削除されます。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using System.Collections.Generic;

namespace Documentation
{
    public class AllPlanPurge
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                var contactId = Guid.Parse("{B65CB77F-0338-49C1-B6AF-1360C9560A17}");
                var purgeRequest = new List<PurgeFromAllPlansRequest> { new PurgeFromAllPlansRequest(contactId) };

                var result = await operationsClient.PurgeFromAllPlansAsync(purgeRequest);
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

コンタクトをプランにシードする

Marketing Automation Operations API を使用して、一覧からプランにコンタクトをプログラム的に登録できます。次の例は、これを行う方法を示しています。

using Sitecore.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;
using System;
using Sitecore.Xdb.MarketingAutomation.OperationsClient;
using Sitecore.Xdb.MarketingAutomation.Core.Requests;
using System.Collections.Generic;
using Sitecore.Xdb.MarketingAutomation.Core.Enrollment;

namespace Documentation
{
    public class SeedPlan
    {
        public async void Example()
        {
            try
            {
                var operationsClient = ServiceLocator.ServiceProvider.GetService<IAutomationOperationsClient>();

                var planId = Guid.Parse("{3F894AC4-926F-4B26-A001-BEAB955C40F8}");
                var contactListId = Guid.Parse("{195B4111-EA97-4DBA-BB3C-7DDD3ADD89D8}");

                var purgeRequest = new List<SeedPlanRequest>
                {
                    new SeedPlanRequest(planId)
                    {
                        SeedFromListsSource = new SeedFromListsSource
                        {
                            LeftListIds = { contactListId },
                            ListsOperation = ListsOperation.Union
                        }
                    }
                };

                var result = await operationsClient.SeedPlanAsync(purgeRequest);
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}