Créer et mettre à jour des utilisateurs (en masse)

Utilisez cet endpoint pour enregistrer des événements personnalisés et des achats, et mettre à jour les attributs de profils utilisateur en masse.

Quand utiliser cet endpoint

Comme l’endpoint /users/track, vous pouvez utiliser cet endpoint pour mettre à jour les profils utilisateur. Cet endpoint est mieux adapté aux mises à jour en masse :

• Requêtes plus volumineuses : Envoyez jusqu’à 1 000 utilisateurs par requête, ce qui vous permet de faire moins de requêtes pour les remplissages et synchronisations importants.
• Priorisation : En cas de pic de trafic, les requêtes vers /users/track sont prioritaires par rapport aux requêtes vers /users/track/bulk.

Utilisez cet endpoint lorsque vous remplissez de nombreux profils utilisateur lors de l’onboarding, ou que vous synchronisez de grands volumes de profils dans le cadre d’une synchronisation quotidienne.

Conditions préalables

Pour utiliser cet endpoint, vous devez disposer d’une clé API avec la permission users.track.bulk.

Si vous effectuez des appels serveur à serveur derrière un pare-feu, vous devrez peut-être ajouter votre endpoint REST Braze à votre liste d’autorisation (par exemple, rest.iad-01.braze.com). Pour plus d’informations, consultez Endpoints API.

Limite de débit

Pour la plupart des clients, cet endpoint a une limite de vitesse de base de 50 requêtes par seconde.

Les clients disposant de contrats plus récents peuvent avoir des limites en rafale (par seconde) et régulières (par heure) basées sur le nombre d’utilisateurs actifs par mois contractualisé.

Chaque requête /users/track/bulk a une limite de payload de 2 Mo et peut inclure jusqu’à 1 000 objets au total entre les attributs, les événements et les achats, en fonction de la politique de limite de débit en masse de votre compte.

Chaque objet peut mettre à jour un utilisateur, de sorte qu’une seule requête peut mettre à jour jusqu’à la limite d’objets de requête de votre compte pour différents utilisateurs. De plus, chaque requête peut contenir un maximum de 100 objets par profil utilisateur entre les attributs, les événements et les achats.

Corps de la requête

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object)
}

Paramètres de la requête

Exemples de requêtes

Mettre à jour des profils utilisateur en masse dans une seule requête

Mettez à jour jusqu’à la limite d’objets de requête de votre compte de profils utilisateur en une seule requête.

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
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    },
    {
      "external_id": "user2",
      "string_attribute": "vegetables",
      "boolean_attribute_1": false,
      "integer_attribute": 25,
      "array_attribute": [
        "broccoli",
        "asparagus"
      ]
    }
  ]
}'

Envoyer des attributs et des événements dans une seule requête

Incluez des attributs et des événements dans la même requête, jusqu’à la limite totale d’objets de votre compte.

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
30
31
32
33
34
35
36
37
38
39
curl --location --request POST 'https://rest.iad-01.braze.com/users/track/bulk' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
    {
      "external_id": "user1",
      "string_attribute": "fruit",
      "boolean_attribute_1": true,
      "integer_attribute": 25,
      "array_attribute": [
        "banana",
        "apple"
      ]
    }
  ],
  "events": [
    {
      "external_id": "user2",
      "app_id": "your_app_identifier",
      "name": "rented_movie",
      "time": "2022-12-06T19:20:45+01:00",
      "properties": {
        "release": {
          "studio": "FilmStudio",
          "year": "2022"
        },
        "cast": [
          {
            "name": "Actor1"
          },
          {
            "name": "Actor2"
          }
        ]
      }
    }
  ]
}'

Réponses

Message de réussite

Les messages de réussite renvoient la réponse suivante :

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this returns an integer of the number of external IDs with attributes that Braze queued for processing,
  "events_processed": (optional, integer), if events are included in the request, this returns an integer of the number of events that Braze queued for processing,
  "purchases_processed": (optional, integer), if purchases are included in the request, this returns an integer of the number of purchases that Braze queued for processing
}

Message de réussite avec des erreurs non fatales

Si votre requête aboutit mais comporte des erreurs non fatales (par exemple, un objet d’événement invalide dans un lot volumineux), vous recevez la réponse suivante :

1
2
3
4
5
6
7
8
{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

Message avec des erreurs fatales

Si votre requête comporte une erreur fatale, vous recevez la réponse suivante :

1
2
3
4
5
6
7
8
{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Codes de réponse pour les erreurs fatales

Pour les codes d’état et les messages d’erreur associés que Braze renvoie lorsque votre requête comporte une erreur fatale, consultez Erreurs fatales et réponses.

Si vous recevez l’erreur « provided external_id is blacklisted and disallowed », votre requête peut inclure un « utilisateur fictif ». Pour plus d’informations, consultez Blocage du spam.

Questions fréquemment posées

Dois-je utiliser cet endpoint ou /users/track ?

Utilisez les deux endpoints en fonction de votre cas d’utilisation :

• Pour les remplissages et synchronisations volumineux, utilisez /users/track/bulk.
• Pour les cas d’utilisation en temps réel, utilisez /users/track.

Quels identifiants puis-je utiliser dans /users/track/bulk ?

Pour chaque objet de requête, incluez l’un des éléments suivants : external_id, braze_id, user_alias, email ou phone.

Puis-je inclure des attributs, des événements et des achats dans une seule requête ?

Oui. Incluez n’importe quelle combinaison d’attributs, d’événements et d’achats, jusqu’à la limite combinée d’objets de requête de votre compte.