Getting started with the Schema Registry API

この Schema Registry APIを使用すると、様々なエクスペリエンスデータモデル(XDM)リソースを作成および管理できます。 This document provides an introduction to the core concepts you need to know before attempting to make calls to the Schema Registry API.

前提条件

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

  • Experience Data Model (XDM) System:顧客体験データを Experience Platform 整理する際に使用される標準化されたフレームワーク。
  • Real-time Customer Profile:複数のソースからの集計データに基づいて、統合されたリアルタイムの消費者プロファイルを提供します。
  • Sandboxes: Experience Platform は、1つの Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスを提供します。

XDMは、JSONスキーマ形式を使用して、取り込むカスタマーエクスペリエンスデータの構造を記述し、検証します。 したがって、この基盤となる技術をより深く理解するために、 公式のJSONスキーマドキュメント を確認することを強くお勧めします。

API 呼び出し例の読み取り

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

必須ヘッダーの値の収集

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

All resources in Experience Platform, including those belonging to the Schema Registry, are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE

For more information on sandboxes in Platform, see the sandbox documentation.

All lookup (GET) requests to the Schema Registry require an additional Accept header, whose value determines the format of information returned by the API. 詳しくは、この後の Accept ヘッダーの節を参照してください。

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

  • Content-Type: application/json

使用する TENANT_ID

APIガイド全体で、APIの概要に関する情報を確認でき TENANT_IDます。 この ID は、作成したリソースに名前空間が適切に設定されていること、またそのリソースが IMS 組織内に格納されていることを確認するために使用されます。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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

応答

A successful response returns information regarding your organization's use of the Schema Registry. この中には TENANT_ID の値である tenantId 属性が含まれています。

{
  "imsOrg":"{IMS_ORG}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [ 
    {
      "title": "Sample Mixin",
      "description": "New Sample Mixin.",
      "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 Mixin",
      "description": "New Sample Mixin.",
      "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 について

Calls to the Schema Registry API require the use of a CONTAINER_ID. There are two containers against which API calls can be made: the global container and the tenant container.

グローバルコンテナ

The global container holds all standard Adobe and Experience Platform partner provided classes, mixins, data types, and schemas. You may only perform list and lookup (GET) requests against the global container.

この global コンテナを使用した呼び出しの例を次に示します。

GET /global/classes

テナントコンテナ

Not to be confused with your unique TENANT_ID, the tenant container holds all classes, mixins, data types, schemas, and descriptors defined by an IMS Organization. これらは各組織に固有のもので、他の IMS 組織では表示も管理もできません。You may perform all CRUD operations (GET, POST, PUT, PATCH, DELETE) against resources that you create in the tenant container.

この tenant コンテナを使用した呼び出しの例を次に示します。

POST /tenant/mixins

When you create a class, mixin, schema or data type in the tenant container, it is saved to the Schema Registry and assigned an $id URI that includes your TENANT_ID. この $id は、API 全体で特定のリソースを参照する際に使用されます。$id 値の例については、次の節で説明します。

リソースの識別

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

  • 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

Calls to the Schema Registry API will support either the URL-encoded $id URI or the meta:altId (dot-notation format). 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

Accept ヘッダー

When performing list and lookup (GET) operations in the Schema Registry API, an Accept header is required to determine the format of the data returned by the API. When looking up specific resources, a version number must also be included in the Accept header.

The following table lists compatible Accept header values, including those with version numbers, along with descriptions of what the API will return when they are used.

Accept 説明
application/vnd.adobe.xed-id+json ID のリストのみを返します。これは、リソースを一覧表示する際に最も使用される値です。
application/vnd.adobe.xed+json 元の $ref および allOf を含むフル JSON スキーマのリストを返します。これは、全リソースのリストを返す際に使用されます。
application/vnd.adobe.xed+json; version={MAJOR_VERSION} $refallOf を含む未処理の XDM です。タイトルと説明があります。
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref 属性と解決された allOf。タイトルと説明があります。
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} $refallOf を含む未処理の XDM です。タイトルや説明はありません。
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref 属性と解決された allOf。タイトルや説明はありません。
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $ref 属性と解決された allOf。記述子が含まれます。
NOTE

メジャーバージョン(1、2、3など)のみを指定した場合、レジストリは最新のマイナーバージョン(例:.1、.2、.3)が自動的に更新されます。

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.",
}
  • フィールドオブジェクトの名前には、英数字、ダッシュ、アンダースコアの各文字を使用できますが、先頭にアンダースコアを配置することは​できません
    • 正しい:fieldNamefield_name2Field-Namefield-name_3
    • 誤り:_fieldName
  • フィールドオブジェクトの名前には、キャメルケースを使用することをお勧めします。例:fieldName
  • フィールドには title が必要です。これは、単語の先頭のみ大文字で記述します。例:Field Name
  • フィールドには type が必要です。
    • 特定のタイプを定義する場合、オプションの format が必要なことがあります。
    • データに特定の形式を設定する必要がある場合は、examples を配列として追加できます。
    • フィールドの種類は、レジストリで任意のデータタイプを使用して定義することもできます。See the section on creating a data type in the data types endpoint guide for more information.
  • description では、フィールドとフィールドデータについての関連情報を表します。スキーマにアクセスした人が誰でもフィールドの意図を理解できるように、明確な言葉で記述する必要があります。

APIで異なるフィールドタイプを定義する方法について詳しくは、 フィールド制約のドキュメント (英語)を参照してください。

次の手順

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

このページ