メタデータ API 開発者ガイド
jAudience
エクスペリエンスビルダーサイトの利用者を表します。利用者は、その利用者をサイトでのターゲティングに割り当てて使用できるさまざまな条件で構成されます。Metadata メタデータ型を拡張し、その fullName 項目を継承します。
ファイルのサフィックスおよびディレクトリの場所
Audience コンポーネントのサフィックスは .audience で、audience フォルダに保存されます。
バージョン
Audience コンポーネントは、API バージョン 44.0 以降で使用できます。
特別なアクセスルール
Audience 型へのアクセスには、AudienceMetadata 権限が必要です。この権限は、ネットワークが有効化されている組織ではデフォルトで有効になります。
Audience 型の権限条件へのアクセスには、AudiencePermissionCriteria 権限が必要です。この権限は、API バージョン 45.0 以降で使用でき、ネットワークが有効化されている組織ではデフォルトで有効になります。
項目
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| audienceName | string | 必須。利用者の名前。 |
| container | string | 必須。利用者を含むサイトまたは組織の名前。 |
| criteria | AudienceCriteria | 必須。利用者の条件。この項目は、API バージョン 47.0 以降で使用できます。 |
| criterion | AudienceCriterion[] | 削除済み。利用者の条件のリスト。 |
| description | string | 利用者の説明。 |
| formula | string | 利用者を決定するために使用する数式。この項目は、API バージョン 45.0 以降で使用できます。 |
| formulaFilterType | FormulaFilterType(string 型の列挙) | 利用者の数式の種類を示します。有効な値は、次のとおりです。
|
| isDefaultAudience | boolean | 利用者がデフォルトの利用者か (true)、否か (false) を示します。この項目は API バージョン 48.0 で使用可能であり、必須の項目です。API バージョン 49.0 以降の場合、この項目は省略可能です。 デフォルトの利用者のフィル名は、Default_Network Name.audience の形式です。 |
| targets | PersonalizationTargetInfos | 利用者の対象。この項目は、API バージョン 47.0 以降で使用できます。 |
AudienceCriteria
利用者の条件を表します。このサブタイプは、API バージョン 47.0 以降で使用できます。
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| criterion | AudienceCriterion[] | 利用者の条件のリスト。利用者には最大 100 個の条件を追加できます。 |
AudienceCriterion
利用者の条件を表します。
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| criteriaNumber | int | 数式で条件に関連付けられている数値 ((1 AND 2) OR 3 など) です。この項目は、API バージョン 45.0 以降で使用できます。 |
| criterionValue | AudienceCriteriaValue | 条件の値。 |
| operator | AudienceCriterionOperator (string 型の列挙) | この条件に関連付けられている演算子。有効な値は、次のとおりです。
|
| type | AudienceCriterionType (string 型の列挙) | 必須。有効な値は、次のとおりです。
|
AudienceCriteriaValue
利用者の条件の値を表します。AudienceCriterion の各 type 項目値で使用可能な AudienceCriteriaValue 項目のリストについては、この表を参照してください。
次の表では、AudienceCriterion のさまざまな type 項目値で使用可能な AudienceCriteriaValue 項目がまとめられています。
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| audienceDeveloperName | string | 利用者の API 参照名。この項目は、API バージョン 53.0 以降で使用できます。この項目は、AudienceCriterion の type 項目の値が Audience の場合にのみ使用できます。 |
| city | string | ユーザの市区郡。この項目は、AudienceCriterion の type 項目の値が GeoLocation の場合にのみ使用できます。 |
| country | string | ユーザの国。この項目は、AudienceCriterion の type 項目の値が GeoLocation の場合にのみ使用できます。 |
| domain | string | ユーザのドメイン。この項目は、AudienceCriterion の type 項目の値が Domain の場合にのみ使用できます。 |
| entityField | string | オブジェクトの項目。この項目は、AudienceCriterion の type 項目の値が FieldBased の場合にのみ使用できます。 |
| entityType | string | オブジェクトの種別。この項目は、AudienceCriterion の type 項目の値が FieldBased の場合にのみ使用できます。 |
| fieldValue | string | 項目の値。この項目は、AudienceCriterion の type 項目の値が FieldBased の場合にのみ使用できます。 |
| isEnabled | string | ユーザに対して権限が有効化されているか (true)、否か (false) を示します。この項目は、API バージョン 45.0 以降で使用できます。この項目は、AudienceCriterion の type 項目の値が Permission の場合にのみ使用できます。 |
| permissionName | string | 標準ユーザまたはカスタム権限の有効な API 参照名を示します。この項目は、API バージョン 45.0 以降で使用できます。この項目は、AudienceCriterion の type 項目の値が Permission の場合にのみ使用できます。 |
| permissionType | string | 権限の種別。有効な値は、Standard および Custom です。この項目は、API バージョン 45.0 以降で使用できます。この項目は、AudienceCriterion の type 項目の値が Permission の場合にのみ使用できます。 |
| profile | string | ユーザのプロファイル。この項目は、AudienceCriterion の type 項目の値が Profile の場合にのみ使用できます。 |
| subdivision | string | ユーザの下位区分。この項目は、AudienceCriterion の type 項目の値が GeoLocation の場合にのみ使用できます。 |
| AudienceCriterion の type | AudienceCriteriaValue 項目 |
|---|---|
| GeoLocation |
city country subdivision |
| Domain | domain |
| Profile | profile |
| FieldBased |
entityField entityType fieldValue |
| Permission |
isEnabled permissionName permissionType |
| Audience | audienceDeveloperName |
PersonalizationTargetInfos
利用者の対象を表します。このサブタイプは、API バージョン 47.0 以降で使用できます。
利用者をリリースする場合は、エクスペリエンスバリエーション対象をサポートするために、ExperienceBundle をパッケージに含める必要があります。
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| target | PersonalizationTargetInfo[] | 利用者の対象のリスト。 |
PersonalizationTargetInfo
利用者の対象を表します。このサブタイプは、API バージョン 47.0 以降で使用できます。
| 項目名 | 項目の型 | 説明 |
|---|---|---|
| groupName | string | 必須。対象のグループ名。グループによって、関連する対象と利用者のペアがまとめられます。グループを 2,000 件まで、グループごとに対象を 500 件まで含めることができます。 対象のグループ名を決定するには、『Experience Cloud 開発者ガイド』の「パーソナライズ対象の API 参照名とグループ名」を参照してください。 |
| priority | int | 対象の優先度。グループ内で、優先度によって、ユーザが複数の利用者に一致する場合にどの対象が返されるかが決まります。 |
| targetType | string | 必須。対象の種別。対象となるデータの性質を示します。サポートされる値は次のとおりです。
ExperienceVariation の対象を 2,500 件まで、レコードの対象を 25,000 件まで含めることができます。 ExperienceVariation 対象種別についての詳細は、ExperienceBundle を参照してください。 |
| targetValue | string | 必須。対象の値。環境のバリエーションの開発者名です。たとえば、ページバリエーションの場合は ContactSupport_ContactSupportForCalifornia_Page となります。 対象の開発者名を判別するには、『Experience Cloud 開発者ガイド』の「パーソナライズ対象の API 参照名とグループ名」を参照してください。 |
使用方法
利用者を削除するためにメタデータ API を使用することはできません。
API バージョン 47.0 以降では、条件を使用せずに利用者を作成することはできません。
利用者の入力で提供される対象のリストは、必要な対象割り当ての状態とみなされます。たとえば、対象の削除、作成、更新については次の情報を参照してください。
- 対象の削除
- 1 つの対象を利用者から削除するには、利用者のすべての対象のリストから削除する対象を差し引いたリストをリリースします。
- 利用者からすべての対象を削除するには、空の targets タグを付けて利用者をリリースします。次に例を示します。
- 対象を更新しない利用者の更新
- 対象を更新せずに利用者を更新するには、targets タグを付けずに利用者をリリースします。次に例を示します。
- 対象の作成
- 対象を作成するには、利用者のすべての対象のリストに作成する対象を加えたリストをリリースします。
- 対象の優先度の更新
- 利用者内の対象の優先度を変更するには、対象の新しい優先度値を使用して利用者のすべての対象者のリストをリリースします。
- 別の利用者の優先度に影響を及ぼす対象の優先度を変更するには、対象の新しい優先度値を使用してすべての対象のリストで両方の利用者をリリースします。
- 利用者の対象割り当ての更新
- 対象を新しい利用者に再割り当てするには、すべての対象のリストで両方の利用者をリリースします。削除した対象が含まれるリストと、追加した対象が含まれるリストをリリースします。
マニフェストファイル内のワイルドカードのサポート
このメタデータ型では、package.xml マニフェストファイル内のワイルドカード文字 * (アスタリスク) がサポートされます。マニフェストファイルの使用についての詳細は、「zip ファイルを使用したメタデータのリリースと取得」を参照してください。