Exporter le profil utilisateur par segment

Utilisez cet endpoint pour exporter tous les utilisateurs d’un segment.

Important

Lors de l’utilisation de cet endpoint, notez les points suivants :

1. Le champ fields_to_export de cette requête API est obligatoire.
2. Les champs custom_events, purchases, campaigns_received et canvases_received contiennent uniquement les données des 90 derniers jours.

Les données des utilisateurs sont exportées sous la forme de plusieurs fichiers d’objets JSON séparés par des retours à la ligne (un objet JSON par ligne). Les données sont exportées vers une URL générée automatiquement ou vers un compartiment S3 si cette intégration est déjà configurée.

Important

Format de sortie de l’exportation : Lorsqu’une exportation réussit et que vous n’avez pas configuré d’identifiants de stockage cloud, la réponse HTTP inclut une URL permettant de télécharger une archive compressée (fichier ZIP ou GZIP). Lorsque des identifiants de stockage cloud (S3, Azure ou Google Cloud Storage) sont configurés, Braze enregistre l’exportation directement dans votre compartiment, et la réponse ne comprend pas d’URL de téléchargement. Si l’exportation échoue, vous recevez une notification par e-mail. La configuration d’identifiants de stockage cloud réduit le risque d’échec lors d’exportations volumineuses.

Notez qu’une entreprise ne peut exécuter qu’une seule exportation par segment à l’aide de cet endpoint à un moment donné. Attendez la fin de l’exportation avant de réessayer.

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.export.segment.

Limite de débit

La limite de débit par défaut de Braze de 250 000 requêtes par heure s’applique à cet endpoint, comme documenté dans Limites de débit de l’API.

Informations relatives à la réponse basée sur les identifiants

Si vous avez ajouté vos identifiants S3, Azure ou Google Cloud Storage à Braze, chaque fichier est téléchargé dans votre compartiment sous forme de fichier ZIP avec un format de clé similaire à segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip. Si vous utilisez Azure, assurez-vous que la case Make this the default data export destination est cochée dans la page d’aperçu du partenaire Azure dans Braze. En règle générale, Braze crée un fichier pour chaque groupe de 5 000 utilisateurs afin d’optimiser le traitement. L’exportation de segments plus petits au sein d’un grand espace de travail peut donner lieu à plusieurs fichiers. Vous pouvez alors décompresser les fichiers et concaténer tous les fichiers json en un seul fichier si nécessaire. Si vous spécifiez une valeur output_format de gzip, l’extension du fichier sera .gz au lieu de .zip.

Nous vous conseillons vivement de configurer vos propres identifiants S3 ou Azure lorsque vous utilisez cet endpoint afin d’appliquer vos propres politiques de compartiment sur l’exportation. Si vous n’avez pas configuré vos identifiants de stockage cloud, la réponse à la requête fournit l’URL où un fichier ZIP contenant tous les fichiers utilisateur peut être téléchargé. L’URL ne devient valide qu’une fois l’exportation terminée.

Sachez que si vous ne fournissez pas vos identifiants de stockage cloud, la quantité de données exportables depuis cet endpoint est limitée. En fonction des champs exportés et du nombre d’utilisateurs, le transfert de fichiers peut échouer si la quantité de données demandées est trop importante. Une bonne pratique consiste à spécifier les champs que vous souhaitez exporter à l’aide de fields_to_export et à ne préciser que les champs dont vous avez besoin afin de réduire la taille du transfert. Si vous obtenez des erreurs lors de la génération du fichier, envisagez de diviser votre base d’utilisateurs en plusieurs segments sur la base d’un numéro de compartiment aléatoire (par exemple, créez un segment dans lequel le numéro de compartiment aléatoire est inférieur à 1 000 ou compris entre 1 000 et 2 000).

Dans les deux cas, vous pouvez éventuellement fournir un callback_endpoint pour être notifié lorsque l’exportation est prête. Si le callback_endpoint est fourni, Braze envoie une requête POST à l’adresse indiquée lorsque le téléchargement est prêt. Le corps du message est “success”:true. Si vous n’avez pas ajouté d’identifiants S3 à Braze, le corps du message comporte également l’attribut url avec l’URL de téléchargement comme valeur.

Une base d’utilisateurs plus importante entraîne des délais d’exportation plus longs. Par exemple, une application avec 20 millions d’utilisateurs peut prendre une heure ou plus.

Corps de la requête

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
}

Paramètres de requête

Remarque

Si custom_attributes est inclus dans le paramètre fields_to_export, tous les attributs personnalisés sont exportés, quel que soit le contenu de custom_attributes_to_export. Si votre objectif est d’exporter des attributs spécifiques, custom_attributes ne doit pas être inclus dans le paramètre fields_to_export. Utilisez plutôt le paramètre custom_attributes_to_export.

Exemple de requête pour exporter tous les attributs personnalisés

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

Exemple de requête pour exporter des attributs personnalisés spécifiques

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

Champs à exporter

Voici la liste des valeurs valides pour fields_to_export. Utiliser fields_to_export pour limiter les données renvoyées peut améliorer le temps de réponse de cet endpoint API :

Rappels importants

• Les champs custom_events, purchases, campaigns_received et canvases_received contiennent uniquement les données des 90 derniers jours.
• custom_events et purchases contiennent tous les deux des champs first et count. Ces deux champs reflètent les informations de toutes les périodes et ne se limitent pas aux données des 90 derniers jours. Par exemple, si un utilisateur a déclenché l’événement pour la première fois il y a plus de 90 jours, cela est reflété avec précision dans le champ first, et le champ count prend également en compte les événements survenus avant les 90 derniers jours.
• Le nombre d’exportations de segments simultanées qu’une entreprise peut exécuter au niveau de l’endpoint est plafonné à 100. Toute tentative dépassant cette limite entraîne une erreur.
• Tenter d’exporter un segment une seconde fois alors que la première tâche d’exportation est toujours en cours entraîne une erreur 429.
• Une réponse 403 Forbidden signifie souvent que le fichier d’exportation n’est pas encore prêt.

Réponse

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
}

URL null

Si la réponse inclut "url": null (ou omet une URL de téléchargement) et que vous avez configuré une intégration de stockage cloud telle qu’un compartiment Amazon S3 ou un conteneur Azure Blob Storage, Braze enregistre l’exportation dans votre compartiment ou conteneur connecté au lieu de renvoyer une URL de téléchargement temporaire dans la réponse API. Récupérez les fichiers depuis votre compartiment ou conteneur de stockage cloud connecté.

Si une URL de téléchargement est renvoyée, elle n’est valide que pendant quelques heures. Nous vous recommandons donc fortement d’ajouter vos propres identifiants S3 à Braze.

Si vous observez object_prefix dans votre réponse API sans URL de téléchargement, cela signifie qu’un compartiment Amazon S3 est déjà configuré pour cet endpoint. Toutes les données exportées via cet endpoint sont directement transférées vers votre compartiment S3.

Exemple de sortie d’un fichier d’exportation utilisateur

Objet d’exportation utilisateur (Braze inclut le moins de données possible—si un champ est absent de l’objet, il doit être considéré comme nul ou vide) :

• 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
{
    "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
      },
      ...
    ],
    "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
{
    "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
      },
      ...
    ],
    "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"
      },
      ...
    ]
}

Conseil

Pour obtenir de l’aide sur les exportations CSV et API, consultez la section Résolution des problèmes d’exportation.