Schema Registry APIを使用して2つのスキーマ間の関係を定義する

様々なチャネルでの顧客とブランドとの関係を理解する能力は、Adobe Experience Platform の重要な部分です。Experience Data Model (XDM)スキーマの構造内でこれらの関係を定義すると、顧客データに対する複雑な洞察を得ることができます。

スキーマの関係は、和集合スキーマとReal-time Customer Profileを使用して推定できますが、これは同じクラスを共有するスキーマにのみ当てはまります。 異なるクラスに属する2つのスキーマ間の関係を確立するには、目的のスキーマのIDを参照するソーススキーマに、専用の関係フィールドを追加する必要があります。

このドキュメントでは、Schema Registry APIを使用して、組織で定義されている2つのスキーマ間の1対1の関係を定義するためのチュートリアルを提供します。

はじめに

このチュートリアルでは、Experience Data Model (XDM)とXDM Systemについての十分な理解が必要です。 このチュートリアルを始める前に、次のドキュメントを確認してください。

  • Experience PlatformのXDMシステム:XDMとその実装の概要を、で説明し Experience Platformます。
  • Real-time Customer Profile:複数のソースからの集計データに基づいて、統合されたリアルタイムの消費者プロファイルを提供します。
  • サンドボックス: Experience Platform は、1つの Platform インスタンスを個別の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスを提供します。

このチュートリアルを開始する前に、開発者ガイドを参照し、Schema Registry APIを正しく呼び出すために知っておく必要がある重要な情報を確認してください。 これには、{TENANT_ID}、「コンテナ」の概念、リクエストをおこなうために必要なヘッダー( ヘッダーとその可能な値に特に注意)が含まれます。Accept

ソースと宛先スキーマの定義

この関係で定義される 2 つのスキーマが既に作成されていると想定されます。このチュートリアルでは、組織の現在の忠誠度プログラム(「Loyalty Members」スキーマで定義)のメンバーと、お気に入りのホテル(「Hotels」スキーマで定義)との間に関係を作成します。

スキーマ関係は、宛先スキーマ​内の別のフィールドを参照するフィールドを有する​ソーススキーマ​で表されます。次の手順では、"Loyalty Members"がソーススキーマ、"Hotels"がターゲットスキーマとして機能します。

重要

関係を確立するには、両方のスキーマがプライマリIDを定義し、Real-time Customer Profileに対して有効にしている必要があります。 スキーマの設定方法に関するガイダンスが必要な場合は、スキーマの作成チュートリアルのプロファイルでのスキーマの使用を有効にする方法の節を参照してください。

2 つのスキーマ間の関係を定義するには、まず両方のスキーマの $id 値を取得する必要があります。スキーマの表示名(title)がわかっている場合は、Schema Registry APIの/tenant/schemasエンドポイントにGETリクエストを行うことで、$idの値を見つけることができます。

API 形式

GET /tenant/schemas

リクエスト

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'
メモ

Acceptヘッダーapplication/vnd.adobe.xed-id+jsonは、結果のスキーマのタイトル、ID、バージョンのみを返します。

応答

正常な応答は、組織が定義したスキーマのリスト(組織の name$idmeta:altIdversion を含む)を返します。

