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. O Braze não armazena um histórico de quando os usuários são adicionados e removidos de um Grupo de Controle Global.

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

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

Detalhes de resposta baseados em credenciais

Se você adicionou suas credenciais do S3 ou do Azure à Braze, cada arquivo terá o upload no 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 no Braze. Em geral, 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.

É 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 fornecido suas credenciais de armazenamento em nuvem, a resposta à solicitação fornecerá o URL onde um ZIP contendo todos os arquivos do usuário pode ser baixado. O URL só se tornará um local válido depois que a exportação estiver 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 especificando 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 intervalo aleatório (por exemplo, crie um segmento em que o número de intervalo 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 endereço callback_endpoint for fornecido, faremos uma solicitação de postagem para o endereço fornecido quando o download estiver pronto. O corpo da postagem será “success”:true. Se você não tiver adicionado suas credenciais de armazenamento em nuvem ao Braze, o corpo da postagem também terá a atribuição url com o 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
}

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. O uso do site fields_to_export para minimizar os dados retornados pode melhorar o tempo de resposta desse endpoint da API:

Resposta

1
2
3
4
5
6
7
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "object_prefix": (required, string) the filename prefix that will be 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 for disponibilizada, ela só será válida por 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 do usuário (incluiremos o mínimo de dados possível - se um campo estiver faltando no objeto, ele deverá ser considerado nulo, falso ou vazio):

• todos os campos
• saída de amostra

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" : "example@braze.com",
    "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"
      },
      ...
    ],
}