Nutzerprofil nach globaler Kontrollgruppe exportieren

Verwenden Sie diesen Endpunkt, um alle Nutzer:innen innerhalb einer globalen Kontrollgruppe zu exportieren.

Nutzerdaten werden als mehrere Dateien mit JSON-Objekten für Nutzer:innen exportiert, die durch Zeilenumbrüche getrennt sind (z. B. ein JSON-Objekt pro Zeile). Alle Nutzer:innen einer globalen Kontrollgruppe werden bei jeder Generierung der Dateien berücksichtigt. Braze speichert keinen Verlauf darüber, wann Nutzer:innen zu einer globalen Kontrollgruppe hinzugefügt oder aus ihr entfernt werden.

Um den Segment-Bezeichner Ihrer globalen Kontrollgruppe zu ermitteln, lesen Sie API-Bezeichnertypen.

Voraussetzungen

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

Rate-Limit

Wir wenden auf diesen Endpunkt das standardmäßige Braze-Rate-Limit von 250.000 Anfragen pro Stunde an, wie in API-Rate-Limits dokumentiert.

Auf Zugangsdaten basierende Antwortdetails

Wenn Sie Ihre S3- oder Azure-Zugangsdaten über die entsprechende Technologie-Partner-Seite zu Braze hinzugefügt haben, wird jede Datei in Ihrem Bucket als ZIP-Datei mit dem folgenden Schlüsselformat hochgeladen: segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip. Wenn Sie Azure verwenden, vergewissern Sie sich, dass Sie auf der Übersichtsseite für Azure-Partner in Braze das Kontrollkästchen Make this the default data export destination aktiviert haben.

Im Allgemeinen erstellen wir eine Datei pro 5.000 Nutzer:innen, um die Verarbeitung zu optimieren. Das Exportieren kleinerer Segmente innerhalb eines großen Workspace kann zu mehreren Dateien führen. Sie können dann die Dateien extrahieren und bei Bedarf alle json-Dateien zu einer einzigen Datei zusammenfügen. Wenn Sie ein output_format von gzip angeben, wird die Dateiendung .gz anstelle von .zip verwendet.

Wir empfehlen Ihnen dringend, Ihre eigenen S3- oder Azure-Zugangsdaten einzurichten (unter Partnerintegrationen > Technologie-Partner > Partnerseite), wenn Sie diesen Endpunkt verwenden, um Ihre eigenen Bucket-Richtlinien für den Export durchzusetzen.

Wenn Sie Ihre Zugangsdaten für den Cloud-Speicher nicht angeben, enthält die Antwort auf die Anfrage die URL, unter der eine ZIP-Datei mit allen Nutzerdateien heruntergeladen werden kann. Die URL wird erst nach Abschluss des Exports zu einem gültigen Speicherort.

Beachten Sie, dass die Menge der Daten, die Sie von diesem Endpunkt exportieren können, begrenzt ist, wenn Sie Ihre Zugangsdaten für den Cloud-Speicher nicht angeben. Je nach den Feldern, die Sie exportieren, und der Anzahl der Nutzer:innen kann die Dateiübertragung fehlschlagen, wenn sie zu groß ist. Am besten legen Sie fest, welche Felder Sie exportieren möchten, indem Sie fields_to_export verwenden und nur die Felder angeben, die Sie benötigen, um die Größe der Übertragung gering zu halten. Wenn Sie bei der Generierung der Datei Fehler erhalten, sollten Sie Ihre Nutzerbasis auf der Grundlage einer zufälligen Bucket-Nummer in mehrere Segmente aufteilen (z. B. ein Segment erstellen, bei dem die zufällige Bucket-Nummer kleiner als 1.000 oder zwischen 1.000 und 2.000 ist).

In beiden Szenarien können Sie optional einen callback_endpoint angeben, um benachrichtigt zu werden, wenn der Export fertig ist. Wenn der callback_endpoint angegeben ist, senden wir eine POST-Anfrage an die angegebene Adresse, sobald der Download bereitsteht. Der Text der Anfrage lautet "success":true. Falls Sie Ihre Cloud-Speicher-Zugangsdaten noch nicht zu Braze hinzugefügt haben, enthält der Text der Anfrage zusätzlich das Attribut url mit der Download-URL als Wert.

Größere Nutzermengen haben längere Exportzeiten zur Folge. Eine App mit 20 Millionen Nutzer:innen könnte zum Beispiel eine Stunde oder länger dauern.

Anfragetext

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
4
5
{
  "callback_endpoint" : (optional, string) endpoint to post a download URL to when the export is available,
  "fields_to_export" : (required, array of string) name of user data fields to export, for example, ['first_name', 'email', 'purchases'],
  "output_format" : (optional, string) When using your own S3 bucket, allows to specify file format as 'zip' or 'gzip'. Defaults to zip file format
}

Warnung

Individuelle angepasste Attribute können nicht exportiert werden. Allerdings können alle angepassten Attribute exportiert werden, indem custom_attributes in das fields_to_export-Array aufgenommen wird (zum Beispiel ['first_name', 'email', 'custom_attributes']).

