Skip to content

オブジェクト配列

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

サポートされるデータ型

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

考慮事項

  • オブジェクトの配列は、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カスタム属性に変数を割り当て、ドット記法を使用してオブジェクトのプロパティにアクセスします。オブジェクト名の後にピリオド.を付け、その後にプロパティ名を指定します。

セグメンテーション

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

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

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

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

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

ネストのレベル

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

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!