記述子エンドポイント
スキーマは、データエンティティの静的表示を定義しますが、これらのスキーマ(データセットなど)に基づくデータが相互にどのように関連付けられるかに関する具体的な詳細は提供しません。Adobe Experience Platform では、記述子を使用して、これらの関係や、記述子に関するその他の解釈的なメタスキーマを記述できます。
スキーマ記述子はテナントレベルのメタデータです。つまり、スキーマ記述子は組織に固有で、すべての記述子操作はテナントコンテナで実行されます。
各スキーマには、1 つ以上のスキーマ記述子エンティティを適用できます。各スキーマ記述子エンティティは、記述子 @type
と、それが適用される sourceSchema
を含みます。適用されると、これらの記述子はスキーマを使用して作成されたすべてのデータセットに適用されます。
The /descriptors
エンドポイント Schema Registry API を使用すると、エクスペリエンスアプリケーション内の記述子をプログラムで管理できます。
はじめに
このガイドで使用されるエンドポイントは、 Schema Registry API. 先に進む前に、はじめる前にを参照し、関連ドキュメントへのリンク、このドキュメントのサンプル API 呼び出しを読み取るためのガイドおよび任意の Experience Platform API を正常に呼び出すために必要なヘッダーに関する重要な情報を確認してください。
記述子のリストの取得 list
に対して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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xdm-link+json'
応答の形式は、 Accept
ヘッダーがリクエストで送信されました。 次の点に注意してください。 /descriptors
エンドポイントの使用 Accept
他のすべてのエンドポイントとは異なるヘッダー Schema Registry API.
Accept
置き換えるヘッダー xed
次を使用 xdm
、および link
記述子に固有のオプション。 適切な Accept
以下の呼び出し例にヘッダーが含まれていますが、記述子を操作する際に正しいヘッダーが使用されていることを確認するには、十分に注意が必要です。Accept
ヘッダーapplication/vnd.adobe.xdm-id+json
application/vnd.adobe.xdm-link+json
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"
]
}
記述子の検索 lookup
特定の記述子の詳細を表示したい場合は、個々の記述子をその @id
を使って検索(GET)できます。
API 形式
GET /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
検索する記述子の名前を指定します。リクエスト
次のリクエストは、記述子をその @id
の値です。 記述子はバージョン管理されないので、 Accept
参照リクエストにはヘッダーが必要です。
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: {ORG_ID}' \
-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": "{ORG_ID}",
"createdClient": "{CREATED_CLIENT}",
"updatedUser": "{UPDATED_USER}",
"created": 1548899346989,
"updated": 1548899346989,
"meta:containerId": "tenant",
"@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}
記述子の作成 create
新しい記述子を作成するには、 /tenant/descriptors
endpoint.
API 形式
POST /tenant/descriptors
リクエスト
次のリクエストでは、スキーマ例の「email address」フィールドに ID 記述子を定義します。これは、 Experience Platform 電子メールアドレスを識別子として使用し、個人に関する情報を組み合わせるのに役立てます。
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: {ORG_ID}' \
-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
は読み取り専用フィールドで、 Schema Registry 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
を返します。PUTリクエストのパス。
API 形式
PUT /tenant/descriptors/{DESCRIPTOR_ID}
{DESCRIPTOR_ID}
@id
。リクエスト
このリクエストは基本的に記述子を書き換えるので、リクエスト本文には、その型の記述子を定義するために必要なすべてのフィールドが含まれている必要があります。 つまり、記述子を更新 (PUT) するリクエストペイロードは、 記述子の作成 (POST) 同じタイプの。
次の例では、別の 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: {ORG_ID}' \
-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"
}
の実行 参照 (GET) リクエスト を表示すると、記述子には、PUTリクエストで送信された変更を反映するようにフィールドが更新されたことが示されます。
記述子の削除 delete
定義した記述子を Schema Registry. これは、 @id
削除する記述子の。
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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
リクエストが成功した場合は、HTTP ステータス 204(コンテンツなし)が空白の本文とともに返されます。
記述子が削除されたことを確認するには、 ルックアップリクエスト 記述子に対して @id
. 記述子が Schema Registry.
付録
次の節では、 Schema Registry API.
記述子の定義 defining-descriptors
以下の節では、使用可能な記述子の型の概要を示します。各型の記述子を定義するための必須フィールドも含まれます。
ID 記述子
ID 記述子は、sourceProperty"sourceSchema"は Identity 次に示すフィールド: 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:descriptorIdentity
.xdm:sourceSchema
$id
URI。xdm:sourceVersion
xdm:sourceProperty
xdm:namespace
xdm:property
xdm:id
または xdm:code
(使用されている xdm:namespace
に応じる)。xdm:isPrimary
わかりやすい名前記述子 friendly-name
わかりやすい名前記述子を使用すると、ユーザーは title
, description
、および meta:enum
コアライブラリスキーマフィールドの値。 特に、「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"
},
"xdm:excludeMetaEnum": {
"web.formFilledOut": "Web Form Filled Out",
"media.ping": "Media ping"
}
}
@type
xdm:alternateDisplayInfo
.xdm:sourceSchema
$id
URI。xdm:sourceVersion
xdm:sourceProperty
/
) で終わらず、1 で終わる。 次を含めない properties
パス内 ( 例: /personalEmail/address
の代わりに /properties/personalEmail/properties/address
) をクリックします。xdm:title
xdm:description
meta:enum
xdm:sourceProperty
は文字列フィールドです。 meta:enum
を使用して、セグメント化 UI の「 」フィールドに推奨値を追加できます。 注意すべき点は meta:enum
は列挙を宣言しないか、XDM フィールドのデータ検証を提供しません。これは、Adobeで定義されたコア XDM フィールドにのみ使用する必要があります。 ソースプロパティが組織で定義されたカスタムフィールドの場合、代わりに、フィールドの
meta:enum
プロパティを直接、PATCHリクエストを介してフィールドの親リソースに渡します。meta:excludeMetaEnum
xdm:sourceProperty
は、 meta:enum
フィールドに値を入力する場合、このオブジェクトをわかりやすい名前記述子に含めて、これらの値の一部またはすべてをセグメント化から除外できます。 各エントリのキーと値は、元のエントリに含まれるキーと値と一致する必要があります meta:enum
」フィールドの値を指定します。関係記述子
関係記述子は、sourceProperty
と destinationProperty
で説明されているプロパティに基づいて、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:descriptorOneToOne
.xdm:sourceSchema
$id
URI。xdm:sourceVersion
xdm:sourceProperty
xdm:destinationSchema
$id
この記述子が関係を定義する参照スキーマの URI。xdm:destinationVersion
xdm:destinationProperty
参照 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:descriptorReferenceIdentity
.xdm:sourceSchema
$id
URI。xdm:sourceVersion
xdm:sourceProperty
/personalEmail/address
の代わりに /properties/personalEmail/properties/address
) をクリックします。xdm:identityNamespace
廃止されたフィールド記述子
以下が可能です。 カスタム XDM リソース内のフィールドを廃止する を追加して meta:status
属性を deprecated
問題のフィールドに ただし、スキーマ内の標準 XDM リソースで提供されるフィールドを非推奨にする場合は、非推奨のフィールド記述子を対象のスキーマに割り当てても、同じ効果を得ることができます。 の使用 正しい Accept
ヘッダーの場合は、API でスキーマを検索する際に、非推奨となった標準フィールドを表示できます。
{
"@type": "xdm:descriptorDeprecated",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
"xdm:sourceVersion": 1,
"xdm:sourceProperty": "/faxPhone"
}
@type
xdm:descriptorDeprecated
に設定する必要があります。xdm:sourceSchema
$id
。xdm:sourceVersion
1
に設定してください。xdm:sourceProperty
["/firstName", "/lastName"]
)で指定します。