{
    "results": [
        {
            "title": "Newsletter Subscriptions",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/192a66930afad02408429174c311ae73",
            "meta:altId": "_{TENANT_ID}.schemas.192a66930afad02408429174c311ae73",
            "version": "1.2"
        },
        {
            "title": "Loyalty Members",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
            "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
            "version": "1.5"
        },
        {
            "title": "Hotels",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
            "meta:altId": "_{TENANT_ID}.schemas.d4ad4b8463a67f6755f2aabbeb9e02c7",
            "version": "1.0"
        }
    ],
    "_page": {
        "orderby": "updated",
        "next": null,
        "count": 3
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform-stage.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

関係を定義する 2 つのスキーマの $id 値を記録します。これらの値は、後の手順で使用します。

ソーススキーマの参照フィールドの定義

Schema Registry内では、リレーショナル・データベース・テーブルの外部キーと同様に関係記述子が機能します。ソーススキーマ内のフィールドは、宛先スキーマのプライマリIDフィールドへの参照として機能します。 ソーススキーマにこの目的のフィールドがない場合は、新しいフィールドを使用してミックスインを作成し、スキーマに追加する必要があります。 この新しいフィールドには、type値"string"が必要です。

重要

宛先スキーマとは異なり、ソーススキーマは、その主IDを参照フィールドとして使用できません。

このチュートリアルでは、宛先スキーマ「Hotels」には、スキーマのプライマリIDとして機能するhotelIdフィールドが含まれているので、参照フィールドとしても機能します。 ただし、ソーススキーマ"Loyalty Members"には参照として使用する専用のフィールドがないため、スキーマに新しいフィールドを追加する新しいミックスインを与える必要があります。favoriteHotel.

メモ

ソーススキーマに、参照フィールドとして使用する専用のフィールドが既に存在する場合は、参照記述子の作成の手順に進むことができます。

新しい mixin の作成

スキーマに新しいフィールドを追加するには、まず mixin で定義する必要があります。/tenant/mixins エンドポイントに対して POST リクエストを作成することで、新しい mixin を作成できます。

API 形式

POST /tenant/mixins

リクエスト

次のリクエストでは、新しい mixin を作成し、追加先の任意のスキーマの _{TENANT_ID} 名前空間の下に favoriteHotel フィールドを追加します。

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/mixins \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '{
        "type": "object",
        "title": "Favorite Hotel",
        "meta:intendedToExtend": ["https://ns.adobe.com/xdm/context/profile"],
        "description": "Favorite hotel mixin for the Loyalty Members schema.",
        "definitions": {
            "favoriteHotel": {
              "properties": {
                "_{TENANT_ID}": {
                  "type":"object",
                  "properties": {
                    "favoriteHotel": {
                      "title": "Favorite Hotel",
                      "type": "string",
                      "description": "Favorite hotel for a Loyalty Member."
                    }
                  }
                }
              }
            }
        },
        "allOf": [
            {
              "$ref": "#/definitions/favoriteHotel"
            }
        ]
      }'

応答

正常な応答は、新しく作成された mixin の詳細を返します。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220",
    "meta:altId": "_{TENANT_ID}.mixins.3387945212ad76ee59b6d2b964afb220",
    "meta:resourceType": "mixins",
    "version": "1.0",
    "type": "object",
    "title": "Favorite Hotel",
    "meta:intendedToExtend": [
        "https://ns.adobe.com/xdm/context/profile"
    ],
    "description": "Favorite hotel mixin for the Loyalty Members schema.",
    "definitions": {
        "favoriteHotel": {
            "properties": {
                "_{TENANT_ID}": {
                    "type": "object",
                    "properties": {
                        "favoriteHotel": {
                            "title": "Favorite Hotel",
                            "type": "string",
                            "description": "Favorite hotel for a Loyalty Member.",
                            "meta:xdmType": "string"
                        }
                    },
                    "meta:xdmType": "object"
                }
            },
            "type": "object",
            "meta:xdmType": "object"
        }
    },
    "allOf": [
        {
            "$ref": "#/definitions/favoriteHotel"
        }
    ],
    "meta:xdmType": "object",
    "meta:abstract": true,
    "meta:extensible": true,
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}",
    "meta:registryMetadata": {
        "eTag": "quM2aMPyb2NkkEiZHNCs/MG34E4=",
        "palm:sandboxName": "prod"
    }
}
プロパティ 説明
$id 新しい mixin の一意の ID(システムで生成され、読み取り専用)。URI の形式を取ります。

次の手順で mixin をソーススキーマに追加する際に使用する、mixin の $id URI を記録します。

ソーススキーマへの mixin の追加

Mixin を作成したら、/tenant/schemas/{SCHEMA_ID} エンドポイントに対して PATCH リクエストを作成して、その mixin をソーススキーマに追加できます。

API 形式

PATCH /tenant/schemas/{SCHEMA_ID}
パラメーター 説明
{SCHEMA_ID} URL エンコードされた $id URI またはソーススキーマの meta:altId

リクエスト

次のリクエストは、"Favorite Hotel"ミックスインを"Loyalty Members"スキーマに追加します。

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.533ca5da28087c44344810891b0f03d9 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
    { 
      "op": "add", 
      "path": "/allOf/-", 
      "value":  {
        "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
      }
    }
  ]'
プロパティ 説明
op 実行する PATCH 操作。このリクエストでは、add 操作が使用されます。
path 新しいリソースを追加するスキーマフィールドへのパス。スキーマにミックスインを追加する場合、値は「/allOf/ — 」にする必要があります。
value.$ref 追加する mixin の $id

