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 に関する十分な知識が必要です。 このチュートリアルを始める前に、次のドキュメントを確認してください。

  • XDM システムのExperience Platform:XDM と、での実装の概要で Experience Platformす。
  • Real-time Customer Profile:複数のソースからの集計データに基づいて、統合されたリアルタイムの顧客プロファイルを提供します。
  • サンドボックス:Experience Platform は、単一の 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 フィールドへの参照として機能します。 ソーススキーマにこの目的のフィールドがない場合は、新しいフィールドを含むスキーマフィールドグループを作成し、スキーマに追加する必要があります。 この新しいフィールドの値は"string"である必要があります。type

重要

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

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

メモ

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

新しいフィールドグループの作成

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

API 形式

POST /tenant/fieldgroups

リクエスト

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

curl -X POST\
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/fieldgroups \
  -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 field group 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"
            }
        ]
      }'

応答

正常な応答は、新しく作成されたフィールドグループの詳細を返します。

{
    "$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 field group 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 読み取り専用の、新しいフィールドグループの一意の識別子です。 URI の形式を取ります。

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

フィールドグループをソーススキーマに追加する

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

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 追加するフィールドグループの $id

応答

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

{
    "$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 でスキーマの関係を定義する手順については、スキーマエディタを使用したスキーマの関係の定義に関するチュートリアルを参照してください。

このページ