Serviço de consulta (Data Distiller) e conjuntos de dados de exportação

Este artigo descreve como a combinação do Experience Platform Query Service (Data Distiller) e a exportação do conjunto de dados podem ser usadas para implementar os seguintes casos de uso de exportação de dados:

A Adobe Analytics pode implementar esses casos de uso usando sua funcionalidade Feeds de dados. Os feeds de dados são uma maneira avançada de obter dados brutos do Adobe Analytics. Este artigo descreve como obter tipo semelhante de dados brutos do Experience Platform, para que você possa implementar os casos de uso mencionados acima. Quando aplicável, as funcionalidades descritas neste artigo são comparadas com os feeds de dados do Adobe Analytics para esclarecer diferenças nos dados e no processo.

Introdução

A exportação de dados usando o Serviço de consulta (Data Distiller) e a exportação de conjunto de dados consiste em:

Pré-requisitos

Certifique-se de atender a todos os requisitos a seguir antes de usar a funcionalidade descrita neste caso de uso:

Serviço de consulta

O Serviço de consulta de Experience Platform permite consultar e associar qualquer conjunto de dados no data lake de Experience Platform como se fosse uma tabela de banco de dados. Você pode capturar os resultados como um novo conjunto de dados para uso em relatórios ou para exportação.

Você pode usar a interface de usuário do Serviço de Consulta, um cliente conectado por meio do protocolo PostgresQL ou as APIs RESTful para criar e agendar consultas que coletam os dados do seu feed de dados.

Criar consulta

Você pode usar toda a funcionalidade do SQL ANSI padrão para instruções SELECT e outros comandos limitados para criar e executar queries que geram os dados para seu feed de dados. Consulte Sintaxe SQL para obter mais informações. Além dessa sintaxe SQL, o Adobe suporta:

Colunas de feed de dados

Os campos XDM que você pode usar no query dependem da definição de esquema em que seus conjuntos de dados se baseiam. Entenda o esquema subjacente ao conjunto de dados. Consulte para obter mais informações o guia da interface do usuário de conjuntos de dados.

Para ajudar você a definir o mapeamento entre as colunas do Feed de dados e os campos XDM, consulte Mapeamento de campos do Analytics. Consulte também a Visão geral da interface do usuário de esquemas para obter mais informações sobre como gerenciar recursos XDM, incluindo esquemas, classes, grupos de campos e tipos de dados.

Por exemplo, caso queira usar nome da página como parte do seu feed de dados:

Identidades

No Experience Platform, várias identidades estão disponíveis. Ao criar suas consultas, verifique se você está consultando identidades corretamente.

Geralmente você encontra identidades em um grupo de campos separado. Em uma implementação, a ECID (ecid) pode ser definida como parte de um grupo de campos com um objeto core, o qual faz parte de um objeto identification (por exemplo: _sampleorg.identification.core.ecid). As ECIDs podem ser organizadas de forma diferente em seus esquemas.

Como alternativa, você pode usar identityMap para consultar identidades. O identityMap é do tipo Map e usa uma estrutura de dados aninhada.

Consulte Definir campos de identidade na interface para obter mais informações sobre como definir campos de identidade no Experience Platform.

Consulte Identificadores primários em dados do Analytics para entender como as identidades do Adobe Analytics são mapeadas para identidades Experience Platform ao usar o conector de origem do Analytics. Esse mapeamento pode servir como orientação para configurar suas identidades, mesmo quando não estiver usando o conector de origem do Analytics.

Dados e identificação do nível de ocorrência

Com base na implementação, os dados de nível de ocorrência tradicionalmente coletados no Adobe Analytics agora são armazenados como dados de evento com carimbo de data e hora no Experience Platform. A tabela a seguir é extraída do mapeamento de campo do Analytics e mostra exemplos de como mapear colunas do Feed de dados do Adobe Analytics específicas para o nível de ocorrência com campos XDM correspondentes em suas consultas. A tabela também mostra exemplos de como as ocorrências, visitas e visitantes são identificados usando campos XDM.

Publicar colunas

Os Feeds de dados do Adobe Analytics usam o conceito de colunas com um prefixo post_, que são colunas que contêm dados após o processamento. Consulte Perguntas frequentes sobre feeds de dados para obter mais informações.

Os dados coletados em conjuntos de dados por meio do Edge Network Experience Platform (SDK da Web, SDK móvel, API do servidor) não têm conceito de campos post_. Como resultado, as colunas de feed de dados com o prefixo post_ e o prefixo non-post_ mapeiam para os mesmos campos XDM. Por exemplo, as colunas de feed de dados page_url e post_page_url mapeiam para o mesmo campo XDM web.webPageDetails.URL.

