Nutzerprofile nach Segmenten exportieren

Verwenden Sie diesen Endpunkt, um alle Nutzer:innen innerhalb eines Segments zu exportieren.

Wichtig

Wenn Sie diesen Endpunkt verwenden, beachten Sie Folgendes:

1. Das Feld fields_to_export in dieser API-Anfrage ist erforderlich.
2. Die Felder für custom_events, purchases, campaigns_received und canvases_received enthalten nur Daten der letzten 90 Tage.

Nutzerdaten werden als mehrere Dateien mit JSON-Objekten exportiert, die durch Zeilenumbrüche getrennt sind (z. B. ein JSON-Objekt pro Zeile). Die Daten werden an eine automatisch generierte URL oder an einen S3-Bucket exportiert, sofern diese Integration bereits eingerichtet ist.

Wichtig

Export-Ausgabeformat: Wenn ein Export erfolgreich war und Sie keine Zugangsdaten für den Cloud-Speicher konfiguriert haben, enthält die HTTP-Antwort eine URL zum Herunterladen eines komprimierten Archivs (ZIP- oder GZIP-Datei). Wenn Cloud-Speicher-Zugangsdaten (S3, Azure oder Google Cloud Storage) konfiguriert sind, speichert Braze den Export direkt in Ihrem Bucket, und die Antwort enthält keine Download-URL. Sollte der Export fehlschlagen, erhalten Sie stattdessen eine E-Mail-Benachrichtigung. Durch die Einrichtung von Zugangsdaten für den Cloud-Speicher wird die Wahrscheinlichkeit von Fehlern bei umfangreichen Exporten verringert.

Beachten Sie, dass ein Unternehmen zu einem bestimmten Zeitpunkt höchstens einen Export pro Segment über diesen Endpunkt durchführen kann. Warten Sie, bis Ihr Export abgeschlossen ist, bevor Sie es erneut versuchen.

Voraussetzungen

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

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-, Azure- oder Google Cloud Storage-Zugangsdaten zu Braze hinzugefügt haben, wird jede Datei als ZIP-Datei in Ihren Bucket hochgeladen. Das Schlüsselformat sieht wie folgt aus: 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 erstellt Braze 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 als output_format den Wert gzip angeben, wird die Dateiendung .gz anstelle von .zip verwendet.

Wir empfehlen dringend, Ihre eigenen S3- oder Azure-Zugangsdaten einzurichten, wenn Sie diesen Endpunkt verwenden, um Ihre eigenen Bucket-Richtlinien für den Export durchzusetzen. Wenn Sie keine Cloud-Speicher-Zugangsdaten hinterlegt haben, 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 keine Cloud-Speicher-Zugangsdaten 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 mit fields_to_export fest, welche Felder Sie exportieren möchten, und geben nur die Felder an, die Sie benötigen, um den Umfang 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 unterteilen (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, sendet Braze eine POST-Anfrage an die angegebene Adresse, sobald der Download bereitsteht. Der Body des Posts lautet “success”:true. Wenn Sie keine S3-Anmeldedaten zu Braze hinzugefügt haben, enthält der Body des Posts zusätzlich das Attribut url mit der Download-URL als Wert.

Eine größere Nutzerbasis führt zu längeren Exportzeiten. 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
6
{
  "segment_id" : (required, string) identifier for the segment to be exported,
  "callback_endpoint" : (optional, string) endpoint to post a download URL when the export is available,
  "fields_to_export" : (required, array of string) name of user data fields to export, you may also export custom attributes. New accounts must specify specific fields to export,
  "output_format" : (optional, string) when using your own S3 bucket,  specifies file format as 'zip' or 'gzip'. Defaults to ZIP file format
}

Anfrageparameter

Hinweis

Wenn custom_attributes im Parameter fields_to_export enthalten ist, werden alle angepassten Attribute exportiert, unabhängig davon, was in custom_attributes_to_export steht. Wenn Sie nur bestimmte Attribute exportieren möchten, sollte custom_attributes nicht im Parameter fields_to_export enthalten sein. Verwenden Sie stattdessen den Parameter custom_attributes_to_export.

Beispielanfrage zum Export aller angepassten Attribute

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

Beispielanfrage zum Export bestimmter angepasster Attribute

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "segment_id" : "segment_identifier",
  "callback_endpoint" : "example_endpoint",
  "fields_to_export" : ["first_name", "email", "purchases"],
  "custom_attributes_to_export" : ["allergies", "favorite_food"],
  "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:

Wichtige Hinweise

• Die Felder für custom_events, purchases, campaigns_received und canvases_received enthalten nur Daten aus den letzten 90 Tagen.
• Sowohl custom_events als auch purchases enthalten Felder für first und count. Beide Felder enthalten Informationen aus dem gesamten Zeitraum und sind nicht auf Daten der letzten 90 Tage beschränkt. Wenn beispielsweise eine bestimmte Nutzer:in das Event vor mehr als 90 Tagen zum ersten Mal ausgeführt hat, wird dies im Feld first korrekt wiedergegeben, und das Feld count berücksichtigt auch Events, die vor den letzten 90 Tagen stattgefunden haben.
• Die Anzahl der gleichzeitigen Segmentexporte, die ein Unternehmen auf Endpunktebene ausführen kann, ist auf 100 begrenzt. Versuche, die diese Grenze überschreiten, führen zu einem Fehler.
• Der Versuch, ein Segment ein zweites Mal zu exportieren, während der erste Exportvorgang noch läuft, führt zu einem 429-Fehler.
• Eine 403 Forbidden-Antwort bedeutet häufig, dass die Exportdatei noch nicht bereit ist.
• Abo-Gruppendaten sind über Segmentexporte nicht verfügbar. Um Nutzer:innen nach Abo-Status zu identifizieren, erstellen Sie ein separates Segment basierend auf der Zugehörigkeit zu einer Abo-Gruppe und exportieren Sie dieses Segment.

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
}

