Nutzer:innen erstellen und aktualisieren (Bulk)

Verwenden Sie diesen Endpunkt, um angepasste Events und Käufe aufzuzeichnen und Nutzerprofilattribute in großen Mengen (Bulk) zu aktualisieren.

Wichtig

Dieser Endpunkt befindet sich derzeit in einer eingeschränkten Beta-Phase. Obwohl wir derzeit keine neuen Kund:innen zur Beta hinzufügen, lassen Sie Ihren Braze Account Manager wissen, wenn Sie glauben, dass dieses Feature für Ihre Braze-Integration nützlich sein könnte.

Wann Sie diesen Endpunkt verwenden sollten

Wie der /users/track-Endpunkt können Sie diesen Endpunkt verwenden, um Nutzerprofile zu aktualisieren. Dieser Endpunkt ist besser für Bulk-Updates geeignet:

• Größere Anfragen: Senden Sie bis zu 1.000 Nutzer:innen pro Anfrage, sodass Sie bei großen Backfills und Synchronisierungen weniger Anfragen stellen müssen.
• Priorisierung: Bei Spitzenverkehr werden Anfragen an /users/track gegenüber Anfragen an /users/track/bulk priorisiert.

Verwenden Sie diesen Endpunkt, wenn Sie während des Onboardings viele Nutzerprofile nachträglich befüllen oder große Mengen an Profilen im Rahmen einer täglichen Synchronisierung übertragen.

Hinweis

Die Limits für Anfrageobjekte des /users/track-Endpunkts variieren je nach Preismodell und Konfiguration. Verwenden Sie /users/track/bulk für die Bulk-Datenaufnahme.

Voraussetzungen

Um diesen Endpunkt zu verwenden, benötigen Sie einen API-Schlüssel mit der Berechtigung users.track.bulk.

Wenn Sie Server-zu-Server-Aufrufe hinter einer Firewall durchführen, müssen Sie möglicherweise Ihren Braze-REST-Endpunkt auf die Zulassungsliste setzen (zum Beispiel rest.iad-01.braze.com). Weitere Informationen finden Sie unter API-Endpunkte.

Rate-Limit

Hinweis

Jedes angepasste Attribut, das in einer Anfrage an /users/track/bulk gesendet wird, verbraucht einen Datenpunkt. Weitere Informationen finden Sie unter Datenpunkte.

Für die meisten Kund:innen hat dieser Endpunkt ein Basis-Geschwindigkeitslimit von 50 Anfragen pro Sekunde.

Kund:innen mit neueren Verträgen haben stattdessen möglicherweise Burst- (pro Sekunde) und Steady-Limits (pro Stunde), die auf den vertraglich vereinbarten monatlich aktiven Nutzer:innen basieren.

Jede /users/track/bulk-Anfrage hat ein Payload-Limit von 2 MB und kann insgesamt bis zu 1.000 Objekte über Attribute, Events und Käufe hinweg enthalten, abhängig von der Bulk-Rate-Limit-Richtlinie Ihres Kontos.

Jedes Objekt kann eine:n Nutzer:in aktualisieren, sodass eine einzelne Anfrage bis zum Anfrageobjekt-Limit Ihres Kontos verschiedene Nutzer:innen aktualisieren kann. Zusätzlich kann jede Anfrage maximal 100 Objekte pro Nutzerprofil über Attribute, Events und Käufe hinweg enthalten.

Anfrage-Body

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)
}

Anfrageparameter

Wichtig

Für jedes Anfrageobjekt müssen Sie eines der folgenden Felder angeben: external_id, user_alias, braze_id, email oder phone.

Beispielanfragen

Nutzerprofile per Bulk in einer Anfrage aktualisieren

Aktualisieren Sie bis zum Anfrageobjekt-Limit Ihres Kontos Nutzerprofile in einer einzigen Anfrage.

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"
      ]
    }
  ]
}'

Attribute und Events in einer Anfrage senden

Fügen Sie Attribute und Events in derselben Anfrage zusammen, bis zum kombinierten Objektlimit Ihres Kontos.

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"
          }
        ]
      }
    }
  ]
}'

Antworten

Erfolgreiche Nachricht

Erfolgreiche Nachrichten geben die folgende Antwort zurück:

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
}

Erfolgreiche Nachricht mit nicht-schwerwiegenden Fehlern

Wenn Ihre Anfrage erfolgreich ist, aber nicht-schwerwiegende Fehler enthält (zum Beispiel ein ungültiges Event-Objekt in einem großen Batch), erhalten Sie die folgende Antwort:

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

Nachricht mit schwerwiegenden Fehlern

Wenn Ihre Anfrage einen schwerwiegenden Fehler enthält, erhalten Sie die folgende Antwort:

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

Antwortcodes bei schwerwiegenden Fehlern

Informationen zu Statuscodes und zugehörigen Fehlermeldungen, die Braze zurückgibt, wenn Ihre Anfrage einen schwerwiegenden Fehler enthält, finden Sie unter Schwerwiegende Fehler und Antworten.

Wenn Sie den Fehler „provided external_id is blacklisted and disallowed“ erhalten, enthält Ihre Anfrage möglicherweise eine:n „Dummy-Nutzer:in“. Weitere Informationen finden Sie unter Spam-Blockierung.

Häufig gestellte Fragen

Sollte ich diesen Endpunkt oder /users/track verwenden?

Verwenden Sie beide Endpunkte je nach Anwendungsfall:

• Für große Backfills und Synchronisierungen verwenden Sie /users/track/bulk.
• Für Realtime-Anwendungsfälle verwenden Sie /users/track.

Welche Bezeichner kann ich in /users/track/bulk verwenden?

Geben Sie für jedes Anfrageobjekt eines der folgenden Felder an: external_id, braze_id, user_alias, email oder phone.

Kann ich Attribute, Events und Käufe in einer Anfrage zusammenfassen?

Ja. Fügen Sie eine beliebige Kombination aus Attributen, Events und Käufen hinzu, bis zum kombinierten Anfrageobjekt-Limit Ihres Kontos.