Anfrageparameter

Beispielanfrage

1
2
3
4
5
6
7
8
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/global_control_group' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "callback_endpoint" : "",
  "fields_to_export" : ["email", "braze_id"],
  "output_format" : "zip"
}'

Zu exportierende Felder

Im Folgenden finden Sie eine Liste der gültigen fields_to_export. Die Verwendung von fields_to_export zur Minimierung der zurückgegebenen Daten kann die Antwortzeit dieses API-Endpunkts verbessern:

Antwort

1
2
3
4
5
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "object_prefix": (required, string) the filename prefix that is used for the JSON file produced by this export, for example,'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
    "url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials
}

Nachdem die URL bereitgestellt wurde, ist sie nur für einige Stunden gültig. Wir empfehlen Ihnen daher dringend, Ihre eigenen S3-Zugangsdaten zu Braze hinzuzufügen.

Beispiel für die Ausgabe einer Nutzerexportdatei

Nutzerexportobjekt (wir geben so wenig Daten wie möglich an – wenn ein Feld im Objekt fehlt, sollte davon ausgegangen werden, dass es null oder leer ist):

• all fields
• sample output

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
    "created_at" : (string),
    "external_id" : (string),
    "user_aliases" : [
      {
        "alias_name" : (string),
        "alias_label" : (string)
      }
    ],
    "braze_id": (string),
    "first_name" : (string),
    "last_name" : (string),
    "email" : (string),
    "dob" : (string) date for the user's date of birth,
    "home_city" : (string),
    "country" : (string) ISO-3166-1 alpha-2 standard,
    "phone" : (string),
    "language" : (string) ISO-639-1 standard,
    "time_zone" : (string),
    "last_coordinates" : (array of float) [lon, lat],
    "gender" : (string) "M" | "F",
    "total_revenue" : (float),
    "attributed_campaign" : (string),
    "attributed_source" : (string),
    "attributed_adgroup" : (string),
    "attributed_ad" : (string),
    "custom_attributes" : (object) custom attribute key-value pairs,
    "custom_events" : [
      {
        "name" : (string),
        "first" : (string) date,
        "last" : (string) date,
        "count" : (int)
      },
      ...
    ],
    "purchases" : [
      {
        "name" : (string),
        "first" : (string) date,
        "last" : (string) date,
         "count" : (int)
      },
      ...
    ],
    "devices" : [
      {
        "model" : (string),
        "os" : (string),
        "carrier" : (string),
        "idfv" : (string) only included for iOS devices when IDFV collection is enabled,
        "idfa" : (string) only included for iOS devices when IDFA collection is enabled,
        "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,
        "roku_ad_id" : (string) only included for Roku devices,
        "ad_tracking_enabled" : (bool)
      },
      ...
    ],
    "apps" : [
      {
        "name" : (string),
        "platform" : (string),
        "version" : (string),
        "sessions" : (string),
        "first_used" : (string) date,
        "last_used" : (string) date
      },
      ...
    ]
}

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
{
    "created_at" : "2020-07-10 15:00:00.000 UTC",
    "external_id" : "A8i3mkd99",
    "user_aliases" : [
      {
        "alias_name" : "user_123",
        "alias_label" : "amplitude_id"
      }
    ],
    "braze_id": "5fbd99bac125ca40511f2cb1",
    "random_bucket" : 2365,
    "first_name" : "Jane",
    "last_name" : "Doe",
    "email" : "[email protected]",
    "dob" : "1980-12-21",
    "home_city" : "Chicago",
    "country" : "US",
    "phone" : "+442071838750",
    "language" : "en",
    "time_zone" : "Eastern Time (US & Canada)",
    "last_coordinates" : [41.84157636433568, -87.83520818508256],
    "gender" : "F",
    "total_revenue" : 65,
    "attributed_campaign" : "braze_test_campaign_072219",
    "attributed_source" : "braze_test_source_072219",
    "attributed_adgroup" : "braze_test_adgroup_072219",
    "attributed_ad" : "braze_test_ad_072219",
    "custom_attributes":
      {
        "loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856",
        "loyaltyPoints": "321",
        "loyaltyPointsNumber": 107
      },
    "custom_events": [
      {
          "name": "Loyalty Acknowledgement",
          "first": "2021-06-28T17:02:43.032Z",
          "last": "2021-06-28T17:02:43.032Z",
          "count": 1
      },
      ...
    ],
    "purchases": [
      {
        "name": "item_40834",
        "first": "2021-09-05T03:45:50.540Z",
        "last": "2022-06-03T17:30:41.201Z",
        "count": 10
      },
      ...
    ],
    "devices": [
      {
        "model": "Pixel XL",
        "os": "Android (Q)",
        "carrier": null,
        "device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
        "ad_tracking_enabled": true
      },
      ...
    ],
    "apps": [
      {
        "name": "MovieCannon",
        "platform": "Android",
        "version": "3.29.0",
        "sessions": 1129,
        "first_used": "2020-02-02T19:56:19.142Z",
        "last_used": "2021-11-11T00:25:19.201Z"
      },
      ...
    ]
}