マーケティングオートメーションAPI

マーケティングオートメーションオペレーションAPI

Version:

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

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つのバッチであっても、非同期要求とバッチ要求です。

手記

アクティビティがリクエストに含まれていない場合、連絡先はプランのエントリーアクティビティに入れられます。

連絡先を1つのプランに登録する

次の例は、コンタクトを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にイベントを送信するために使用されます。

1つのライブイベントを登録する

次の例は、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;
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
            }
        }
    }
}

この記事を改善するための提案がある場合は、お知らせください!

マーケティングオートメーションオペレーションAPI

Automation Operations APIへのアクセス

運用実績

運用の優先順位

オペレーションズ

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

連絡先を1つのプランに登録する

連絡先を複数のプランに登録する

登録申請結果

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

1つのライブ イベントを登録する

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

プランからの連絡先のパージ

特定のプランからの連絡先のパージ

すべてのプランから連絡先を消去する

1つのライブイベントを登録する

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