Schema Registry API の概要

Schema Registry APIを使用すると、様々なExperience Data Model （XDM） リソースを作成および管理できます。 このドキュメントでは、Schema Registry API を呼び出す前に知っておく必要があるコア概念の概要を説明します。

前提条件

このガイドを使用するには、Adobe Experience Platformの次のコンポーネントについて理解している必要があります。

XDMでは、JSON スキーマ形式を使用して、取り込まれた顧客体験データの構造を記述および検証します。 したがって、この基礎となるテクノロジーをより深く理解するために、公式JSON スキーマドキュメント ​を確認することを強くお勧めします。

API 呼び出し例の読み取り

Schema Registry API ドキュメントには、API 呼び出しの例とリクエストの形式を指定する方法が示されています。 これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。 また、API レスポンスで返されるサンプル JSON も示されています。 ドキュメントで使用される API 呼び出し例の表記について詳しくは、Experience Platform トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してください。

必須ヘッダーの値の収集

Experience Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。 次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

Schema Registryに属するリソースを含むExperience Platformのすべてのリソースは、特定の仮想サンドボックスに分離されます。 Experience Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。

Schema Registryへのすべてのルックアップ （GET）要求には、値がAPIによって返される情報の形式を決定するAccept ヘッダーが追加で必要です。 詳しくは、この後の Accept ヘッダーの節を参照してください。

ペイロード（POST、PUT、PATCH）を含んだすべてのリクエストには、以下の追加ヘッダーが必要です。

テナント IDを知る know-your-tenant_id

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について container

Schema Registry APIを呼び出すには、CONTAINER_IDを使用する必要があります。 API呼び出しを行うことができる2つのコンテナがあります。global コンテナとtenant コンテナです。

グローバルコンテナ

global コンテナには、すべての標準AdobeとExperience Platformのパートナーが提供するクラス、スキーマフィールドグループ、データタイプ、スキーマが格納されます。 global コンテナに対して実行できるのは、リストおよびルックアップ （GET）要求のみです。

global コンテナを使用する呼び出しの例は、次のようになります。

GET /global/classes

テナントコンテナ

独自のTENANT_IDと混同しないでください。tenant コンテナには、組織によって定義されたすべてのクラス、フィールドグループ、データタイプ、スキーマ、および記述子が格納されます。 これらのテンプレートは組織ごとに異なるため、他の組織では表示されず、管理することができません。 tenant コンテナで作成したリソースに対して、すべてのCRUD操作（GET、POST、PUT、PATCH、DELETE）を実行できます。

tenant コンテナを使用する呼び出しの例は、次のようになります。

POST /tenant/fieldgroups

クラス、フィールドグループ、スキーマ、またはデータタイプをtenant コンテナで作成すると、そのクラスはSchema Registryに保存され、TENANT_IDを含む$id URIが割り当てられます。 この $id は、API 全体で特定のリソースを参照する際に使用されます。 $id 値の例については、次の節で説明します。

リソース特定 resource-identification

XDM リソースは、次の例のように、URIの形式で$id属性で識別されます。

URI をより REST に適したものにするために、スキーマでは、meta:altId と呼ばれるプロパティで、ドット表記でエンコードされた URI を使用できます。

Schema Registry APIへの呼び出しは、URL エンコードされた$id URIまたはmeta:altId （ドット表記形式）のいずれかをサポートします。 API への REST 呼び出しを実行する際には、URL エンコードされた $id URI を使用することをお勧めします。

Accept ヘッダー accept

Schema Registry APIでリストおよびルックアップ （GET）操作を実行する場合、APIによって返されるデータの形式を判断するには、Accept ヘッダーが必要です。 特定のリソースを検索する場合は、バージョン番号もAccept ヘッダーに含める必要があります。

次の表に、バージョン番号を含む互換性のあるAccept ヘッダー値と、使用時にAPIが返す内容の説明を示します。

スキーマのバージョン管理 versioning

スキーマバージョンは、Schema Registry APIのAccept個のヘッダーと、下流のExperience Platform サービス API ペイロードのschemaRef.contentType個のプロパティで参照されます。

現在、Experience Platformでは、各スキーマに対して1つのメジャーバージョン （1）のみがサポートされています。 スキーマ進化🔗の ルールによると、スキーマに対する各更新は非破壊的である必要があります。つまり、スキーマの新しいマイナーバージョン （1.2、1.3など）が必要です。 以前のマイナーなバージョンと常に下位互換性があります。 したがって、version=1を指定する場合、スキーマレジストリは常にスキーマの​latest メジャーバージョン 1を返します。つまり、以前のマイナーバージョンは返されません。

XDM フィールドの制約とベストプラクティス

スキーマのフィールドは、その 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.",
}

次の手順

Schema Registry API を使用した呼び出しを開始するには、使用可能なエンドポイントガイドの 1 つを選択します。