Skip to content

オブジェクトの配列

このページでは、関連する属性をグループ化するためにオブジェクトの配列を使用する方法について説明します。たとえば、ペットオブジェクト、曲オブジェクト、アカウントオブジェクトのグループがあり、それらがすべて1人のユーザーに属している場合があります。これらのオブジェクトの配列は、Liquid を使用してメッセージングをパーソナライズしたり、オブジェクト内のいずれかの要素が条件に一致する場合にオーディエンスセグメントを作成したりするために使用できます。

サポートされるデータ型

以下のデータタイプがサポートされている：

考慮事項

  • オブジェクトの配列は、API を通じて送信されるカスタム属性を対象としています。CSV アップロードはサポートされていません。これは、CSVファイル内のカンマが列区切りとして解釈され、値内のカンマがパースエラーを引き起こすためです。
  • オブジェクトの配列にはアイテム数の制限はありませんが、最大サイズは 100 KB です。更新（$add や $update など）によって配列がこの制限を超える場合、Braze はその更新を破棄し、属性は変更されません。API リクエスト自体は成功レスポンスを返します。新しいアイテムを追加できるように配列を制限内に収めるには、まず $remove を使用して配列からアイテムを削除してください。
  • すべての Braze パートナーがオブジェクトの配列をサポートしているわけではありません。連携がこの機能をサポートしているかどうかは、パートナードキュメントを参照して確認してください。

配列内のアイテムを更新または削除するには、キーと値でアイテムを識別する必要があるため、配列内の各アイテムに一意の識別子を含めることを検討してください。一意性は配列内のみにスコープされ、配列から特定のオブジェクトを更新および削除する場合に役立ちます。これは Braze によって強制されるものではありません。

API の例

以下は、pets 配列を使用した /users/track の例です。ペットのプロパティをキャプチャするには、pets をオブジェクトの配列としてリストする API リクエストを送信します。各オブジェクトには、後で更新を行う際に参照できる一意の id が割り当てられていることに注意してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald"
        }
      ]
    }
  ]
}

$add 演算子を使用して、配列に別のアイテムを追加します。以下の例は、ユーザーの pets 配列にさらに3つのペットオブジェクトを追加する方法を示しています。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": {
        "$add": [
          {
            "id": 3,
            "type": "dog",
            "breed": "corgi",
            "name": "Doug"
          },
          {
            "id": 4,
            "type": "fish",
            "breed": "salmon",
            "name": "Larry"
          },
           {
            "id": 5,
            "type": "bird",
            "breed": "parakeet",
            "name": "Mary"
          }
        ]
      }
    }
  ]
}

_merge_objects パラメーターと $update 演算子を使用して、配列内の特定のオブジェクトの値を更新します。シンプルな階層化カスタム属性オブジェクトの更新と同様に、ディープマージが実行されます。

$update は、配列内のオブジェクトからネストされたプロパティを削除するためには使用できないことに注意してください。これを行うには、配列からアイテム全体を削除し、その特定のキーを含まないオブジェクトを追加する必要があります（$remove と $add の組み合わせを使用）。

以下の例は、id が 4 のオブジェクトの breed プロパティを goldfish に更新する方法を示しています。このリクエスト例では、id が 5 のオブジェクトの name も Annette に更新しています。_merge_objects パラメーターが true に設定されているため、これら2つのオブジェクトの他のすべてのフィールドはそのまま維持されます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "pets": {
        "$update": [
          {
            "$identifier_key": "id",
            "$identifier_value": 4,
            "$new_object": {
              "breed": "goldfish"
            }
          },
          {
            "$identifier_key": "id",
            "$identifier_value": 5,
            "$new_object": {
              "name": "Annette"
            }
          }
        ]
      }
    }
  ]
}

$remove 演算子を一致するキー（$identifier_key）と値（$identifier_value）と組み合わせて使用し、配列からオブジェクトを削除します。

以下の例は、pets 配列内で id の値が 1 のオブジェクト、id の値が 2 のオブジェクト、および type の値が dog のオブジェクトを削除する方法を示しています。type の値が dog のオブジェクトが複数ある場合、一致するすべてのオブジェクトが削除されます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": {
        "$remove": [
          // Remove by ID
          {
            "$identifier_key": "id",
            "$identifier_value": 1
          },
          {
            "$identifier_key": "id",
            "$identifier_value": 2
          },
          // Remove any dog
          {
            "$identifier_key": "type",
            "$identifier_value": "dog"
          }
        ]
      }
    }
  ]
}

処理順序

単一の /users/track リクエストに同じ配列属性に対する $add、$remove、$update 操作が含まれている場合、Braze は以下の順序で処理します。

  1. $add
  2. $remove
  3. $update

