和集合エンドポイント

Unions (or union views) are system-generated, read-only schemas that aggregate the fields of all schemas which share the same class (XDM ExperienceEvent or XDM Individual Profile) and are enabled for Real-time Customer Profile.

このドキュメントでは、Schema Registry API で和集合を操作するための基本的な概念と、様々な操作のサンプル呼び出しを示しています。XDM の和集合に関する一般的な情報については、「Basics of schema composition」の和集合に関する節を参照してください。

和集合スキーマフィールド

和集合スキーマには、次の3つの主要フィールドが Schema Registry 自動的に含まれます。 identityMaptimeSeriesEventsおよび segmentMembership

ID マップ

和集合スキーマの identityMap は、和集合に関連付けられているレコードスキーマ内の既知の ID を表します。ID マップは、名前空間で特定された異なる配列に ID を分離します。リストされる ID 自体は、一意の id 値を含むオブジェクトです。詳しくは、ID サービスに関するドキュメントを参照してください。

時系列イベント

timeSeriesEvents 配列は、和集合に関連付けられているレコードスキーマに関連する時系列イベントのリストです。プロファイルデータをデータセットにエクスポートする場合、この配列は各レコードに含まれます。 これは、様々な使用事例に役立ちます。例えば、モデルがレコード属性に加えてプロファイルの行動履歴全体を必要とする機械学習などに役立ちます。

セグメントメンバーシップマップ

segmentMembership マップには、セグメント評価の結果が格納されます。Segmentation API を使用してセグメントジョブが正常に実行された場合、マップが更新されます。また、segmentMembership には、Platform に取り込まれた評価済みのオーディエンスセグメントも格納されます。このため、Adobe Audience Manager などの他のソリューションと統合することができます。詳しくは、API を使用したセグメ ントの作成に関するチュートリアルを参照してください。

Retrieve a list of unions

スキーマに union タグを設定すると、がそのスキーマの基となるクラスの和集合にそのスキーマを Schema Registry 自動的に追加します。 該当するクラスに和集合が存在しない場合は、新しい和集合が自動的に作成されます。 The $id for the union is similar to the standard $id of other Schema Registry resources, with the only difference being that is appended by two underscores and the word "union" (__union).

エンドポイントにGETリクエストを行うことで、使用可能な和集合のリストを表示でき /tenant/unions ます。

API 形式

GET /tenant/unions

リクエスト

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

The response format depends on the Accept header sent in the request. The following Accept headers are available for listing unions:

Accept ヘッダー 説明
application/vnd.adobe.xed-id+json 各リソースの短い概要を返します。 リソースのリストを表示する際に推奨されるヘッダーです。 (制限:300)
application/vnd.adobe.xed+json Returns full JSON class for each resource, with original $ref and allOf included. (制限:300)

応答

リクエストが成功した場合は、HTTP ステータス 200(OK)、およびレスポンス本文に results 配列が返されます。和集合が定義されている場合、各和集合の詳細は配列内のオブジェクトとして提供されます。 和集合が定義されていない場合も、HTTP ステータス 200(OK)が返されますが、results 配列は空になります。

{
    "results": [
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile__union",
            "meta:altId": "_xdm.context.profile__union",
            "version": "1"
        },
        {
            "title": "Property",
            "$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590__union",
            "meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590__union",
            "version": "1"
        }
    ]
}

Look up a union

特定の和集合を表示するには、$id と、和集合の詳細の一部またはすべて(Accept ヘッダーにより異なる)を含む GET リクエストを実行します。

NOTE

Union lookups are available using the /unions and /schemas endpoint to enable them for use in Profile exports into a dataset.

API 形式

GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}
パラメーター 説明
{UNION_ID} The URL-encoded $id URI of the union you want to look up. 和集合スキーマの URI には「__union」が追加されます。

リクエスト

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions/https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile__union \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed+json; version=1'

和集合の検索リクエストでは、Accept ヘッダーに version を含める必要があります。

和集合スキーマの検索では、次の Accept ヘッダーを使用できます。

Accept 説明
application/vnd.adobe.xed+json; version= $refallOf を含む未処理の和集合。タイトルと説明が含まれます。
application/vnd.adobe.xed-full+json; version= $ref 属性と allOf が解決されます。タイトルと説明が含まれます。

