xConnectクライアントAPI概要
このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。
xConnect Client APIは、信頼できるクライアントがHTTPS上で連絡先ややり取りを作成、読み取り、更新、検索できるポータブルなC#ライブラリです。以下の例は 、SitecoreコンテキストでxConnectクライアントを取得し 、IDで単一の連絡先を取得する方法を示しています:
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 Client APIに依存しています。ウェブセッション中に連絡先を追跡する方法については、ウェブトラッキング のドキュメントを参照してください。
非同期および同期拡張手法
xConnectクライアントAPIは非同期ですが、ほとんどの拡張メソッドにはSitecore.XConnect.Client.XConnectSynchronousExtensions拡張メソッドクラスで同期版があります:
非同期法
同期法
注記
GetAsync()
Get()
SubmitAsync()
Submit()
シンクロナス提出はタイムアウトオーバーロードを発生しません。
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コレクションデータベースに保存されたバッチの確認
client.Submit()/client.SubmitAsync()を呼び出した後、client.LastBatchプロパティを使ってバッチに含まれる操作のリストを見ることができます。Statusプロパティの値がSucceededされる任意の操作については、xDBコレクションデータベースでデータが利用可能です。詳細は「操作結果を入手」をご覧ください。
バッチがインデックスされていることを確認する
xConnect Search Indexerは、変更がxDBコレクションデータベースに保存された後、xDBインデックスを更新します。バッチがインデックス化されたかどうかを確認する詳細は 「バッチインデックス作成 」を参照してください。
例外を予期して
xConnectクライアントAPI 1つ以上の操作が失敗すると例外を投げます。xConnectクライアントの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における例外およびエラー処理の詳細については 、「例外処理」を参照してください。