記述子エンドポイント

スキーマは、データエンティティの静的表示を定義しますが、これらのスキーマ(データセットなど)に基づくデータが相互にどのように関連付けられるかに関する具体的な詳細は提供しません。Adobe Experience Platform では、記述子を使用して、これらの関係や、記述子に関するその他の解釈的なメタスキーマを記述できます。

スキーマ記述子はテナントレベルのメタデータです。つまり、スキーマ記述子は IMS 組織に固有で、すべての記述子操作はテナントコンテナで行われます。

各スキーマには、1 つ以上のスキーマ記述子エンティティを適用できます。各スキーマ記述子エンティティは、記述子 @type と、それが適用される sourceSchema を含みます。適用されると、これらの記述子はスキーマを使用して作成されたすべてのデータセットに適用されます。

APIの /descriptorsSchema Registry エンドポイントを使用すると、エクスペリエンスアプリケーション内の記述子をプログラムで管理できます。

はじめに

このガイドで使用されるエンドポイントは、 Schema Registry APIの一部です。 先に進む前に、 はじめに 、関連ドキュメントへのリンク、このドキュメントのサンプルAPI呼び出しを読むためのガイド、Experience PlatformAPIの呼び出しを正常に行うために必要なヘッダーに関する重要な情報を確認してください。

Retrieve a list of descriptors

組織が定義したすべての記述子をリストするには、にGETリクエストを行い /tenant/descriptorsます。

API 形式

GET /tenant/descriptors

リクエスト

curl -X GET \
  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 'Accept: application/vnd.adobe.xdm-link+json'

The response format depends on the Accept header sent in the request. Notice that the /descriptors endpoint uses Accept headers that are different than all other endpoints in the Schema Registry API.

重要

記述子には、一意のヘッダが必要です。こ Accept のヘッダは、に置き換えら xedxdm、記述子に固有の link オプションもオファーします。 The proper Accept headers have been included in the examples calls below, but take extra caution to ensure the correct headers are being used when working with descriptors.

Accept ヘッダー 説明
application/vnd.adobe.xdm-id+json 記述子 ID の配列を返します。
application/vnd.adobe.xdm-link+json 記述子 API パスの配列を返します。
application/vnd.adobe.xdm+json 拡張された記述子オブジェクトの配列を返します。
application/vnd.adobe.xdm-v2+json この Accept ヘッダは、ページング機能を利用するために使用する必要があります。

応答

応答には、定義された記述子を持つ各記述子タイプの配列が含まれます。つまり、ある種の @type 記述子が定義されていない場合、その記述子型の空の配列は返されません。

link Accept ヘッダーを使用する場合、各記述子は 形式を持つ配列項目として示されます。/{CONTAINER}/descriptors/{DESCRIPTOR_ID}

{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

記述子の検索

特定の記述子の詳細を表示したい場合は、個々の記述子をその @id を使って検索(GET)できます。

API 形式

GET /tenant/descriptors/{DESCRIPTOR_ID}
パラメーター 説明
{DESCRIPTOR_ID} The @id of the descriptor you want to look up.

リクエスト

次のリクエストは、その @id 値で記述子を取得します。 Descriptors are not versioned, therefore no Accept header is required in the lookup request.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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}'

応答

正常な応答は、記述子の詳細(@type および sourceSchema を含む)と、記述子の種類に応じて変化する追加情報を返します。返される @id は、リクエストで指定された記述子 @id と一致する必要があります。

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{IMS_ORG}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Create a descriptor

You can create a new descriptor by making a POST request to the /tenant/descriptors endpoint.

重要

The Schema Registry allows you to define several different descriptor types. 各記述子の型は、要求の本文に固有のフィールドを送信する必要があります。 記述子の完全なリストとそれらを定義するのに必要なフィールドについては、 付録 を参照してください。

API 形式

POST /tenant/descriptors

リクエスト

次のリクエストでは、スキーマ例の「email address」フィールドに ID 記述子を定義します。This tells Experience Platform to use the email address as an identifier to help stitch together information about the individual.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

応答

正常な応答は、新しく作成された記述子の詳細(@id を含む)と共に HTTP ステータス 201(作成済み)を返します。The @id is a read-only field assigned by the Schema Registry and used for referencing the descriptor in the API.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

記述子の更新

PUTリクエストのパスに記述子を含めること @id で、記述子を更新できます。

API 形式

PUT /tenant/descriptors/{DESCRIPTOR_ID}
パラメーター 説明
{DESCRIPTOR_ID} 更新する記述子の @id

リクエスト

このリクエストは基本的に記述子を書き換えるので、リクエスト本体には、その型の記述子を定義するために必要なすべてのフィールドが含まれている必要があります。In other words, the request payload to update (PUT) a descriptor is the same as the payload to create (POST) a descriptor of the same type.

重要

POST要求を使用する記述子を作成する場合と同様に、各記述子の型は、PUT要求ペイロードに独自の固有のフィールドを送信する必要があります。 記述子の完全なリストとそれらを定義するのに必要なフィールドについては、 付録 を参照してください。

次の例では、ID記述子を更新して、別の xdm:sourceProperty (mobile phone)を参照し、に変更 xdm:namespace しま Phoneす。

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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 '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

応答

正常な応答は、更新された記述子の @id(リクエストで送信された @id と一致する必要がある)と共に、HTTP ステータス 201(作成済み)を返します。

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Performing a lookup (GET) request to view the descriptor will show that the fields have now been updated to reflect the changes sent in the PUT request.

記述子の削除