$add が $remove より先に実行されるため、単一のリクエスト内で $remove の後に $add を行うアップサートメカニズムは使用できません。$add が最初に処理され、その後 $remove がアイテムを削除します。アップサートを行うには、$add の前に別のリクエストで $remove を送信してください。

タイムスタンプ

オブジェクトの配列にタイムスタンプなどのフィールドを含める場合は、プレーンな文字列や Unix エポック整数ではなく、$time 形式を使用してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "attributes": [
    {
      "external_id": "user123",
      "purchases": [
        {
          "item_name": "T-shirt",
          "price": 19.99,
          "purchase_time": {
            "$time": "2020-05-28"
          }
        }
      ]
    }
  ]
}

SDK の例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

val json = JSONArray()
    .put(JSONObject()
        .put("id", 1)
        .put("type", "dog")
        .put("breed", "beagle")
        .put("name", "Gus"))
    .put(JSONObject()
        .put("id", 2)
        .put("type", "cat")
        .put("breed", "calico")
        .put("name", "Gerald")
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("pets", json)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

val json = JSONObject()
    .put("\$add", JSONArray()
        .put(JSONObject()
            .put("id", 3)
            .put("type", "dog")
            .put("breed", "corgi")
            .put("name", "Doug"))
        .put(JSONObject()
            .put("id", 4)
            .put("type", "fish")
            .put("breed", "salmon")
            .put("name", "Larry"))
        .put(JSONObject()
            .put("id", 5)
            .put("type", "bird")
            .put("breed", "parakeet")
            .put("name", "Mary")
        )
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("pets", json, true)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

val json = JSONObject()
    .put("\$update", JSONArray()
        .put(JSONObject()
            .put("\$identifier_key", "id")
            .put("\$identifier_value", 4)
            .put("\$new_object", JSONObject()
                .put("breed", "goldfish")
            )
        )
        .put(JSONObject()
            .put("\$identifier_key", "id")
            .put("\$identifier_value", 5)
            .put("\$new_object", JSONObject()
                .put("name", "Annette")
            )
        )
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("pets", json, true)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

val json = JSONObject()
    .put("\$remove", JSONArray()
        .put(JSONObject()
            .put("\$identifier_key", "id")
            .put("\$identifier_value", 1)
        )
        .put(JSONObject()
            .put("\$identifier_key", "id")
            .put("\$identifier_value", 2)
        )
        .put(JSONObject()
            .put("\$identifier_key", "type")
            .put("\$identifier_value", "dog")
        )
    )

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("pets", json, true)
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

let json: [[String: Any?]] = [
  [
    "id": 1,
    "type": "dog",
    "breed": "beagle",
    "name": "Gus"
  ],
  [
    "id": 2,
    "type": "cat",
    "breed": "calico",
    "name": "Gerald"
  ]
]

braze.user.setCustomAttribute(key: "pets", array: json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

let json: [String: Any?] = [
  "$add": [
    [
      "id": 3,
      "type": "dog",
      "breed": "corgi",
      "name": "Doug"
    ],
    [
      "id": 4,
      "type": "fish",
      "breed": "salmon",
      "name": "Larry"
    ],
    [
      "id": 5,
      "type": "bird",
      "breed": "parakeet",
      "name": "Mary"
    ]
  ]
]

braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

let json: [String: Any?] = [
  "$update": [
    [
      "$identifier_key": "id",
      "$identifier_value": 4,
      "$new_object": [
        "breed": "goldfish"
      ]
    ],
    [
      "$identifier_key": "id",
      "$identifier_value": 5,
      "$new_object": [
        "name": "Annette"
      ]
    ]
  ]
]

braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

let json: [String: Any?] = [
  "$remove": [
    [
      "$identifier_key": "id",
      "$identifier_value": 1,
    ],
    [
      "$identifier_key": "id",
      "$identifier_value": 2,
    ],
    [
      "$identifier_key": "type",
      "$identifier_value": "dog",
    ]
  ]
]

braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)

1
2
3
4
5
6
7
8
9
10
11
12
13

import * as braze from "@braze/web-sdk";
const json = [{
  "id": 1,
  "type": "dog",
  "breed": "beagle",
  "name": "Gus"
}, {
  "id": 2,
  "type": "cat",
  "breed": "calico",
  "name": "Gerald"
}];
braze.getUser().setCustomUserAttribute("pets", json);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import * as braze from "@braze/web-sdk";
const json = {
  "$add": [{
    "id":  3,
    "type":  "dog",
    "breed":  "corgi",
    "name":  "Doug",
  }, {
    "id":  4,
    "type":  "fish",
    "breed":  "salmon",
    "name":  "Larry",
  }, {
    "id":  5,
    "type":  "bird",
    "breed":  "parakeet",
    "name":  "Mary",
  }]
};
braze.getUser().setCustomUserAttribute("pets", json, true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import * as braze from "@braze/web-sdk";
const json = {
  "$update": [
    {
      "$identifier_key": "id",
      "$identifier_value": 4,
      "$new_object": {
        "breed": "goldfish"
      }
    },
    {
      "$identifier_key": "id",
      "$identifier_value": 5,
      "$new_object": {
        "name": "Annette"
      }
    }
  ]
};
braze.getUser().setCustomUserAttribute("pets", json, true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import * as braze from "@braze/web-sdk";
const json = {
  "$remove": [
    {
      "$identifier_key": "id",
      "$identifier_value": 1,
    },
    {
      "$identifier_key": "id",
      "$identifier_value": 2,
    },
    {
      "$identifier_key": "type",
      "$identifier_value": "dog",
    }
  ]
};
braze.getUser().setCustomUserAttribute("pets", json, true);

Liquid テンプレート

この pets 配列を使用してメッセージをパーソナライズできます。以下の Liquid テンプレートの例は、前述の API リクエストから保存されたカスタム属性オブジェクトのプロパティを参照し、メッセージングで使用する方法を示しています。

1
2
3
4
5

{% assign pets = {{custom_attribute.${pets}}} %} 
 
{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}

このシナリオでは、Liquid を使用して pets 配列をループし、各ペットについてのステートメントを出力できます。pets カスタム属性に変数を割り当て、ドット記法を使用してオブジェクトのプロパティにアクセスします。オブジェクト名の後にピリオド . を付け、その後にプロパティ名を指定します。

セグメンテーション

オブジェクトの配列に基づいてユーザーをセグメント化する場合、配列内のいずれかのオブジェクトが条件に一致すると、そのユーザーはセグメントの対象となります。

新しいセグメントを作成し、フィルターとして階層化カスタム属性を選択します。次に、オブジェクトの配列の名前を検索して選択します。

オブジェクトの配列でフィルタリング。

ドット記法を使用して、オブジェクトの配列内のどのフィールドを使用するかを指定します。テキストフィールドの先頭に空の角括弧 [] を付けて、オブジェクトの配列内を検索していることを Braze に伝えます。その後、ピリオド . を追加し、使用するフィールド名を続けます。

たとえば、type フィールドに基づいて top_3_movies オブジェクトの配列をフィルタリングする場合は、[].type と入力し、Fantasy Movie などフィルタリングする映画を選択します。

ネストのレベル

配列のネストは1レベルまで（配列内の配列）でセグメントを作成できます。たとえば、以下の属性の場合、pets[].name に Gus が含まれるセグメントは作成できますが、pets[].nicknames[] に Gugu が含まれるセグメントは作成できません。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus",
          "nicknames": [
            "Gugu",
            "Gusto"
          ]
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald",
          "nicknames": [
            "GeGe",
            "Gerry"
          ]
        }
      ]
    }
  ]
}

