ドキュメント Experience Platform エクスペリエンスデータモデル（XDM）ガイド

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

Last update: Wed May 10 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

トピック：
Schemas

作成対象：

Developer

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

スキーマの関係は、結合スキーマと Real-Time Customer Profile を使用して推論できますが、同じクラスを共有するスキーマにのみ適用されます。異なるクラスに属する 2 つのスキーマ間の関係を確立するには、専用の関係フィールドを ソーススキーマ：別の 参照スキーマ.

NOTE

スキーマレジストリ API は、参照スキーマを「宛先スキーマ」と呼びます。これらは、の宛先スキーマと混同しないでください。データ準備マッピングセットまたはスキーマ宛先接続.

このドキュメントでは、 Schema Registry API.

はじめに

このチュートリアルでは、 Experience Data Model (XDM) と XDM System. このチュートリアルを始める前に、次のドキュメントを確認してください。

XDM システムのExperience Platform:XDM と、 Experience Platform.
- スキーマ構成の基本：XDM スキーマの構築ブロックの紹介。
Real-Time Customer Profile：複数のソースからの集計データに基づいて、統合されたリアルタイムの顧客プロファイルを提供します。
サンドボックス：Experience Platform は、単一の Platform インスタンスを別々の仮想環境に分割して、デジタルエクスペリエンスアプリケーションの開発と発展を支援する仮想サンドボックスを提供します。

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

ソースと参照スキーマの定義 define-schemas

この関係で定義される 2 つのスキーマが既に作成されていると想定されます。このチュートリアルでは、組織の現在のロイヤルティプログラム (「Loyalty Members「」スキーマ ) とそのお気に入りのホテル（「」で定義）Hotels"スキーマ ) です。

スキーマの関係は、 ソーススキーマ 内の別のフィールドを参照するフィールドを持つ 参照スキーマ. 次の手順で、「Loyalty Members」がソーススキーマになり、「Hotels「」は参照スキーマとして機能します。

IMPORTANT

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

2 つのスキーマ間の関係を定義するには、まず両方のスキーマの $id 値を取得する必要があります。表示名 (title) を使用して、スキーマの $id の値を指定するために、 /tenant/schemas エンドポイント Schema Registry API

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

NOTE

この Accept ヘッダー application/vnd.adobe.xed-id+json は、結果として生成されるスキーマのタイトル、ID およびバージョンのみを返します。

応答

正常な応答は、組織が定義したスキーマのリスト（組織の name、$id、meta:altId、version を含む）を返します。

{
    "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.

IMPORTANT

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

このチュートリアルでは、参照スキーマ「Hotels「」には次が含まれます hotelId スキーマのプライマリ id として機能するフィールド。ただし、ソーススキーマ「Loyalty Members」には、 hotelIdと呼ばれ、スキーマに新しいフィールドを追加するには、カスタムフィールドグループを作成する必要があります。 favoriteHotel.

NOTE

ソーススキーマに、参照フィールドとして使用する専用のフィールドが既に存在する場合は、参照記述子の作成.

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

スキーマに新しいフィールドを追加するには、まずフィールドグループで定義する必要があります。新しいフィールドグループを作成するには、 /tenant/fieldgroups endpoint.

API 形式

POST /tenant/fieldgroups

リクエスト

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

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: {ORG_ID}' \
  -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

システムが生成した、新しいフィールドグループの一意の ID です。 URI の形式を取ります。

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

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

フィールドグループを作成したら、 /tenant/schemas/{SCHEMA_ID} endpoint.

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: {ORG_ID}' \
  -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 追加するフィールドグループの

応答

正常な応答は、更新されたスキーマの詳細を返します。この詳細には、 $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": "{ORG_ID}",
    "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 記述子の作成 reference-identity

スキーマフィールドは、関係内の別のスキーマへの参照として使用される場合、参照 ID 記述子を適用する必要があります。以降 favoriteHotel フィールドの「Loyalty Members」が hotelId フィールドの「Hotels", favoriteHotel は、参照 ID 記述子を与える必要があります。

に対してPOSTリクエストを実行して、ソーススキーマの参照記述子を作成します。 /tenant/descriptors endpoint.

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストは、 favoriteHotel ソーススキーマのフィールド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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
    "@type": "xdm:descriptorReferenceIdentity",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "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/533ca5da28087c44344810891b0f03d9",
    "xdm:sourceVersion": 1,
    "xdm:sourceProperty": "/_{TENANT_ID}/favoriteHotel",
    "xdm:identityNamespace": "Hotel ID",
    "meta:containerId": "tenant",
    "@id": "53180e9f86eed731f6bf8bf42af4f59d81949ba6"
}

関係記述子の作成 create-descriptor

関係記述子は、ソーススキーマと参照スキーマの間に 1 対 1 の関係を確立します。ソーススキーマ内の適切なフィールドの参照 ID 記述子を定義したら、に対してPOSTリクエストを作成して、新しい関係記述子を作成できます。 /tenant/descriptors endpoint.

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストは、「Loyalty Members"をソーススキーマとして、"Hotels」を参照スキーマとして使用します。

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: {ORG_ID}' \
  -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

参照スキーマ内のプライマリ ID フィールドへのパス。

応答

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

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

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07