応答

正常な応答は、更新されたスキーマの詳細を返します。これには、追加された mixin の $ref 値が allOf 配列に含まれます。

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "meta:altId": "_{TENANT_ID}.schemas.2c66c3a4323128d3701289df4468e8a6",
    "meta:resourceType": "schemas",
    "version": "1.1",
    "type": "object",
    "title": "Loyalty Members",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/3387945212ad76ee59b6d2b964afb220"
        }
    ],
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:tenantNamespace": "_{TENANT_ID}",
    "imsOrg": "{IMS_ORG}",
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/ec16dfa484358f80478b75cde8c430d3",
        "https://ns.adobe.com/{TENANT_ID}/mixins/61969bc646b66a6230a7e8840f4a4d33"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557525483804,
        "repo:lastModifiedDate": 1566419670915,
        "xdm:createdClientId": "{API_KEY}",
        "xdm:lastModifiedClientId": "{CLIENT_ID}",
        "eTag": "ITNzu8BVTO5pw9wfCtTTpk6U4WY="
    }
}

参照 ID 記述子の作成

スキーマフィールドは、関係内の他の要素からの参照として使用される場合、参照 ID 記述子を適用する必要があります。"Loyalty Members"のfavoriteHotelフィールドは"Hotels"のhotelIdフィールドを参照するので、hotelIdに参照ID記述子を指定する必要があります。

/tenant/descriptors エンドポイントに対して POST リクエストをおこなって、宛先スキーマの参照記述子を作成します。

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストは、宛先スキーマー"Hotels"にhotelIdフィールドの参照記述子を作成します。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID"
  }'
パラメーター 説明
@type 定義する記述子のタイプ。参照記述子の場合、値は"xdm:descriptorReferenceIdentity"でなければなりません。
xdm:sourceSchema 宛先スキーマの $id URL。
xdm:sourceVersion 宛先スキーマのバージョン番号。
sourceProperty 宛先スキーマのプライマリ ID フィールドへのパス。
xdm:identityNamespace 参照フィールドの ID 名前空間。この名前空間は、フィールドをスキーマのプライマリIDとして定義する場合と同じにする必要があります。 詳しくは、「ID 名前空間の概要」を参照してください。

応答

正常な応答は、宛先スキーマの新しく作成された参照記述子の詳細を返します。

{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/hotelId",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

関係記述子の作成

関係記述子は、ソース記述子と宛先スキーマとの間に 1 対 1 の関係を確立します。宛先スキーマの参照記述子を定義すると、/tenant/descriptorsエンドポイントにPOSTリクエストを作成して、新しい関係記述子を作成できます。

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストは、新しい関係記述子を作成します。この際、ソーススキーマとして「Loyalty Members」を、宛先スキーマとして「Legacy Loyalty Members」を指定します。

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId"
  }'
パラメーター 説明
@type 作成する記述子のタイプ。関係記述子の@type値は"xdm:descriptorOneToOne"です。
xdm:sourceSchema ソーススキーマの $id URL。
xdm:sourceVersion ソーススキーマのバージョン番号。
xdm:sourceProperty ソーススキーマの参照フィールドへのパス。
xdm:destinationSchema 宛先スキーマの $id URL。
xdm:destinationVersion 宛先スキーマのバージョン番号。
xdm:destinationProperty コピー先スキーマの参照フィールドへのパス。

応答

正常な応答は、宛先スキーマの新しく作成された関係記述子の詳細を返します。

{
    "@type": "xdm:descriptorOneToOne",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/2c66c3a4323128d3701289df4468e8a6",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/d4ad4b8463a67f6755f2aabbeb9e02c7",
    "xdm:destinationVersion": 1,
    "xdm:destinationProperty": "/_{TENANT_ID}/hotelId",
    "meta:containerId": "tenant",
    "@id": "76f6cc7105f4eaab7eb4a5e1cb4804cadc741669"
}

次の手順

このチュートリアルでは、2 つのスキーマ間に 1 対 1 の関係を作成しました。Schema Registry APIを使用した記述子の操作について詳しくは、スキーマレジストリ開発者ガイドを参照してください。 UI でスキーマの関係を定義する手順については、スキーマエディタを使用したスキーマの関係の定義に関するチュートリアルを参照してください。

このページ