データポイント

データポイントは、プロパティの作成、更新、削除のいずれを行うかによって、異なる方法で記録されます。

新しい配列を作成すると、オブジェクト内の各属性に対して1データポイントが記録されます。この例では8データポイントを消費します。各ペットオブジェクトには4つの属性があり、オブジェクトが2つあるためです。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald"
        }
      ]
    }
  ]
}

既存の配列を更新すると、追加された各プロパティに対して1データポイントが記録されます。この例では、2つのオブジェクトそれぞれで1つのプロパティのみを更新しているため、2データポイントを消費します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "pets": {
        "$update": [
          {
            "$identifier_key": "id",
            "$identifier_value": 4,
            "$new_object": {
              "breed": "goldfish"
            }
          },
          {
            "$identifier_key": "id",
            "$identifier_value": 5,
            "$new_object": {
              "name": "Annette"
            }
          }
        ]
      }
    }
  ]
}

配列からオブジェクトを削除すると、送信した各削除条件に対して1データポイントが記録されます。この例では、このステートメントで複数の犬を削除する可能性がありますが、3データポイントを消費します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": {
        "$remove": [
          // Remove by ID
          {
            "$identifier_key": "id",
            "$identifier_value": 1
          },
          {
            "$identifier_key": "id",
            "$identifier_value": 2
          },
          // Remove any dog
          {
            "$identifier_key": "type",
            "$identifier_value": "dog"
          }
        ]
      }
    }
  ]
}
New Stuff!