スキーマの一意の ID とは何ですか?

Schema Registry のすべてのリソース(スキーマ、フィールドグループ、データタイプ、クラス)には、参照およびルックアップ用の一意の ID として機能する URI があります。API でスキーマを表示すると、最上位レベルの $id および meta:altId 属性でスキーマが見つかります。

詳しくは、Schema Registry API ガイドのリソースの識別の節を参照してください。

長いフィールドタイプの最大サイズはどれくらいですか?

長いフィールドタイプは、最大サイズが 53(+1)ビットの整数で、可能な範囲は -9007199254740992 ~ 9007199254740992 です。これは、JSON の JavaScript 実装が長整数を表す方法に制限があるためです。

フィールドタイプについて詳しくは、XDM フィールドタイプの制約に関するドキュメントを参照してください。

meta:AltId とは

meta:altId は、スキーマの一意の ID です。 meta:altId は、API 呼び出しで使用する参照しやすい ID を提供します。 この ID を使用すると、JSON URI 形式と同様に使用するたびにエンコード/デコードする必要がなくなります。

マップデータタイプの使用制限は何ですか。

XDM は、このデータタイプの使用に次の制限を設けます。

  • マップの型はオブジェクト型でなければなりません。
  • マップの種類にはプロパティを定義できません(つまり、「空の」オブジェクトを定義します)。
  • マップタイプには、文字列または整数のいずれかでマップ内に配置できる値を記述する additionalProperties.type フィールドを含める必要があります。
  • マルチエンティティのセグメント化は、マップキーに基づいてのみ定義でき、値に基づいて定義することはできません。
  • マップは、アカウントオーディエンスではサポートされていません。

詳しくは、 マップオブジェクトの使用制限を参照してください。

NOTE
マルチレベル マップまたはマップのマップはサポートされていません。

スキーマIdentity Management

この節では、スキーマ内の ID の定義と管理に関するよくある質問に対する回答を示します。

スキーマの ID を定義するにはどうすればよいですか?

Experience Platform では、ID は、解釈されるデータのソースに関係なく、サブジェクト(通常は個人)の識別に使用されます。キーフィールドを「ID」としてマークすることで、スキーマで ID が定義されます。ID によく使用されるフィールドには、メールアドレス、電話番号、Experience Cloud ID (ECID)、CRM ID、その他の一意の ID フィールドなどがあります。

フィールドは、API またはユーザーインターフェイスを使用して ID としてマークできます。

API で ID を定義

API では、ID は ID 記述子を作成することで確立されます。ID 記述子は、スキーマの特定のプロパティが一意の ID であることを示します。

ID 記述子は、/descriptors エンドポイントへの POST リクエストによって作成されます。作成に成功した場合は、HTTP ステータス 201(Created)と、新しい記述子の詳細を含む応答オブジェクトを受け取ります。

API での ID 記述子の作成について詳しくは、Schema Registry 開発者ガイドの記述子に関する節を参照してください。

UI での ID の定義

スキーマエディターにスキーマを開いた状態で、ID としてマークするフィールドをエディターの「構造」セクションで選択します。右側の「フィールドプロパティ」で、「ID」チェックボックスをオンにします。

UI で ID を管理する方法について詳しくは、スキーマエディターのチュートリアルの ID フィールドの定義に関する節を参照してください。

スキーマにプライマリ ID は必要ですか?

スキーマにはプライマリ ID がないか 1 つのみ存在できるので、プライマリ ID はオプションです。ただし、スキーマを Real-Time Customer Profile で使用できるようにするには、スキーマにプライマリ ID が必要です。詳しくは、スキーマエディターのチュートリアルの ID に関する節を参照してください。

スキーマプロファイルの有効化

この節では、リアルタイム顧客プロファイルでスキーマを使用できるようにする際のガイダンスを示します。

Real-Time Customer Profile でスキーマを使用できるようにするにはどうすればよいですか?

スキーマの meta:immutableTags 属性内に「union」タグを追加すれば、スキーマを Real-Time Customer Profile で使用できるようになります。スキーマを Profile で使用できるようにするには、API またはユーザーインターフェイスを使用します。

API を使用して既存のスキーマを Profile に有効にする方法

PATCH リクエストを作成して、スキーマを更新し、値「union」を含む配列として meta:immutableTags 属性を追加します。更新が成功すると、応答に更新されたスキーマが表示され、スキーマに和集合タグが含まれるようになります。

API を使用して、スキーマを Real-Time Customer Profile で使用できるようにする方法について詳しくは、Schema Registry 開発者ガイドの結合に関するドキュメントを参照してください。