null-URL

Wenn die Antwort "url": null enthält (oder keine Download-URL zurückgibt) und Sie eine Cloud-Speicher-Integration wie einen Amazon S3-Bucket oder einen Azure Blob Storage-Container konfiguriert haben, schreibt Braze den Export in Ihren verbundenen Bucket oder Container, anstatt eine temporäre Download-URL in der API-Antwort zurückzugeben. Rufen Sie die Dateien aus Ihrem verbundenen Cloud-Speicher-Bucket oder -Container ab.

Wenn eine Download-URL zurückgegeben wird, ist sie nur für einige Stunden gültig. Wir empfehlen Ihnen daher dringend, Ihre eigenen S3-Anmeldedaten zu Braze hinzuzufügen.

Wenn Sie in Ihrer API-Antwort object_prefix sehen, aber keine URL zum Herunterladen der Daten, bedeutet dies, dass Sie bereits einen Amazon S3-Bucket für diesen Endpunkt eingerichtet haben. Alle Daten, die über diesen Endpunkt exportiert werden, gehen direkt in Ihren S3-Bucket.

Beispiel für die Ausgabe einer Nutzerexportdatei

Nutzerexportobjekt (Braze enthält so wenig Daten wie möglich—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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
{
    "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),
    "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "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" : (boolean)
      },
      ...
    ],
    "push_tokens" : [
      {
        "app" : (string) app name,
        "platform" : (string),
        "token" : (string),
        "device_id": (string),
        "notifications_enabled": (boolean) whether foreground push notifications are enabled for this token. `true` means foreground push is enabled for the token, and `false` means foreground push is disabled (for example, background-only). This is device-level and doesn't indicate the user's global push subscription status,
        "provisionally_opted_in": (boolean) included for iOS and Android tokens only. Indicates whether the token is in a provisional push authorization state. `true` means the token is provisionally opted in (notifications are delivered quietly), `false` means the token isn't provisional (the user has explicitly authorized or denied push), and `null` means provisional status isn't set. Provisional authorization applies to iOS; Android tokens report `null`
      },
      ...
    ],
    "apps" : [
      {
        "name" : (string),
        "platform" : (string),
        "version" : (string),
        "sessions" : (integer),
        "first_used" : (string) date,
        "last_used" : (string) date
      },
      ...
    ],
    "campaigns_received" : [
      {
        "name" : (string),
        "last_received" : (string) date,
        "engaged" :
         {
           "opened_email" : (boolean),
           "opened_push" : (boolean),
           "clicked_email" : (boolean),
           "clicked_triggered_in_app_message" : (boolean)
          },
          "converted" : (boolean),
          "api_campaign_id" : (string),
          "variation_name" : (optional, string) exists only if it is a multivariate campaign,
          "variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
          "in_control" : (optional, boolean) exists only if it is a multivariate campaign
        },
      ...
    ],
    "canvases_received": [
      {
        "name": (string),
        "api_canvas_id": (string),
        "last_received_message": (string) date,
        "last_entered": (string) date,
        "variation_name": (string),
        "in_control": (boolean),
        "last_exited": (string) date,
        "steps_received": [
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          },
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          },
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          }
        ]
      },
      ...
    ],
    "cards_clicked" : [
      {
        "name" : (string)
      },
      ...
    ]
}

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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
{
    "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",
    "push_subscribe" : "opted_in",
    "push_opted_in_at": "2020-01-26T22:45:53.953Z",
    "email_subscribe" : "subscribed",
    "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
      },
      ...
    ],
    "push_tokens": [
      {
        "app": "MovieCanon",
        "platform": "Android",
        "token": "12345abcd",
        "device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
        "notifications_enabled": true,
        "provisionally_opted_in": null
      },
      ...
    ],
    "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"
      },
      ...
    ],
    "campaigns_received": [
      {
        "name": "Email Unsubscribe",
        "api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942",
        "last_received": "2022-06-02T03:07:38.105Z",
        "engaged":
        {
           "opened_email": true
        },
        "converted": true,
        "multiple_converted":
        {
          "Primary Conversion Event - A": true
        },
        "in_control": false,
        "variation_name": "Variant 1",
        "variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8"
      },
      ...
    ],
    "canvases_received": [
      {
        "name": "Non Global  Holdout Group 4/21/21",
        "api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781",
        "last_received_message": "2021-07-07T20:46:24.136Z",
        "last_entered": "2021-07-07T20:45:24.000+00:00",
        "variation_name": "Variant 1",
        "in_control": false,
        "last_entered_control_at": null,
        "last_exited": "2021-07-07T20:46:24.136Z",
        "steps_received": [
          {
            "name": "Step",
            "api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39",
            "last_received": "2021-07-07T20:46:24.136Z"
          },
          ...
        ]
      }
      ...
    ],
    "cards_clicked" : [
      {
        "name" : "Loyalty Promo"
      },
      ...
    ]
}

Tipp

Hilfe zu CSV- und API-Exporten finden Sie unter Fehlerbehebung bei Exporten.