応答

リクエストが成功した場合は、リクエストパスで指定した $id のクラスを実装するすべてのスキーマの和集合表示が返されます。

レスポンスの形式は、リクエストで送信した Accept ヘッダーにより異なります。異なる Accept ヘッダーを試して、応答を比較し、使用事例に最適なヘッダーを判断します。

{
    "type": "object",
    "description": "Union view of all schemas that extend https://ns.adobe.com/xdm/context/profile",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        }
    ],
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599",
        "https://ns.adobe.com/xdm/context/profile-personal-details"
    ],
    "title": "Union object for https://ns.adobe.com/xdm/context/profile",
    "$id": "https://ns.adobe.com/xdm/context/profile__union",
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:altId": "_xdm.context.profile__union",
    "version": "1.0",
    "meta:resourceType": "unions",
    "meta:registryMetadata": {}
}

和集合メンバーシップのスキーマを有効にする

スキーマをそのクラスの和集合に含めるには、タグをスキーマの union meta:immutableTags 属性に追加する必要があります。 これを行うには、対象のスキーマに対して、1つの文字列値を持つ meta:immutableTags 配列を追加するPATCHリクエスト union を作成します。 詳しい例については、 スキーマエンドポイントガイド を参照してください。

和集合でのスキーマのリスト

特定のエンドポイントに属するスキーマを確認するには、エンドポイントに対してGETリクエストを実行し /tenant/schemas ます。 property クエリパラメーターを使用すると、アクセス先の和集合があるクラスと同等の meta:immutableTags フィールドおよび meta:class を含むスキーマのみを返すようにレスポンスを設定できます。

API 形式

GET /tenant/schemas?property=meta:immutableTags==union&property=meta:class=={CLASS_ID}
パラメーター 説明
{CLASS_ID} 和集合が有効なスキーマ $id をリストするクラスの。

リクエスト

次のリクエストは、 XDM Individual Profile クラスの和集合の一部であるすべてのスキーマのリストを取得します。

curl -X GET \
  'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile' \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -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}'

The response format depends on the Accept header sent in the request. The following Accept headers are available for listing schemas:

Accept ヘッダー 説明
application/vnd.adobe.xed-id+json 各リソースの短い概要を返します。 リソースのリストを表示する際に推奨されるヘッダーです。 (制限:300)
application/vnd.adobe.xed+json Returns full JSON schema for each resource, with original $ref and allOf included. (制限:300)

応答

「成功した」応答は、和集合のメンバーシップが有効になっている、指定したクラスに属するスキーマのみを含む、フィルターされたリストを返します。 複数のクエリーパラメーターを使用する場合は、AND が想定されることに注意してください。

{
    "results": [
        {
            "title": "Schema 1",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
            "meta:altId": "_{TENANT_ID}.schemas.142afb78d8b368a5ba97a6cc8fc7e033",
            "version": "1.2"
        },
        {
            "title": "Schema 2",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e7297a6ddfc7812ab3a7b504a1ab98da",
            "meta:altId": "_{TENANT_ID}.schemas.e7297a6ddfc7812ab3a7b504a1ab98da",
            "version": "1.5"
        },
        {
            "title": "Schema 3",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/50f960bb810e99a21737254866a477bf",
            "meta:altId": "_{TENANT_ID}.schemas.50f960bb810e99a21737254866a477bf",
            "version": "1.2"
        },
        {
            "title": "Schema 4",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/a39655ca8ea3d5c1f36a463b45fccca8",
            "meta:altId": "_{TENANT_ID}.schemas.a39655ca8ea3d5c1f36a463b45fccca8",
            "version": "1.1"
        },
        {
            "title": "Schema 5",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/c063fac45c6d6285ef33b0e2af09f633",
            "meta:altId": "_{TENANT_ID}.schemas.c063fac45c6d6285ef33b0e2af09f633",
            "version": "1.2"
        },
        {
            "title": "Schema 6",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/dfebb19b93827b70bbad006137812537",
            "meta:altId": "_{TENANT_ID}.schemas.dfebb19b93827b70bbad006137812537",
            "version": "1.7"
        }
    ],
    "_links": {
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile"
        }
    }
}

このページ