パートナースキーマ設定

Experience Platform では、スキーマを使用して、一貫性のある再利用可能な方法でデータの構造を記述します。データが Platform に取り込まれると、XDM スキーマに応じて構造化されます。デザインの原則やベストプラクティスなど、スキーマ構成モデルについて詳しくは、スキーマ構成の基本を参照してください。

Destination SDK で宛先を作成する場合、宛先プラットフォームによって使用される独自のパートナースキーマを定義できます。これにより、ユーザーに、Platform から宛先プラットフォームが認識する特定のフィールドにプロファイル属性をマッピングする機能を提供します。これらは、すべて Platform UI 内で実行できます。

宛先用にパートナースキーマを設定する場合、宛先プラットフォームでサポートされているフィールドマッピングを微調整できます。以下に例を示します。

  • ユーザーは、phoneNumber XDM 属性を宛先プラットフォームでサポートされている phone 属性にマッピングできます。
  • 宛先内のサポートされるすべての属性のリストを取得するために Experience Platform が動的に呼び出す、動的パートナースキーマを作成します。
  • 宛先プラットフォームが必要とする必須のフィールドマッピングを定義します。

このコンポーネントがDestination SDKで作成される統合のどこに適合するかを把握するには、 設定オプションドキュメントの図を参照するか、Destination SDKを使用したファイルベースの宛先の設定方法に関するガイドを参照してください。

/authoring/destinations エンドポイントを介してスキーマ設定を設定できます。このページに表示されるコンポーネントを設定できる、詳細な API 呼び出しの例については、以下の API リファレンスページを参照してください。

この記事では、宛先に使用できる、サポートされるすべてのスキーマ設定オプションを説明し、Platform UI で顧客に何が表示されるかを示します。

IMPORTANT
Destination SDK でサポートされているすべてのパラメーター名および値は、大文字と小文字が区別 ​されます。大文字と小文字を区別することに関するエラーを避けるために、ドキュメントに示すように、パラメーター名および値を正確に使用してください。

サポートされる統合タイプ supported-integration-types

このページで説明される機能をサポートする統合のタイプについて詳しくは、以下の表を参照してください。

統合タイプ
機能のサポート
リアルタイム(ストリーミング)統合
ファイルベースの(バッチ)統合

サポートされるスキーマ設定 supported-schema-types

Destination SDK は、以下の複数のスキーマ設定をサポートします。

  • 静的スキーマは、schemaConfig セクションの profileFields 配列を通じて定義されます。静的スキーマでは、profileFields 配列で Experience Platform UI に表示される必要がある各ターゲット属性を定義します。スキーマを更新する必要がある場合、宛先設定を更新する必要があります。
  • 動的スキーマは、動的スキーマサーバーと呼ばれる、追加の宛先サーバータイプを使用して、サポートされているターゲット属性を動的に取得し、独自の API に基づいて動的にスキーマを生成します。動的スキーマは、profileFields 配列を使用しません。スキーマを更新する必要がある場合、宛先設定を更新する必要はありません。代わりに、動的スキーマサーバーは、更新されたスキーマを API から取得します。
  • スキーマ設定内では、必須の(または事前定義済みの)マッピングを追加するオプションがあります。これらは、ユーザーが Platform UI で表示できるマッピングですが、宛先への接続を設定する際には変更できません。例えば、常に宛先に送信されるように、メールアドレスフィールドを強制できます。

schemaConfig セクションは、以下の節で示すように、必要とするスキーマのタイプに応じて、複数の設定パラメーターを使用できます。

静的スキーマの作成 attributes-schema

プロファイル属性を使用して静的スキーマを作成するには、以下に示すように、profileFields 配列でターゲット属性を定義します。

