Exportar perfil de usuário por Grupo de Controle Global

Use esse endpoint para exportar todos os usuários de um Grupo de Controle Global.

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). Todos os usuários de um Grupo de Controle Global são incluídos sempre que os arquivos são gerados. A Braze não armazena um histórico de quando os usuários são adicionados e removidos de um Grupo de Controle Global.

Para localizar o identificador do segmento do seu Grupo de Controle Global, consulte Tipos de identificadores de API.

Pré-requisitos

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

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 ou Azure à Braze por meio da respectiva página de Parceiros de Tecnologia, 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, criamos um 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.

Recomendamos fortemente configurar suas próprias credenciais de S3 ou Azure (acessando Integrações de Parceiros > Parceiros de Tecnologia > página do parceiro) ao usar esse endpoint para aplicar suas próprias políticas de bucket na exportação.

Se você não tiver fornecido suas credenciais de armazenamento em nuvem, a resposta à solicitação fornecerá a URL onde um ZIP contendo todos os arquivos do usuário pode ser baixado. A URL se torna um local válido apenas após a exportação estar pronta.

Esteja ciente de que, se você não fornecer suas credenciais de armazenamento em nuvem, haverá 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 incluindo 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 o 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ê pode opcionalmente fornecer um callback_endpoint para receber uma notificação quando a exportação estiver pronta. Se o callback_endpoint for fornecido, fazemos 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 suas credenciais de armazenamento em nuvem à Braze, o corpo do post adicionalmente terá o atributo url com a URL de download como valor.

Bases de usuários maiores resultarão 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
{
  "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
}

Aviso

Atributos personalizados individuais não podem ser exportados. No entanto, todos os atributos personalizados podem ser exportados incluindo custom_attributes no array fields_to_export (por exemplo, ['first_name', 'email', 'custom_attributes']).

Parâmetros de solicitação

Exemplo de solicitação

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

Campos a serem exportados

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

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
}

Depois que a URL estiver disponível, ela será válida por apenas algumas horas. Portanto, é altamente recomendável que você adicione suas próprias credenciais S3 à Braze.

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

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

• todos os campos
• exemplo de saída

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