UI を使用して既存のスキーマを Profile に有効にする方法

Experience Platform で、左側のナビゲーションにある「スキーマ」を選択し、有効にするスキーマの名前をスキーマのリストから選択します。次に、エディターの右側の「スキーマプロパティ」で、「プロファイル」を選択してオンに切り替えます。

詳しくは、スキーマエディターのチュートリアルのリアルタイム顧客プロファイルでの使用に関する節を参照してください。

Adobe Analytics データをソースとしてインポートした場合、自動作成されたスキーマはプロファイルに対して有効になっていますか?

リアルタイム顧客プロファイルに対してスキーマは自動的には有効になりません。 プロファイルに対して有効になっているスキーマに基づいて、プロファイルのデータセットを明示的に有効にする必要があります。 リアルタイム顧客プロファイルで使用するデータセットを有効にするために必要な手順と要件については、ドキュメントを参照してください。

プロファイルが有効なスキーマを削除できますか?

リアルタイム顧客プロファイルに対して有効にした後は、スキーマを削除できません。 プロファイルに対してスキーマを有効にすると、そのスキーマを無効にしたり削除したりすることはできず、スキーマからフィールドを削除することもできません。 したがって、プロファイルに対して有効にする前に、スキーマ設定を慎重に計画および検証することが重要です。 ただし、プロファイルが有効になっているデータセットは削除できます。 情報については、次を参照してください:https://experienceleague.adobe.com/ja/docs/experience-platform/catalog/datasets/user-guide#delete-a-profile-enabled-dataset

プロファイルが有効なスキーマを使用しない場合は、スキーマの名前を 使用しない または 非アクティブ に変更することをお勧めします。

スキーマの変更と制限

この節では、スキーマ変更ルールと重大な変更の防止に関する説明を示します。

スキーマでは重大な変更の防止をどのような場合に開始しますか?

データセットの作成に使用されていないか、Real-Time Customer Profile での使用が有効になっていない限り、スキーマに重大な変更を加えることができます。スキーマがデータセットの作成に使用されたり、Real-Time Customer Profile で使用できるようになったりすると、スキーマ進化 のルールがシステムで厳密に適用されます。

和集合スキーマを直接編集できますか?

和集合スキーマは読み取り専用であり、システムによって自動的に生成されます。和集合スキーマを直接編集することはできません。和集合スキーマは、特定のクラスを実装するスキーマに「和集合」タグが追加されたときに、そのクラスに対して作成されます。

XDM での結合について詳しくは、Schema Registry API ガイドの結合の節を参照してください。

スキーマにデータを取り込むには、データファイルをどのような形式にする必要がありますか?

Experience Platform では、Parquet または JSON 形式のデータファイルを受け入れます。これらのファイルの内容は、データセットが参照するスキーマに準拠している必要があります。データファイル取得に関するベストプラクティスについて詳しくは、「バッチ取得の概要」を参照してください。

スキーマを読み取り専用スキーマに変換するにはどうすればよいですか?

現在、スキーマを読み取り専用に変換することはできません。

エラーとトラブルシューティング

Schema Registry API を使用する際に発生する可能性のあるエラーメッセージのリストを以下に示します。

リソースが見つかりません

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1010-404",
    "title": "Resource not found",
    "status": 404,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found.",
        "sub-errors": []
    },
    "detail": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found."
}

このエラーは、システムが特定のリソースを見つけることができなかった場合に表示されます。リソースが削除されたか、API 呼び出しのパスが無効です。再試行する前に、API 呼び出しの有効なパスを入力したことを確認してください。リソースの正しい ID を入力したこと、およびパスが適切なコンテナ(グローバルまたはテナント)で適切に名前空間化されていることを確認する必要があります。。

NOTE
取得するリソースタイプに応じて、このエラーは次の type URI のいずれかを使用できます。
  • http://ns.adobe.com/aep/errors/XDM-1010-404
  • http://ns.adobe.com/aep/errors/XDM-1011-404
  • http://ns.adobe.com/aep/errors/XDM-1012-404
  • http://ns.adobe.com/aep/errors/XDM-1013-404
  • http://ns.adobe.com/aep/errors/XDM-1014-404
  • http://ns.adobe.com/aep/errors/XDM-1015-404
  • http://ns.adobe.com/aep/errors/XDM-1016-404
  • http://ns.adobe.com/aep/errors/XDM-1017-404

API での参照パスの作成について詳しくは、Schema Registry 開発者ガイドのコンテナおよびリソースの識別の節を参照してください。

