ゲストデータ拡張機能REST API v2 (レガシ)

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

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

大事な

このREST APIの新しいバージョン(v2.1)が利用可能です。ゲストREST APIを初めて使用する場合は、新しいバージョンを使用してください。または、すでに古いバージョンを使用している場合は、v2とv2.1の違いについて読んでアップグレードできるようにしてください。

ゲストデータエクステンションは、任意の名前と値のペア (属性) を指定できる配列です。ゲストデータエクステンションはオプションであり、組織はゲストに関するより堅牢な情報を取得できます。その後、ゲストデータをバッチセグメンテーションで使用し、ゲストプロファイルで表示できます。

ゲストデータエクステンションを作成するときは、選択した属性のオブジェクトをSitecore CDPに送信します。

組織で1つのシステムから1つの要求ですべてのゲストデータエクステンションを送信する場合は、次のエンドポイントを使用します。

POST v2/guests/{:placeholder-token:}<guestRef>{/:placeholder-token:}/extext

キーと値のペアのキーの名前は、ゲストデータエクステンションになります。その後、Sitecore CDPはオブジェクトをゲストプロファイルに保存し、バッチセグメンテーションUIで選択できるようにします。

または、組織が複数のソースシステムからゲストデータエクステンションを送信する場合は、ゲストデータエクステンショングループを使用して、他のソースシステムのデータがリクエストごとに上書きされないようにする必要があります。

次に、ゲストデータエクステンションの使用に関するガイドラインを示します。

データエクステンションデータをオブジェクトのextensions配列に配置します。
name属性はextである必要があります。または、複数のソースからゲスト拡張データを送信する場合は、ext1、ext2、ext3、ext4 、またはext5である必要があります。
key属性はdefaultである必要があります。
ゲストデータエクステンションには、最大100個の属性があります。

以下は、データエクステンションで属性を使用するためのガイドラインのリストです。

属性名は、JSON RFC 7159仕様に従って、英数字 A-Z、a-z、0-9 である必要があります。
データエクステンションの属性名はキャメルケースで記述する必要があります。
属性名は一意である必要があります。
属性名は意味のあるものにすることをお勧めします。

この例では、loyaltyTier、rewardBalance、vipMember、およびloyaltyNumberがゲストデータエクステンションになります。

curl -X POST '<baseURL>/v2/guests/3bc77f6e-368a-4343-bb75-222f8d5e77a8/extext' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
    "key": "default",
    "loyaltyTier": "level2",
    "rewardBalance": 5012.25,
    "vipMember": true,
    "loyaltyNumber": 3452
}'

複数のソースシステムからのゲスト拡張データの送信

組織は、複数のソースシステムからゲスト拡張データをSitecore CDPに送信できます。各ゲストデータエクステンショングループには、最大100個のカスタム属性を含めることができます。

たとえば、組織でロイヤルティシステムからゲストデータエクステンションを送信してロイヤルティデータを取得し、顧客関係管理 (CRM) システムを使用してメール設定や代替メールアドレスなどを取得することができます。

警告

複数のソース・システムからデータを送信するには、ソース・システムごとに異なる拡張グループ名を使用する必要があります。これを行わないと、ソースシステムがゲスト拡張データをSitecore CDPに送信するたびに、他のソースシステムから送信されたゲスト拡張データが上書きされます。これは、ゲストデータ拡張機能REST APIが要求に含まれるすべてのキーと値のペアを上書きし、API要求に含まれていないキーと値を削除するためです。

組織では、最大6つのゲストデータエクステンショングループを使用できます。各グループ名は、異なるソース・システムを表します。拡張グループ名は、次のように使用する必要があります。

ext
ext1
ext2
ext3
ext4
ext5

エンドポイントには、ゲストデータエクステンショングループの名前を含める必要があります。リクエストの本文に含める必要はありません。

次のリクエストでは、ゲストデータエクステンショングループ名としてext2を使用しています。

POSTv2/guests/{:placeholder-token:}guestRef{/:placeholder-token:}/extext2

たとえば、ロイヤルティシステムからSitecore CDPにデータを送信する場合、組織はエンドポイントで常に同じゲスト拡張グループ名を使用する必要があります。同じゲスト拡張グループ名を使用して、他のソースシステムから拡張を送信しないでください。

メモ

キーと値のペアのキー名に一貫したプレフィックスを使用します。これにより、ユーザーはバッチセグメンテーションUIで特定のソースシステムのすべてのゲストデータエクステンションをすばやく見つけることができます。たとえば、プレフィックスとしてmemberを使用すると、すべてのゲストデータエクステンションmember UIにアルファベット順にまとめて表示されます。これにより、他のソースシステムから送信されたキーと値のペアを上書きすることもなくなります。たとえば、ロイヤルティメンバーシップとCRMシステムに対してnumberを持つキーが存在するとします。

ユーザーは、次の例に示すように、バッチセグメンテーションでゲストデータエクステンションにアクセスできます。

Accessing guest data extensions in batch segmentation

この例では、memberCardBalance、memberCardCategory、memberCardTypeが組織のロイヤルティシステムから送信されるゲストデータエクステンションになります。

curl -X POST '<baseURL>/v2/guests/3bc77f6e-368a-4343-bb75-222f8d5e77a8/extext2' \
-u '<username>:<password>' \
-H 'Accept: application/json' \
--data-raw '
{
    "key": "default",
    "memberCardBalance": 8938,
    "memberCardCategory": "promoter",
    "memberCardType": "platinum"
}'

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

ゲスト データ拡張機能REST API v2 (レガシ)

複数のソースシステムからのゲスト拡張データの送信

ゲストデータ拡張機能REST API v2 (レガシ)