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 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。

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

に対するすべての検索 (GET) リクエスト Schema Registry 追加の 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 呼び出しを実行できるコンテナは 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 値の例については、次の節で説明します。

リソースの識別 resource-identification

XDM リソースは、 $id 属性を URI 形式で記述します。次に例を示します。

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

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

Accept ヘッダー accept

リスト操作およびルックアップ (GET) 操作を Schema Registry API、 Accept API から返されるデータの形式を決定するには、ヘッダーが必要です。 特定のリソースを検索する場合は、バージョン番号も Accept ヘッダー。

次の表に、互換性のあるリストを示します Accept ヘッダー値（バージョン番号を持つヘッダー値を含む）と、それらを使用したときに API が返す内容の説明。

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

スキーマのバージョンはで参照されています Accept スキーマレジストリ API および schemaRef.contentType ダウンストリーム Platform サービス API ペイロードのプロパティ。

現在、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 つを選択します。