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 呼び出し例の読み方に関する節を参照してください。

必須ヘッダーの値の収集

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

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

Schema Registry へのすべての参照（GET）リクエストには、追加の Accept ヘッダーが必要です。このヘッダーの値によって、API から返される情報の形式が決まります。 詳しくは、この後の Accept ヘッダーの節を参照してください。

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

Tenant_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 呼び出しを実行できるコンテナには、global コンテナと tenant コンテナの 2 つがあります。

グローバルコンテナ

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

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 ヘッダーと、ダウンストリーム Platform サービス API ペイロードの schemaRef.contentType プロパティで参照されます。

現在、Platform では、各スキーマに対して 1 つのメジャーバージョン（1）のみをサポートしています。 スキーマ進化のルールに従い、スキーマの各更新は非破壊的である必要があります。つまり、スキーマの新しいマイナーバージョン（1.2、1.3 など）です は常に、以前のマイナーバージョンとの下位互換性があります。 したがって、version=1 を指定すると、スキーマレジストリは常にスキーマの 最新 メジャーバージョン 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 つを選択します。