Exportar perfil de usuário por segmento

Use esse endpoint para exportar todos os usuários de um segmento.

Importante

Ao usar esse endpoint, observe o seguinte:

1. O campo fields_to_export nessa solicitação da API é obrigatório.
2. Os campos para custom_events, purchases, campaigns_received e canvases_received contêm apenas dados dos últimos 90 dias.

Os dados de usuários são exportados como vários arquivos de objetos JSON de usuários separados por novas linhas (como um objeto JSON por linha). Os dados são exportados para uma URL gerada automaticamente ou para um bucket S3 se essa integração já estiver configurada.

Importante

Formato de saída da exportação: Quando uma exportação é bem-sucedida e você não configurou credenciais de armazenamento em nuvem, a resposta HTTP inclui uma URL para baixar um arquivo compactado (arquivo ZIP ou GZIP). Quando as credenciais de armazenamento em nuvem (S3, Azure ou Google Cloud Storage) estão configuradas, a Braze escreve a exportação diretamente no seu bucket, e a resposta não inclui uma URL de download. Se a exportação falhar, você receberá uma notificação por e-mail. Configurar credenciais de armazenamento em nuvem reduz a probabilidade de falhas em grandes exportações.

Note que uma empresa pode executar no máximo uma exportação por segmento usando esse endpoint em um determinado momento. Aguarde a conclusão da exportação antes de tentar novamente.

Pré-requisitos

Para usar esse endpoint, você precisará de uma chave de API com a permissão users.export.segment.

Limite de taxa

Aplicamos o limite de taxa padrão da Braze de 250.000 solicitações por hora a esse endpoint, conforme documentado em Limites de taxa da API.

Detalhes de resposta baseados em credenciais

Se você adicionou suas credenciais de S3, Azure ou Google Cloud Storage à Braze, cada arquivo é enviado para o seu bucket como um arquivo ZIP com o formato de chave semelhante a segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip. Se estiver usando o Azure, certifique-se de que a caixa Tornar este o destino padrão de exportação de dados esteja marcada na página de visão geral do parceiro do Azure na Braze. Geralmente, a Braze cria 1 arquivo para cada 5.000 usuários para otimizar o processamento. A exportação de segmentos menores em um espaço de trabalho grande pode resultar em vários arquivos. Em seguida, você pode extrair os arquivos e concatenar todos os arquivos json em um único arquivo, se necessário. Se você especificar um output_format de gzip, a extensão do arquivo será .gz em vez de .zip.

É altamente recomendável configurar suas próprias credenciais do S3 ou do Azure ao usar esse endpoint para aplicar suas próprias políticas de bucket na exportação. Se não tiver suas credenciais de armazenamento em nuvem, a resposta à solicitação fornecerá a URL onde um arquivo ZIP contendo todos os arquivos do usuário pode ser baixado. A URL se torna um local válido apenas depois que a exportação está pronta.

Esteja ciente de que, se você não fornecer suas credenciais de armazenamento em nuvem, há uma limitação na quantidade de dados que você pode exportar desse endpoint. Dependendo dos campos que você está exportando e do número de usuários, a transferência do arquivo pode falhar se ele for muito grande. Uma prática recomendada é especificar quais campos você deseja exportar usando fields_to_export e especificar apenas os campos necessários para manter o tamanho da transferência menor. Se você estiver recebendo erros ao gerar o arquivo, considere dividir sua base de usuários em mais segmentos com base em um número de bucket aleatório (por exemplo, crie um segmento em que um número de bucket aleatório seja menor que 1.000 ou entre 1.000 e 2.000).

Em qualquer um dos cenários, você tem a opção de fornecer um callback_endpoint para receber uma notificação quando a exportação estiver pronta. Se o callback_endpoint for fornecido, a Braze faz uma solicitação POST para o endereço fornecido quando o download estiver pronto. O corpo do POST é “success”:true. Se você não adicionou credenciais S3 à Braze, o corpo do POST terá adicionalmente o atributo url com a URL de download como valor.

Bases de usuários maiores resultam em tempos de exportação mais longos. Por exemplo, um app com 20 milhões de usuários pode levar uma hora ou mais.

Corpo da solicitação

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
}

Parâmetros de solicitação

Nota

Se custom_attributes estiver incluído no parâmetro fields_to_export, todos os atributos personalizados serão exportados, independentemente do que estiver em custom_attributes_to_export. Se seu objetivo for exportar atributos específicos, custom_attributes não deve ser incluído no parâmetro fields_to_export. Em vez disso, use o parâmetro custom_attributes_to_export.

Exemplo de solicitação para exportar todos os atributos personalizados

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

Exemplo de solicitação para exportar atributos personalizados específicos

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

Campos a serem exportados

A seguir, uma lista de fields_to_export válidos. O uso de fields_to_export para minimizar os dados retornados pode melhorar o tempo de resposta desse endpoint da API:

Lembretes importantes

• Os campos para custom_events, purchases, campaigns_received e canvases_received contêm apenas dados dos últimos 90 dias.
• Tanto custom_events quanto purchases contêm campos para first e count. Ambos os campos refletem informações de todo o período e não estão limitados aos dados dos últimos 90 dias. Por exemplo, se um usuário específico realizou o evento pela primeira vez há 90 dias, isso é refletido com precisão no campo first, e o campo count leva em conta eventos que ocorreram antes dos últimos 90 dias também.
• O número de exportações de segmentos simultâneas que uma empresa pode executar no nível do endpoint é limitado a 100. Tentativas que ultrapassam esse limite resultam em um erro.
• Tentar exportar um segmento uma segunda vez enquanto o primeiro trabalho de exportação ainda está em execução resulta em um erro 429.
• Uma resposta 403 Forbidden geralmente significa que o arquivo de exportação ainda não está pronto.

Resposta

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

Se a resposta incluir "url": null (ou omitir uma URL de download) e você tiver configurado uma integração de armazenamento em nuvem como um bucket Amazon S3 ou um contêiner Azure Blob Storage, a Braze escreve a exportação no seu bucket ou contêiner conectado em vez de retornar uma URL de download temporária na resposta da API. Recupere os arquivos do seu bucket ou contêiner de armazenamento em nuvem conectado.

Se uma URL de download for retornada, ela é válida apenas por algumas horas. Portanto, é altamente recomendável que você adicione suas próprias credenciais S3 à Braze.

Se você vir object_prefix na sua resposta da API e nenhuma URL para baixar os dados, isso significa que você já tem um bucket Amazon S3 configurado para esse endpoint. Qualquer dado exportado usando esse endpoint vai diretamente para o seu bucket S3.

Exemplo de saída de arquivo de exportação do usuário

Objeto de exportação do usuário (a Braze inclui o menor número possível de dados—se um campo estiver ausente do objeto, deve-se assumir que é nulo ou vazio):

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

Dica

Para obter ajuda com exportações de CSV e API, acesse Resolução de problemas de exportação.