1. xConnectクライアントAPI (C#)

xConnectクライアントAPIの概要

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

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

xConnect Client APIは、信頼できるクライアントがHTTPS経由でコンタクトとインタラクションを作成、読み取り、更新、検索できるポータブルなC# ライブラリです。次の例は 、SitecoreコンテキストでxConnectクライアントを取得し 、IDで1つの連絡先を取得する方法を示しています。

using System;
using System.Threading.Tasks;
using Sitecore.XConnect;

namespace Documentation
{
    public class GetContact
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));

                    Task<Sitecore.XConnect.Contact> contactTask = client.GetAsync<Sitecore.XConnect.Contact>(reference, 
                    new Sitecore.XConnect.ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions() { }));

                    Contact contact = await contactTask;
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}
メモ

xConnect Client APIはトラッカーを置き換えるものではありません。ただし、トラッカーはxConnectクライアントAPIに依存してデータの読み取りと書き込みを行います。Webセッション中の連絡先の追跡の詳細については、Webトラッキング のドキュメントを参照してください。

非同期および同期拡張メソッド

xConnect Client APIは非同期ですが、Sitecore.XConnect.Client.XConnectSynchronousExtensions拡張メソッド クラスでは、ほとんどの拡張メソッドの同期バージョンを使用できます。

非同期メソッド

同期方式

筆記

GetAsync()

Get()

SubmitAsync()

Submit()

Synhronous送信にはタイムアウトの過負荷はありません。

GetBatchEnumerator()

GetBatchEnumeratorSync()

ToSearchResults()

該当なし

この拡張機能の同期バージョンは、現在利用できません。

InitializeAsync()

Initialize()

同期拡張のないメソッド

メソッドの同期バージョンがない場合は、次の例に示すように、非同期呼び出しの周囲にSuspendContextLock() メソッドを使用します。

Sitecore.XConnect.Client.XConnectSynchronousExtensions.SuspendContextLock(client.Contacts.Where(c => c.Identifiers.Any(t => t.IdentifierType == Sitecore.XConnect.ContactIdentifierType.Known)).Count);Any(t =>
大事な

非同期APIから返されたタスクに対して、.Wait()、.Result、ConfigureAwait(false).GetAwaiter().GetResult()、または同様のものを呼び出さないでください。

次の拡張メソッドには、同期に対応するメソッドはありません。

  • .FirstOrDefault()

  • .First()

  • .Single()

  • .SingleOrDefault()

  • .Count()

バッチ処理操作

xConnectクライアントAPIは、xConnect操作のバッチ処理をサポートしています。操作のバッチはシリアル化され、HTTPS経由でxConnectに送信され、xConnectサービス レイヤーによって逆シリアル化されます。次の例では、AddContact() 拡張機能は、2つのAddContactOperation操作をクライアントに追加してから、両方の操作を1つのバッチで送信します。

var firstContact = new Contact();
client.AddContact(firstContact);

var secondContact = new Contact();
client.AddContact(secondContact);

await client.SubmitAsync();

バッチがxDB Collectionデータベースに保存されたことの確認

client.Submit()/client.SubmitAsync()を呼び出した後、client.LastBatchプロパティを使用して、バッチに含まれていた操作のリストを表示できます。xDB Collectionデータベースでは、Statusプロパティの値がSucceededである任意の操作のデータを使用できます。詳細については、「操作結果の取得」を参照してください。

バッチがインデックス付けされたことの確認

xConnect Search Indexerは、変更がxDB Collectionデータベースに保存された後にxDBインデックスを更新します。バッチがインデックス化されたことを確認する方法の詳細については、「 バッチインデックス作成 」を参照してください。

例外の予測

xConnectクライアントAPIは、1つ以上の操作が失敗すると例外をスローします。次の例に示すように、xConnect Client APIの使用をtry/catchステートメントでラップし、XdbExecutionExceptionまたはXdbUnavailableExceptionをキャッチします。

using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
        try
        {
            // GET or POST some data
        }
        catch (XdbExecutionException ex)
        {
            // Handle the exception
        }
}

xConnectでの例外とエラー処理の詳細については、「 例外の処理」を参照してください。

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