Consulte Comparar o processamento de dados entre o Adobe Analytics e o Customer Journey Analytics para obter uma visão geral da diferença no processamento de dados.

O tipo de dados da coluna de prefixo post_, quando coletado no data lake do Experience Platform, requer, no entanto, transformações avançadas antes de poder ser usado com êxito em um caso de uso de feed de dados. A execução dessas transformações avançadas em suas consultas envolve o uso de funções definidas por Adobe para sessão, atribuição e desduplicação. Consulte Exemplos sobre como usar essas funções.

Pesquisas

Para pesquisar dados de outros conjuntos de dados, use a funcionalidade SQL padrão (WHERE cláusula, INNER JOIN, OUTER JOIN e outras).

Cálculos

Para realizar cálculos em campos (colunas), use as funções SQL padrão (por exemplo COUNT(*)) ou a parte funções e operadores matemáticos e estatísticos do Spark SQL. Além disso, as funções de janela oferecem suporte para atualizar agregações e retornar itens únicos para cada linha em um subconjunto ordenado. Consulte Exemplos sobre como usar essas funções.

Estrutura de dados aninhada

Os esquemas nos quais os conjuntos de dados são baseados geralmente contêm tipos de dados complexos, incluindo estruturas de dados aninhadas. identityMap mencionado anteriormente é um exemplo de estrutura de dados aninhada. Veja abaixo um exemplo de dados de identityMap.

{
   "identityMap":{
      "FPID":[
         {
            "id":"55613368189701342632255821452918751312",
            "authenticatedState":"ambiguous"
         }
      ],
      "CRM":[
         {
            "id":"2394509340-30453470347",
            "authenticatedState":"authenticated"
         }
      ]
   }
}

Você pode usar a explode() ou outras funções de Matrizes do Spark SQL para obter os dados dentro de uma estrutura de dados aninhada, por exemplo:

select explode(identityMap) from demosys_cja_ee_v1_website_global_v1_1 limit 15;

Como alternativa, você pode consultar elementos individuais usando a notação de pontos. Por exemplo:

select identityMap.ecid from demosys_cja_ee_v1_website_global_v1_1 limit 15;

Consulte Trabalho com estruturas de dados aninhadas no Query Service para obter mais informações.

Exemplos

Para consultas:

consulte:

Veja abaixo um exemplo de como aplicar corretamente a atribuição entre sessões e isso ilustra como

+++
Detalhes

Para fazer isso, você tem que…

Exemplo de funções da janela de sessão

$$ BEGIN
   -- Disable dropping system columns
   set drop_system_columns=false;

   -- Initialize variables
   SET @last_updated_timestamp = SELECT CURRENT_TIMESTAMP;

   -- Get the last processed batch ingestion time
   SET @from_batch_ingestion_time = SELECT coalesce(last_batch_ingestion_time, 'HEAD')
      FROM checkpoint_log a
      JOIN (
            SELECT MAX(process_timestamp) AS process_timestamp
            FROM checkpoint_log
            WHERE process_name = 'data_feed'
            AND process_status = 'SUCCESSFUL'
      ) b
      ON a.process_timestamp = b.process_timestamp;

   -- Get the last batch ingestion time
   SET @to_batch_ingestion_time = SELECT MAX(_acp_system_metadata.ingestTime)
      FROM events_dataset;

   -- Sessionize the data and insert into data_feed.
   INSERT INTO data_feed
   SELECT *
   FROM (
      SELECT
            userIdentity,
            timestamp,
            SESS_TIMEOUT(timestamp, 60 * 30) OVER (
               PARTITION BY userIdentity
               ORDER BY timestamp
               ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
            ) AS session_data,
            page_name,
            ingest_time
      FROM (
            SELECT
               userIdentity,
               timestamp,
               web.webPageDetails.name AS page_name,
               _acp_system_metadata.ingestTime AS ingest_time
            FROM events_dataset
            WHERE timestamp >= current_date - 90
      ) AS a
      ORDER BY userIdentity, timestamp ASC
   ) AS b
   WHERE b.ingest_time >= @from_batch_ingestion_time;

   -- Update the checkpoint_log table
   INSERT INTO checkpoint_log
   SELECT
      'data_feed' process_name,
      'SUCCESSFUL' process_status,
      cast(@to_batch_ingestion_time AS string) last_batch_ingestion_time,
      cast(@last_updated_timestamp AS TIMESTAMP) process_timestamp
END
$$;

Exemplo de funções da janela de atribuição

$$ BEGIN
 SET drop_system_columns=false;

-- Initialize variables
 SET @last_updated_timestamp = SELECT CURRENT_TIMESTAMP;