Occasionally you may need to remove a descriptor that you have defined from the Schema Registry. これは、削除する記述子の @id を参照する DELETE リクエストを作成することで行われます。

API 形式

DELETE /tenant/descriptors/{DESCRIPTOR_ID}
パラメーター 説明
{DESCRIPTOR_ID} 削除する記述子の @id

リクエスト

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -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}'

応答

正常な応答は、空白の本文とともに HTTP ステータス 204(コンテンツなし)を返します。

To confirm the descriptor has been deleted, you can perform a lookup request against the descriptor @id. The response returns HTTP status 404 (Not Found) because the descriptor has been removed from the Schema Registry.

付録

The following section provides additional information regarding working with descriptors in the Schema Registry API.

記述子の定義

以下の節では、使用可能な記述子の型の概要を示します。各型の記述子を定義するための必須フィールドも含まれます。

ID 記述子

An identity descriptor signals that the "sourceProperty" of the "sourceSchema" is an Identity field as described by Adobe Experience Platform Identity Service.

{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}
プロパティ 説明
@type 定義する記述子のタイプ。
xdm:sourceSchema 記述子を定義するスキーマの $id URI。
xdm:sourceVersion ソーススキーマのメジャーバージョン。
xdm:sourceProperty ID となる特定のプロパティへのパス。パスは、「/」で始まる必要がありますが、「/」で終わらない必要があります。パスに「プロパティ」を含めてはいけません(例:「/properties/personalEmail/properties/address」の代わりに「/personalEmail/address」を使用)。
xdm:namespace ID 名前空間の id または code。A list of namespaces can be found using the Identity Service API.
xdm:property xdm:id または xdm:code(使用されている xdm:namespace に応じる)。
xdm:isPrimary オプションのブール値。true の場合、フィールドがプライマリ ID であることを示します。スキーマには、1 つのプライマリ ID のみを含めることができます。

わかりやすい名前記述子

Friendly name descriptors allow a user to modify the title, description, and meta:enum values of the core library schema fields. 特に、「eVar」および組織に固有の情報を含むとしてラベル付けする他の「汎用」フィールドを扱う場合に役立ちます。UI は、これらを使用して、わかりやすい名前を表示したり、わかりやすい名前を持つフィールドのみを表示したりできます。

{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  }
}
プロパティ 説明
@type 定義する記述子のタイプ。
xdm:sourceSchema 記述子を定義するスキーマの $id URI。
xdm:sourceVersion ソーススキーマのメジャーバージョン。
xdm:sourceProperty ID となる特定のプロパティへのパス。パスは、「/」で始まる必要がありますが、「/」で終わらない必要があります。パスに「プロパティ」を含めてはいけません(例:「/properties/personalEmail/properties/address」の代わりに「/personalEmail/address」を使用)。
xdm:title このフィールドに表示する新しいタイトル(タイトルケースで記述)。
xdm:description オプションで、タイトルに説明を追加できます。
meta:enum に示すフィールド xdm:sourceProperty が文字列フィールドの場合、 meta:enum UI内のフィールドに推奨される値のリストを Experience Platform 決定します。 定義済みリストを宣言しないこと、またはXDMフィールドに対してデータの検証を行わないことに注意して meta:enum ください。

これは、Adobeが定義するコアXDMフィールドに対してのみ使用する必要があります。 ソースプロパティが、組織で定義されたカスタムフィールドの場合は、フィールドの親リソースに対するPATCH要求を介して、フィールドの meta:enum プロパティを直接編集する必要があります。

関係記述子

関係記述子は、sourcePropertydestinationProperty で説明されているプロパティに基づいて、2 つの異なるスキーマ間の関係を記述します。詳しくは、2 つのスキーマ間の関係の定義に関するチュートリアルを参照してください。

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": 
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}
プロパティ 説明
@type 定義する記述子のタイプ。
xdm:sourceSchema 記述子を定義するスキーマの $id URI。
xdm:sourceVersion ソーススキーマのメジャーバージョン。
xdm:sourceProperty 関係を定義するソーススキーマ内のフィールドのパス。「/」で始まる必要がありますが、「/」で終わらない必要があります。パスに「プロパティ」を含めてはいけません(例:「/properties/personalEmail/properties/address」の代わりに「/personalEmail/address」を使用)。。
xdm:destinationSchema この記述子が関係を定義する宛先スキーマの $id URI。
xdm:destinationVersion 宛先スキーマのメジャーバージョン。
xdm:destinationProperty 宛先スキーマ内のターゲットフィールドへの最適パス。このプロパティを省略すると、ターゲットフィールドは、対応する参照 ID 記述子(以下を参照)を含むフィールドによって推論されます。

参照 ID 記述子

参照ID記述子は、スキーマフィールドの主要なIDへの参照コンテキストを提供し、他のスキーマのフィールドから参照できるようにします。 参照記述子を適用する前に、フィールドに ID 記述子のラベルを付けておく必要があります。

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}
プロパティ 説明
@type 定義する記述子のタイプ。
xdm:sourceSchema 記述子を定義するスキーマの $id URI。
xdm:sourceVersion ソーススキーマのメジャーバージョン。
xdm:sourceProperty 記述子を定義するソーススキーマ内のフィールドのパス。「/」で始まる必要がありますが、「/」で終わらない必要があります。パスに「プロパティ」を含めてはいけません(例:「/properties/personalEmail/properties/address」の代わりに「/personalEmail/address」を使用)。。
xdm:identityNamespace ソースプロパティの ID 名前空間コード。

このページ