"schemaConfig":{
      "profileFields":[
           {
              "name":"phoneNo",
              "title":"phoneNo",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the mobilePhone.number value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"firstName",
              "title":"firstName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.firstName value in Experience Platform could be firstName on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           },
                      {
              "name":"lastName",
              "title":"lastName",
              "description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.lastName value in Experience Platform could be phoneNo on your side.",
              "type":"string",
              "isRequired":false,
              "readOnly":false,
              "hidden":false
           }
        ],
      "useCustomerSchemaForAttributeMapping":false,
      "profileRequired":true,
      "segmentRequired":true,
      "identityRequired":true,
      "segmentNamespaceAllowList": ["someNamespace"],
      "segmentNamespaceDenyList": ["someOtherNamespace"]

}
パラメーター
タイプ
必須/オプション
説明
profileFields
配列
オプション
顧客がプロファイル属性をマッピングする宛先プラットフォームによって受け入れられるターゲット属性の配列を定義します。profileFields 配列を使用する場合、useCustomerSchemaForAttributeMapping パラメーター全体を省略できます。
useCustomerSchemaForAttributeMapping
ブール値
オプション

顧客スキーマから profileFields 配列で定義する属性への属性のマッピングを有効または無効にします。

  • true に設定すると、ユーザーには、マッピングフィールドのソース列のみが表示されます。この場合、profileFields は適用されません。
  • false に設定すると、ユーザーは、ユーザーのスキーマから profileFields 配列で定義した属性にソース属性をマッピングできます。

デフォルト値は false です。

profileRequired
ブール値
オプション
ユーザーが Experience Platform から宛先プラットフォームのカスタム属性にプロファイル属性をマッピングできる必要がある場合は、true を使用します。
segmentRequired
ブール値
必須
このパラメーターは、Destination SDK に必須で、常に true に設定される必要があります。
identityRequired
ブール値
必須
ユーザーが Experience Platform から profileFields 配列で定義した属性に ID タイプをマッピングできる必要がある場合は、true に設定します。
segmentNamespaceAllowList
配列
オプション
ユーザーがオーディエンスを宛先にマッピングできる特定のオーディエンス名前空間を定義します。このパラメーターを使用して、Platform ユーザーが配列で定義したオーディエンス名前空間のみからオーディエンスを書き出しするように制限します。このパラメーターは、segmentNamespaceDenyList と共に使用することはできません。

例:"segmentNamespaceAllowList": ["AudienceManager"] を使用すると、ユーザーは AudienceManager 名前空間のオーディエンスのみをこの宛先にマッピングできます。

ユーザーが任意のオーディエンスを宛先に書き出しできるようにするには、このパラメーターを無視します。

segmentNamespaceAllowListsegmentNamespaceDenyList の両方が設定にない場合、ユーザーはセグメント化サービスからのオーディエンスのみを書き出しできます。
segmentNamespaceDenyList
配列
オプション
ユーザーが配列で定義したオーディエンス名前空間から宛先にオーディエンスをマッピングできないように制限します。segmentNamespaceAllowed と共に使用することはできません。

例:"segmentNamespaceDenyList": ["AudienceManager"] は、ユーザーが AudienceManager 名前空間のオーディエンスをこの宛先にマッピングすることをブロックします。

ユーザーが任意のオーディエンスを宛先に書き出しできるようにするには、このパラメーターを無視します。

segmentNamespaceAllowedsegmentNamespaceDenyList の両方が設定にない場合、ユーザーはセグメント化サービスからのオーディエンスのみを書き出しできます。

接触チャネルに関係なく、すべてのオーディエンスを書き出しできるようにするには、"segmentNamespaceDenyList":[] を設定します。

以下の画像に、結果の UI エクスペリエンスを示します。

ユーザーがターゲットマッピングを選択する場合、profileFields 配列で定義されたフィールドを確認できます。

ターゲット属性画面を示す UI 画像。

属性を選択すると、ターゲットフィールド列で確認できます。

属性を含む静的ターゲットスキーマを示す UI 画像

動的スキーマの作成 dynamic-schema-configuration

Destination SDK は、動的パートナースキーマの作成をサポートしています。静的スキーマとは対照的に、動的スキーマは、profileFields 配列を使用しません。代わりに、動的スキーマは、スキーマ設定を取得する独自の API に接続する、動的スキーマサーバーを使用します。

IMPORTANT
動的スキーマを作成する前に、動的スキーマサーバーを作成する必要があります。

動的スキーマ設定では、以下に示すように、profileFields 配列が dynamicSchemaConfig セクションによって置き換えられます。

"schemaConfig":{
   "dynamicSchemaConfig":{
      "dynamicEnum": {
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"DYNAMIC_SCHEMA_SERVER_ID",
         "value": "Schema Name",
         "responseFormat": "SCHEMA"
      }
   },
   "profileRequired":true,
   "segmentRequired":true,
   "identityRequired":true
}
パラメーター
タイプ
必須/オプション
説明
dynamicEnum.authenticationRule
文字列
必須

Platform の顧客が宛先に接続する方法を示します。使用できる値は CUSTOMER_AUTHENTICATIONPLATFORM_AUTHENTICATIONNONE
です。

  • Platform の顧客がこちらで説明しているいずれかの認証方法でお使いのシステムにログインする場合は、CUSTOMER_AUTHENTICATION を使用します。
  • アドビと宛先との間にグローバル認証システムがあり、Platform の顧客が宛先への接続に認証資格情報を提供する必要がない場合は、PLATFORM_AUTHENTICATION を使用します。この場合、資格情報 API を使用して、資格情報オブジェクトを作成する必要があります。
  • 宛先プラットフォームにデータを送信するために認証が必要ない場合は、NONE を使用します。
dynamicEnum.destinationServerId
文字列
必須
動的スキーマサーバーの instanceId。この宛先サーバーには、動的スキーマを取得するために Experience Platform が呼び出す API エンドポイントが含まれます。
dynamicEnum.value
文字列
必須
動的スキーマサーバー設定で定義された、動的スキーマの名前。
dynamicEnum.responseFormat
文字列
必須
動的スキーマを定義する際は、常に SCHEMA に設定します。
profileRequired
ブール値
オプション
ユーザーが Experience Platform から宛先プラットフォームのカスタム属性にプロファイル属性をマッピングできる必要がある場合は、true を使用します。
segmentRequired
ブール値
必須
このパラメーターは、Destination SDK に必須で、常に true に設定される必要があります。
identityRequired
ブール値
必須
ユーザーが Experience Platform から profileFields 配列で定義した属性に ID タイプをマッピングできる必要がある場合は、true に設定します。

必須のマッピング required-mappings

スキーマ設定内では、静的または動的スキーマに加えて、必須の(または事前定義済みの)マッピングを追加するオプションがあります。これらは、ユーザーが Platform UI で表示できるマッピングですが、宛先への接続を設定する際には変更できません。

例えば、常に宛先に送信されるように、メールアドレスフィールドを強制できます。

NOTE
現在、必須のマッピングの以下の組み合わせがサポートされています。
  • 必須のソースフィールドと必須の宛先フィールドを設定できます。この場合、ユーザーは、2 つのうちどちらかのフィールドを編集または選択できず、選択した方のみを表示できます。
  • 必須の宛先フィールドのみを設定できます。この場合、ユーザーは、宛先にマッピングするためのソースフィールドを選択できます。
必須のソースフィールドのみの設定は、現在、サポート​ されていません

必須のマッピングを含むスキーマ設定と、これらがバッチ宛先に対するデータの有効化ワークフローのマッピング手順でどのように見えるかについて、以下の 2 つ例を参照してください。

必須のソースおよび宛先マッピング

以下に、必須のソースと宛先の両方のマッピングの例を示します。ソースと宛先の両方のフィールドが必須のマッピングとして指定されている場合、ユーザーは、2 つのうちどちらかのフィールドを選択または編集できず、事前定義済みの選択のみを表示できます。

code language-json
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "sourceType": "text/x.schema-path",
        "source": "personalEmail.address",
        "destination": "personalEmail.address"
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
パラメーター タイプ 必須/オプション 説明
requiredMappingsOnly ブール値 オプション これが true に設定されている場合、ユーザーは、requiredMappings 配列で定義する必須のマッピング以外に、アクティベーションフローで他の属性および ID をマッピングできません。
requiredMappings.sourceType 文字列 必須

source フィールドのタイプを示します。サポートされている値:

  • text/x.schema-pathsource フィールドが XDM スキーマからのプロファイル属性の場合に、この値を使用します。
  • text/x.aep-xlsource フィールドが正規表現で定義されている場合に、この値を使用します。例:iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\")
  • text/plainsource フィールドがマクロテンプレートで定義されている場合に、この値を使用します。現在、サポートされている唯一のマクロテンプレートは、metadata.segment.alias です。
requiredMappings.source 文字列 必須

ソースフィールドの値を示します。サポートされる値タイプを以下に示します。

  • XDM プロファイル属性。例:personalEmail.address。ソース属性が XDM プロファイル属性の場合は、sourceType パラメーターを text/x.schema-path に設定します。
  • 正規表現。例:iif(segmentMembership.ups.aep_seg_id.status==\"exited\", \"1\", \"0\")。ソース属性が正規表現の場合は、sourceType パラメーターを text/x.aep-xl に設定します。
  • マクロテンプレート。例:metadata.segment.alias。ソース属性がマクロテンプレートの場合は、sourceType パラメーターを text/plain に設定します。現在、サポートされている唯一のマクロテンプレートは、metadata.segment.alias です。
requiredMappings.destination 文字列 必須 ターゲットフィールドの値を示します。ソースと宛先の両方のフィールドが必須のマッピングとして指定されている場合、ユーザーは、2 つのうちどちらかのフィールドを選択または編集できず、選択した方のみを表示できます。

その結果、Platform UI の​ ソースフィールド ​と​ ターゲットフィールド ​の両方のセクションが灰色表示になります。

UI アクティベーションフローでの必須のマッピングの画像。

必須の宛先マッピング

以下に、必須の宛先マッピングの例を示します。宛先フィールドのみが必須として指定されている場合、ユーザーは、マッピングするソースフィールドを選択できます。

code language-json
"schemaConfig": {
    "requiredMappingsOnly": true,
    "requiredMappings": [
      {
        "destination": "identityMap.ExamplePartner_ID",
        "mandatoryRequired": true,
        "primaryKeyRequired": true
      }
    ]
}
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto
パラメーター タイプ 必須/オプション 説明
requiredMappingsOnly ブール値 オプション これが true に設定されている場合、ユーザーは、requiredMappings 配列で定義する必須のマッピング以外に、アクティベーションフローで他の属性および ID をマッピングできません。
requiredMappings.destination 文字列 必須 ターゲットフィールドの値を示します。宛先フィールドのみが指定されている場合、ユーザーは、宛先にマッピングするソースフィールドを選択できます。
mandatoryRequired ブール値 オプション マッピングが必須の属性としてマークされる必要があるかどうかを示します。
primaryKeyRequired ブール値 オプション マッピングが重複排除キーとしてマークされる必要があるかどうかを示します 。

その結果、Platform UI の​ ターゲットフィールド ​セクションが灰色表示になるのに対して、ソースフィールド ​セクションはアクティブになり、ユーザーが操作できます。必須キー ​および​ 重複排除キー ​オプションがアクティブになり、ユーザーは変更できません。

UI アクティベーションフローでの必須のマッピングの画像。

外部オーディエンスのサポートの設定 external-audiences

外部で生成されたオーディエンスのアクティベーションをサポートするように宛先を設定するには、schemaConfig の節で以下のスニペットを含めます。

"schemaConfig": {
  "segmentNamespaceDenyList": [],
  ...
}

segmentNamespaceDenyList の機能について詳しくは、このページの前述の table のプロパティの説明を参照してください。

次の手順 next-steps

この記事を読むことで、Destination SDK でサポートされるスキーマタイプと、どのようにスキーマを設定できるかについて、理解を深めることができました。

その他の宛先コンポーネントについて詳しくは、以下の記事を参照してください。

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6