-- Get the last processed batch ingestion time 1718755872325
 SET @from_batch_ingestion_time =
     SELECT coalesce(last_snapshot_id, 'HEAD')
     FROM checkpoint_log a
     JOIN (
         SELECT MAX(process_timestamp) AS process_timestamp
         FROM checkpoint_log
         WHERE process_name = 'data_feed'
         AND process_status = 'SUCCESSFUL'
     ) b
     ON a.process_timestamp = b.process_timestamp;

 -- Get the last batch ingestion time 1718758687865
 SET @to_batch_ingestion_time =
     SELECT MAX(_acp_system_metadata.ingestTime)
     FROM demo_data_trey_mcintyre_midvalues;

 -- Sessionize the data and insert into new_sessionized_data
 INSERT INTO new_sessionized_data
 SELECT *
 FROM (
     SELECT
         _id,
         timestamp,
         struct(User_Identity,
         cast(SESS_TIMEOUT(timestamp, 60 * 30) OVER (
             PARTITION BY User_Identity
             ORDER BY timestamp
             ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
         ) as string) AS SessionData,
         to_timestamp(from_unixtime(ingest_time/1000, 'yyyy-MM-dd HH:mm:ss')) AS IngestTime,
         PageName,
         first_url,
         first_channel_type
           ) as _demosystem5
     FROM (
         SELECT
             _id,
             ENDUSERIDS._EXPERIENCE.MCID.ID as User_Identity,
             timestamp,
             web.webPageDetails.name AS PageName,
            attribution_first_touch(timestamp, '', web.webReferrer.url) OVER (PARTITION BY ENDUSERIDS._EXPERIENCE.MCID.ID ORDER BY timestamp ASC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING).value AS first_url,
            attribution_first_touch(timestamp, '',channel.typeAtSource) OVER (PARTITION BY ENDUSERIDS._EXPERIENCE.MCID.ID ORDER BY timestamp ASC ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING).value AS first_channel_type,
             _acp_system_metadata.ingestTime AS ingest_time
         FROM demo_data_trey_mcintyre_midvalues
         WHERE timestamp >= current_date - 90
     )
     ORDER BY User_Identity, timestamp ASC
 )
 WHERE _demosystem5.IngestTime >= to_timestamp(from_unixtime(@from_batch_ingestion_time/1000, 'yyyy-MM-dd HH:mm:ss'));

-- Update the checkpoint_log table
INSERT INTO checkpoint_log
SELECT
   'data_feed' as process_name,
   'SUCCESSFUL' as process_status,
   cast(@to_batch_ingestion_time AS string) as last_snapshot_id,
   cast(@last_updated_timestamp AS timestamp) as process_timestamp;

END
$$;

+++

Agendar consulta

Você programa a consulta para garantir que ela seja executada e que os resultados sejam gerados no intervalo de sua preferência.

Uso do Editor de consultas

Você pode agendar uma consulta usando o Editor de consultas. Ao agendar a query, você define um conjunto de dados de saída. Consulte Agendamentos de consulta para obter mais informações.

Uso da API do Serviço de consulta

Como alternativa, você pode usar as APIs RESTful para definir uma consulta e um agendamento para a consulta. Consulte o Guia da API do Serviço de Consulta para obter mais informações.
Defina o conjunto de dados de saída como parte da propriedade ctasParameters opcional ao criar a consulta (Criar uma consulta) ou ao criar o agendamento para uma consulta (Criar uma consulta agendada).

Exportar conjuntos de dados

Depois de criar e agendar sua consulta e verificar os resultados, você pode exportar os conjuntos de dados brutos para destinos de armazenamento na nuvem. Essa exportação está na terminologia Destinos do Experience Platform, conhecida como Destinos de exportação do conjunto de dados. Consulte Exportar conjuntos de dados para destinos de armazenamento na nuvem para obter uma visão geral.

Os seguintes destinos de armazenamento em nuvem são compatíveis:

IU DO EXPERIENCE PLATFORM

Você pode exportar e agendar a exportação dos conjuntos de dados de saída por meio da interface do usuário do Experience Platform. Esta seção descreve as etapas envolvidas.

Selecionar destino

Depois de determinar para qual destino de armazenamento na nuvem você deseja exportar o conjunto de dados de saída, selecione o destino. Quando ainda não tiver configurado um destino para o armazenamento na nuvem de sua preferência, você deve criar uma nova conexão de destino.

Como parte da configuração de um destino, você pode

Selecionar conjunto de dados

