この Schema Registry API を使用すると、様々な Experience Data Model(XDM) リソースを作成および管理できます。 このドキュメントでは、Schema Registry API を呼び出す前に知っておく必要があるコア概念の概要を説明します。
開発者ガイドを使用するには、Adobe Experience Platformの次のコンポーネントに関する十分な知識が必要です。
XDM では、JSON スキーマの形式を使用して、取り込んだ顧客体験データの構造を記述し、検証します。 したがって、 公式の JSON スキーマドキュメント この基盤となる技術をより深く理解するために
Schema Registry API ドキュメントには、API 呼び出しの例とリクエストの形式を指定する方法が示されています。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、Experience Platform トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してください。
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}
のすべてのリソース Experience Platform ( Schema Registryは、特定の仮想サンドボックスに分離されています。 Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
x-sandbox-name: {SANDBOX_NAME}
でのサンドボックスについて詳しくは、 Platformを参照し、 サンドボックスドキュメント.
に対するすべての検索 (GET) リクエスト Schema Registry 追加の Accept
ヘッダー。この値は、API から返される情報の形式を決定します。 詳しくは、この後の Accept ヘッダーの節を参照してください。
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。
Content-Type: application/json
API ガイド全体を通して、 TENANT_ID
. この ID は、作成したリソースの名前空間が適切に付けられ、組織内に含まれるようにするために使用されます。 ID が不明な場合は、次の GET リクエストを実行して ID にアクセスします。
API 形式
GET /stats
リクエスト
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/stats \
-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}'
応答
成功時の応答は、組織の Schema Registry. この中には TENANT_ID
の値である tenantId
属性が含まれています。
{
"imsOrg":"{ORG_ID}",
"tenantId":"{TENANT_ID}",
"counts": {
"schemas": 4,
"mixins": 3,
"datatypes": 1,
"classes": 2,
"unions": 0,
},
"recentlyCreatedResources": [
{
"title": "Sample Field Group",
"description": "New Sample Field Group.",
"meta:resourceType": "mixins",
"meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
"version": "1.1"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
"title": "Tenant Class",
"description": "Tenant Defined Class",
"meta:resourceType": "classes",
"meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
"version": "1.0"
}
],
"recentlyUpdatedResources": [
{
"title": "Sample Field Group",
"description": "New Sample Field Group.",
"meta:resourceType": "mixins",
"meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
"version": "1.1"
},
{
"title": "Data Schema",
"description": "Schema for Data Information",
"meta:resourceType": "schemas",
"meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
"meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
"meta:classTitle": "Sample Class",
"version": "1.1"
}
],
"classUsage": {
"https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
"title": "Tenant Data Schema",
"description": "Schema for tenant-specific data."
}
],
"https://ns.adobe.com/xdm/context/profile": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
"title": "Simple Profile",
"description": "A simple profile schema."
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
"title": "Program Schema",
"description": "Schema for program-related data."
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
"title": "Sample Schema",
"description": "A sample schema."
}
]
}
}
CONTAINER_ID
について への呼び出し Schema Registry API では CONTAINER_ID
. API 呼び出しを実行できるコンテナは 2 つあります。の global
コンテナと tenant
コンテナ。
この global
コンテナにはすべての標準Adobeと Experience Platform パートナーが提供したクラス、スキーマフィールドグループ、データタイプ、スキーマ。 リストリクエストと参照 (GET) リクエストは、 global
コンテナ。
を使用する呼び出しの例 global
コンテナは次のようになります。
GET /global/classes
ユニークな TENANT_ID
、 tenant
コンテナには、組織で定義されたすべてのクラス、フィールドグループ、データ型、スキーマ、および記述子が格納されます。 これらは各組織に固有のもので、他の組織では表示も管理もできません。 で作成したリソースに対して、すべての CRUD 操作 (GET、POST、PUT、PATCH、DELETE) を実行できます。 tenant
コンテナ。
を使用する呼び出しの例 tenant
コンテナは次のようになります。
POST /tenant/fieldgroups
クラス、フィールドグループ、スキーマ、データ型を tenant
コンテナの場合は、 Schema Registry そして割り当てられた $id
を含む URI TENANT_ID
. この $id
は、API 全体で特定のリソースを参照する際に使用されます。$id
値の例については、次の節で説明します。
XDM リソースは、 $id
属性を URI 形式で記述します。次に例を示します。
https://ns.adobe.com/xdm/context/profile
https://ns.adobe.com/{TENANT_ID}/schemas/7442343-abs2343-21232421
URI をより REST に適したものにするために、スキーマでは、meta:altId
と呼ばれるプロパティで、ドット表記でエンコードされた URI を使用できます。
_xdm.context.profile
_{TENANT_ID}.schemas.7442343-abs2343-21232421
への呼び出し Schema Registry API は、URL エンコードされた $id
URI または meta:altId
(ドット表記形式)。 API への REST 呼び出しを実行する際には、URL エンコードされた $id
URI を使用することをお勧めします。
https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile
https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F7442343-abs2343-21232421
リスト操作およびルックアップ (GET) 操作を Schema Registry API、 Accept
API から返されるデータの形式を決定するには、ヘッダーが必要です。 特定のリソースを検索する場合は、バージョン番号も Accept
ヘッダー。
次の表に、互換性のあるリストを示します Accept
ヘッダー値(バージョン番号を持つヘッダー値を含む)と、それらを使用したときに API が返す内容の説明。
Accept | 説明 |
---|---|
application/vnd.adobe.xed-id+json |
ID のリストのみを返します。これは、リソースを一覧表示する際に最も使用される値です。 |
application/vnd.adobe.xed+json |
元の $ref および allOf を含むフル JSON スキーマのリストを返します。これは、全リソースのリストを返す際に使用されます。 |
application/vnd.adobe.xed+json; version=1 |
$ref と allOf を含む未処理の XDM です。タイトルと説明があります。 |
application/vnd.adobe.xed-full+json; version=1 |
$ref 属性と解決された allOf 。タイトルと説明があります。 |
application/vnd.adobe.xed-notext+json; version=1 |
$ref と allOf を含む未処理の XDM です。タイトルや説明はありません。 |
application/vnd.adobe.xed-full-notext+json; version=1 |
$ref 属性と解決された allOf 。タイトルや説明はありません。 |
application/vnd.adobe.xed-full-desc+json; version=1 |
$ref 属性と解決された allOf 。記述子が含まれます。 |
application/vnd.adobe.xed-deprecatefield+json; version=1 |
$ref および allOf を解決、タイトルと説明を含む非推奨のフィールドは、 meta:status 属性 deprecated . |
Platform は現在、各スキーマ (1
) をクリックします。 したがって、 version
は常に 1
検索リクエストを実行して、スキーマの最新のマイナーバージョンを返す場合。 スキーマのバージョン管理について詳しくは、以下のサブセクションを参照してください。
スキーマのバージョンはで参照されています Accept
スキーマレジストリ API および schemaRef.contentType
ダウンストリーム Platform サービス API ペイロードのプロパティ。
現在、Platform は 1 つのメジャーバージョン (1
) を使用します。 以下に従って: スキーマ進化のルールに設定する場合、スキーマを更新するたびに非破壊的にする必要があります。つまり、スキーマの新しいマイナーバージョン (1.2
, 1.3
など ) は、常に以前のマイナーバージョンとの後方互換性を維持します。 したがって、 version=1
に値を指定しない場合、スキーマレジストリは常に latest メジャーバージョン 1
スキーマの。つまり、以前のマイナーバージョンは返されません。
スキーマの進化に対する非破壊的な要件は、スキーマがデータセットによって参照され、次のいずれかの場合に該当するときにのみ適用されます。
上記の条件の 1 つを満たすデータセットにスキーマが関連付けられていない場合は、スキーマに対して任意の変更を加えることができます。 ただし、どの場合でも version
コンポーネントは、まだ次の場所に残っています: 1
.
スキーマのフィールドは、その properties
オブジェクト内にリストされます。各フィールド自体はオブジェクトで、フィールドに格納できるデータを記述および制約する属性を含みます。に関するガイドを参照してください。 API でのカスタムフィールドの定義 最も一般的に使用されるデータ型のコードサンプルとオプションの制約を参照してください。
以下のサンプルフィールドは、適切に形式が設定された XDM フィールドを表しています。サンプルコードの下に、命名時の制約とベストプラクティスが示されています。これらのベストプラクティスは、同様の属性を含むその他のリソースを定義する際にも適用できます。
"fieldName": {
"title": "Field Name",
"type": "string",
"format": "date-time",
"examples": [
"2004-10-23T12:00:00-06:00"
],
"description": "Full sentence describing the field, using proper grammar and punctuation.",
}
fieldName
、field_name2
、Field-Name
、field-name_3
_fieldName
fieldName
title
が必要です。これは、単語の先頭のみ大文字で記述します。例:Field Name
type
が必要です。
format
が必要なことがあります。examples
を配列として追加できます。description
では、フィールドとフィールドデータについての関連情報を表します。スキーマにアクセスした人が誰でもフィールドの意図を理解できるように、明確な言葉で記述する必要があります。Schema Registry API を使用した呼び出しを開始するには、使用可能なエンドポイントガイドの 1 つを選択します。