Schema Registry API使用の手引き

Schema Registry APIを使用すると、様々なエクスペリエンスデータモデル(XDM)リソースを作成および管理できます。 このドキュメントでは、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 呼び出し例の読み取り

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: {IMS_ORG}

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

  • x-sandbox-name: {SANDBOX_NAME}
メモ

Platformのサンドボックスについて詳しくは、サンドボックスのドキュメントを参照してください。

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

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

  • Content-Type: application/json

使用する TENANT_ID

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}'

応答

正常に応答すると、組織の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 について

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

グローバルコンテナ

globalコンテナは、すべての標準Adobeと[!DNL Experience Platform]パートナーが提供するクラス、ミックスイン、データ型、スキーマを保持します。 globalコンテナに対してのみリストおよび参照(GET)要求を実行できます。

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

GET /global/classes

テナントコンテナ

tenantコンテナは、IMS組織が定義するすべてのクラス、ミックスイン、データ型、スキーマ、および記述子を保持し、独自のTENANT_IDと混同しないでください。 これらは各組織に固有のもので、他の IMS 組織では表示も管理もできません。tenantコンテナで作成するリソースに対して、すべてのCRUD操作(GET、POST、PUT、PATCH、DELETE)を実行できます。

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

POST /tenant/mixins

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

リソース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

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

Accept ヘッダー

Schema Registry APIでリストおよびルックアップ(GET)操作を実行する場合、APIから返されるデータの形式を決定するにはAcceptヘッダーが必要です。 特定のリソースを検索する場合は、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={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。記述子が含まれます。
メモ

メジャーバージョン(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 を配列として追加できます。
    • フィールドの種類は、レジストリで任意のデータタイプを使用して定義することもできます。詳しくは、『データ型エンドポイントガイド』のデータ型の作成に関する節を参照してください。
  • description では、フィールドとフィールドデータについての関連情報を表します。スキーマにアクセスした人が誰でもフィールドの意図を理解できるように、明確な言葉で記述する必要があります。

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

次の手順

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

このページ