Ao selecionar o destino, na próxima etapa Selecionar conjuntos de dados, é necessário selecionar o conjunto de dados de saída na lista de conjuntos de dados. Se você tiver criado várias consultas programadas e quiser que os conjuntos de dados de saída enviem para o mesmo destino de armazenamento na nuvem, poderá selecionar os conjuntos de dados de saída correspondentes. Consulte Selecionar seus conjuntos de dados para obter mais informações.

Programar exportação do conjunto de dados

Por fim, você deseja agendar a exportação do seu conjunto de dados como parte da etapa Agendamento. Nessa etapa, é possível definir o agendamento e se a exportação do conjunto de dados de saída deve ser incremental ou não. Consulte Agendar exportação do conjunto de dados para obter mais informações.

Etapas finais

Revise sua seleção e, quando estiver correto, comece a exportar seu conjunto de dados de saída para o destino de armazenamento na nuvem.

Você deve verificar uma exportação de dados bem-sucedida. Ao exportar conjuntos de dados, o Experience Platform cria um ou vários arquivos .json ou .parquet no local de armazenamento definido no seu destino. Espere que os novos arquivos sejam depositados no local de armazenamento de acordo com o agendamento de exportação configurado. O Experience Platform cria uma estrutura de pastas no local de armazenamento especificado como parte do destino selecionado, onde deposita os arquivos exportados. Uma nova pasta é criada para cada exportação, seguindo o padrão: folder-name-you-provided/datasetID/exportTime=YYYYMMDDHHMM. O nome de arquivo padrão é gerado aleatoriamente e garante que os nomes de arquivo exportados sejam exclusivos.

API do serviço de fluxo

Como alternativa, você pode exportar e agendar a exportação de conjuntos de dados de saída usando APIs. As etapas envolvidas estão documentadas em Exportar conjuntos de dados usando a API de Serviço de Fluxo.

Introdução

Para exportar conjuntos de dados, verifique se você tem as permissões necessárias. Verifique também se o destino para onde deseja enviar o conjunto de dados de saída suporta a exportação de conjuntos de dados. Em seguida, você deve coletar os valores dos cabeçalhos obrigatórios e opcionais que você usa nas chamadas de API. Você também precisa identificar a especificação da conexão e as IDs da especificação do fluxo do destino para o qual você pretende exportar conjuntos de dados.

Recuperar conjuntos de dados qualificados

Você pode recuperar uma lista de conjuntos de dados qualificados para exportação e verificar se o conjunto de dados de saída faz parte dessa lista usando a API GET /connectionSpecs/{id}/configs.

Criar conexão de origem

Em seguida, você deve criar uma conexão de origem para o conjunto de dados de saída, usando sua ID exclusiva, que você deseja exportar para o destino de armazenamento na nuvem. Você usa a API POST /sourceConnections.

Autenticar para destino (criar conexão base)

Agora você deve criar uma conexão base para autenticar e armazenar com segurança as credenciais no destino de armazenamento na nuvem usando a API POST /targetConection.

Fornecer parâmetros de exportação

Em seguida, você deve criar uma conexão de destino adicional que armazene os parâmetros de exportação para seu conjunto de dados de saída usando, mais uma vez, a API POST /targetConection. Esses parâmetros de exportação incluem local, formato de arquivo, compactação e muito mais.

Configurar fluxo de dados

Por fim, você configurou o fluxo de dados para garantir que o conjunto de dados de saída seja exportado para o destino de armazenamento na nuvem usando a API POST /flows. Nesta etapa, você pode definir o agendamento da exportação, usando o parâmetro scheduleParams.

Validar fluxo de dados

Para verificar execuções bem-sucedidas do fluxo de dados, use a API GET /runs, especificando a ID do fluxo de dados como parâmetro de consulta. Essa ID de fluxo de dados é um identificador retornado ao configurar o fluxo de dados.

Verificar uma exportação de dados bem-sucedida. Ao exportar conjuntos de dados, o Experience Platform cria um ou vários arquivos .json ou .parquet no local de armazenamento definido no seu destino. Espere que os novos arquivos sejam depositados no local de armazenamento de acordo com o agendamento de exportação configurado. O Experience Platform cria uma estrutura de pastas no local de armazenamento especificado como parte do destino selecionado, onde deposita os arquivos exportados. Uma nova pasta é criada para cada exportação, seguindo o padrão: folder-name-you-provided/datasetID/exportTime=YYYYMMDDHHMM. O nome de arquivo padrão é gerado aleatoriamente e garante que os nomes de arquivo exportados sejam exclusivos.

Conclusão

Resumindo, emular a funcionalidade do Feed de dados do Adobe Analytics implica configurar consultas agendadas usando o Serviço de consulta e usando os resultados dessas consultas em exportações de conjunto de dados agendadas.