タイトルが一意ではありません

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1521-400",
    "title": "Title not unique",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title",
        "sub-errors": []
    },
    "detail": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title"
}

このエラーメッセージは、別のリソースで既に使用されているタイトルを持つリソースを作成しようとすると表示されます。タイトルは、すべてのリソースタイプで一意である必要があります。例えば、スキーマで既に使用されているタイトルのフィールドグループを作成しようとすると、このエラーが表示されます。

名前空間の検証エラー

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1021-400",
    "title": "Namespace validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}.",
        "sub-errors": []
    },
    "detail": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}."
}

このエラーメッセージが表示されるのは、名前空間の設定が適切でないフィールドを含んだリソースを作成しようとした場合や、名前空間の設定が適切でないフィールドを既存のリソースに追加しようとした場合です。

組織で定義されたリソースでは、他の業界やベンダーのリソースとの競合を避けるために、フィールドの名前空間をテナント ID の下に設定する必要があります。標準のフィールドグループを使用してスキーマを作成する場合は、それらのフィールドグループの構造内に追加するカスタムフィールドも、テナント ID の下に名前空間を設定する必要があります。

NOTE
このエラーでは、名前空間エラーの固有の性質に応じて、次の type URI のいずれかを、異なるメッセージ詳細と共に使用できます。
  • http://ns.adobe.com/aep/errors/XDM-1020-400
  • http://ns.adobe.com/aep/errors/XDM-1021-400
  • http://ns.adobe.com/aep/errors/XDM-1022-400
  • http://ns.adobe.com/aep/errors/XDM-1023-400
  • http://ns.adobe.com/aep/errors/XDM-1024-400

XDM リソースの適切なデータ構造の詳細な例については、スキーマレジストリ API ガイドを参照してください。

Accept ヘッダーが無効です

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1006-400",
    "title": "Accept header invalid",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json",
        "sub-errors": []
    },
    "detail": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json"
}

Schema Registry API の GET リクエストには、システムで応答の形式を決定するために Accept ヘッダーが必要です。このエラーは、必須の Accept ヘッダーが無効か見つからない場合に発生します。

使用しているエンドポイントに応じて、正常な応答を得るための有効な Accept ヘッダーがどのようなものであるかを detailed-message プロパティが示します。実行しようとしている API リクエストに適合する Accept ヘッダーを正しく入力してあることを確認してから、もう一度やり直してください。

NOTE
このエラーでは、使用しているエンドポイントに応じて、次の type URI のいずれかを使用できます。
  • http://ns.adobe.com/aep/errors/XDM-1006-400
  • http://ns.adobe.com/aep/errors/XDM-1007-400
  • http://ns.adobe.com/aep/errors/XDM-1008-400
  • http://ns.adobe.com/aep/errors/XDM-1009-400

様々な API リクエストに適合する Accept ヘッダーのリストについては、スキーマレジストリ開発者ガイドの対応する節を参照してください。

Real-Time Customer Profile のエラー

次のエラーメッセージは、スキーマを Real-Time Customer Profile で使用できるようにする場合の操作に関連しています。詳しくは、Schema Registry API 開発者ガイドの結合の節を参照してください。

参照 ID 記述子が必要です

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1526-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union.",
        "sub-errors": []
    },
    "detail": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union."
}

このエラーメッセージが表示されるのは、スキーマを Profile で使用できるようにしようとしたときに、そのスキーマのプロパティのいずれかに参照 ID 記述子のない関係記述子が含まれている場合です。このエラーを解決するには、問題のスキーマフィールドに参照 ID 記述子を追加します。

参照 ID 記述子フィールドの名前空間と宛先スキーマの名前空間が一致している必要があります

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1527-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field.",
        "sub-errors": []
    },
    "detail": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field."
}
NOTE
このエラーの場合、「宛先スキーマ」は関係の参照スキーマを指します。

関係記述子を含んだスキーマを Profile で使用できるようにするには、ソースフィールドの名前空間と参照フィールドのプライマリ名前空間を同じにする必要があります。このエラーメッセージが表示されるのは、参照 ID 記述子に一致しない名前空間を含んだスキーマを有効にしようとした場合です。

この問題を解決するには、参照スキーマの ID フィールドの xdm:namespace 値が、ソースフィールドの参照 ID 記述子における xdm:identityNamespace プロパティの値と一致することを確認してください。

標準の ID 名前空間コードのリストについては、「ID 名前空間の概要」の標準の名前空間の節を参照してください。