Ative públicos para destinos baseados em arquivo usando a API do Serviço de fluxo
Use os recursos aprimorados de exportação de arquivos para acessar a funcionalidade aprimorada de personalização ao exportar arquivos do Experience Platform:
- Opções de nomenclatura de arquivo adicionais.
- Capacidade de definir cabeçalhos de arquivos personalizados em seus arquivos exportados por meio da etapa de mapeamento aprimorado.
- Capacidade de selecionar o tipo de arquivo do arquivo exportado.
- Capacidade de personalizar a formatação de arquivos de dados CSV exportados.
Essa funcionalidade é compatível com os seis cartões de armazenamento em nuvem listados abaixo:
Este artigo explica o fluxo de trabalho necessário para usar a API de Serviço de Fluxo para exportar perfis qualificados do Adobe Experience Platform para um dos locais de armazenamento na nuvem vinculados acima.
Introdução get-started
Este guia requer uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
- Experience Data Model (XDM) System: a estrutura padronizada pela qual o Experience Platform organiza os dados de experiência do cliente.
- Segmentation Service: Adobe Experience Platform Segmentation Service cria públicos-alvo em Adobe Experience Platform a partir dos dados de Real-Time Customer Profile.
- Sandboxes: Experience Platform fornece sandboxes virtuais que particionam uma única instância do Experience Platform em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.
As seções a seguir fornecem informações adicionais que você precisa saber para ativar dados para destinos baseados em arquivo no Experience Platform.
Permissões necessárias permissions
Para exportar perfis, você precisa de Exibir Destinos, Ativar Destinos, Exibir Perfis e Exibir Segmentos permissões de controle de acesso. Leia a visão geral do controle de acesso ou contate o administrador do produto para obter as permissões necessárias.
Para exportar identidades, você precisa da permissão Exibir Gráfico de Identidade controle de acesso.
Leitura de chamadas de API de amostra reading-sample-api-calls
Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e conteúdos de solicitação formatados corretamente. Também fornece exemplos de JSON retornado nas respostas da API. Para obter informações sobre as convenções usadas na documentação para chamadas de API de exemplo, consulte a seção sobre como ler chamadas de API de exemplo no guia de solução de problemas da Experience Platform.
Colete valores para cabeçalhos obrigatórios e opcionais gather-values-headers
Para fazer chamadas para APIs do Experience Platform, primeiro complete o tutorial de autenticação do Experience Platform. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API da Experience Platform, conforme mostrado abaixo:
- Autorização: Portador
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id
{ORG_ID}
Os recursos em Experience Platform podem ser isolados em sandboxes virtuais específicas. Em solicitações para Experience Platform APIs, é possível especificar o nome e a ID da sandbox em que a operação ocorrerá. Esses parâmetros são opcionais.
- x-sandbox-name:
{SANDBOX_NAME}
Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho de tipo de mídia adicional:
- Tipo de conteúdo:
application/json
Documentação de referência da API api-reference-documentation
Você pode encontrar a documentação de referência de acompanhamento para todas as operações de API neste tutorial. Consulte a documentação do Serviço de Fluxo - API de Destinos no site da Adobe Developer. Recomendamos que você use este tutorial e a documentação de referência da API em paralelo.
Glossário glossary
Para obter descrições dos termos que você encontrará neste tutorial de API, leia a seção de glossário da documentação de referência da API.
Selecionar destino para o qual exportar públicos select-destination
Antes de iniciar o fluxo de trabalho para exportar perfis, identifique a especificação da conexão e as IDs de especificação do fluxo do destino para o qual você pretende exportar públicos. Use a tabela abaixo como referência.
4fce964d-3f37-408f-9778-e597338a21ee1a0514a6-33d4-4c7f-aff8-594799c475496d6b59bf-fb58-4107-9064-4d246c0e5bb2752d422f-b16f-4f0d-b1c6-26e448e3b388be2c3209-53bc-47e7-ab25-145db8b873e117be2013-2549-41ce-96e7-a70363bec29310440537-2a7b-4583-ac39-ed38d4b848e8cd2fc47e-e838-4f38-a581-8fff2f99b63ac5d93acb-ea8b-4b14-8f53-02138444ae99585c15c4-6cbf-4126-8f87-e26bff78b65736965a81-b1c6-401b-99f8-22508f1e6a26fd36aaa4-bf2b-43fb-9387-43785eeeb799Você precisa dessas IDs para criar várias entidades do serviço de fluxo nas próximas etapas deste tutorial. Você também precisa fazer referência a partes da especificação de conexão para configurar determinadas entidades para que possa recuperar a especificação de conexão das APIs de serviço de fluxo. Veja os exemplos abaixo de recuperação das especificações de conexão para todos os destinos na tabela:
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para Amazon S3 | ||
|
Resposta
| accordion | ||
|---|---|---|
| Amazon S3 - Especificação da conexão | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para Azure Blob Storage | ||
|
Resposta
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para Azure Data Lake Gen 2(ADLS Gen2) | ||
|
Resposta
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para Data Landing Zone(DLZ) | ||
|
Resposta
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para Google Cloud Storage | ||
|
Resposta
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Recuperar connection spec para SFTP | ||
|
Resposta
| accordion | ||
|---|---|---|
| SFTP - Connection spec | ||
|
Siga as etapas abaixo para configurar um fluxo de dados de exportação de público-alvo para um destino de armazenamento na nuvem. Para algumas etapas, as solicitações e respostas diferem entre os vários destinos de armazenamento na nuvem. Nesses casos, use as guias na página para recuperar as solicitações e respostas específicas ao destino ao qual você deseja se conectar e exportar públicos. Certifique-se de usar o connection spec e o flow spec corretos para o destino que você está configurando.
Criar uma conexão com o Source create-source-connection
Depois de decidir para qual destino você está exportando públicos, é necessário criar uma conexão de origem. A conexão de origem representa a conexão com o repositório de Perfis da Experience Platform interno.
Solicitação
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha ao copiar e colar a solicitação no terminal de sua escolha.
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Uma resposta bem-sucedida retorna a ID (id) da conexão de origem recém-criada e um etag. Anote a ID da conexão de origem, pois ela será necessária posteriormente ao criar o fluxo de dados.
Criar uma conexão básica create-base-connection
Uma conexão base armazena com segurança as credenciais no seu destino. Dependendo do tipo de destino, as credenciais necessárias para a autenticação nesse destino podem variar. Para localizar esses parâmetros de autenticação, primeiro recupere o connection spec do destino desejado, conforme descrito na seção Selecione o destino para o qual exportar públicos e, em seguida, verifique a authSpec da resposta. Consulte as guias abaixo para obter as propriedades authSpec de todos os destinos com suporte.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec mostrando auth spec | ||
|
Observe a linha destacada com comentários embutidos no exemplo connection spec abaixo, que fornece informações adicionais sobre onde encontrar os parâmetros de autenticação no connection spec.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec mostrando auth spec | ||
|
Observe a linha destacada com comentários embutidos no exemplo connection spec abaixo, que fornece informações adicionais sobre onde encontrar os parâmetros de autenticação no connection spec.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec mostrando auth spec | ||
|
Observe a linha destacada com comentários embutidos no exemplo connection spec abaixo, que fornece informações adicionais sobre onde encontrar os parâmetros de autenticação no connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Connection spec mostrando auth spec | |||||
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec mostrando auth spec | ||
|
Observe a linha destacada com comentários embutidos no exemplo connection spec abaixo, que fornece informações adicionais sobre onde encontrar os parâmetros de autenticação no connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Connection spec mostrando auth spec | |||||
Observe a linha destacada com comentários embutidos no exemplo connection spec abaixo, que fornece informações adicionais sobre onde encontrar os parâmetros de autenticação no connection spec.
|
Usando as propriedades especificadas na especificação de autenticação (ou seja, authSpec da resposta), você pode criar uma conexão base com as credenciais necessárias, específicas para cada tipo de destino, conforme mostrado nos exemplos abaixo:
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitação de conexão básica com autenticação de chave de acesso e chave secreta | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitação de conexão base com autenticação de função assumida | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Amazon S3 Resposta de conexão base | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitação de conexão básica | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Azure Blob Storage - Resposta da conexão base | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitação de conexão básica | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Resposta da conexão base | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Solicitação de conexão básica | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Data Landing Zone - Resposta da conexão base | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitação de conexão básica | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Google Cloud Storage - Resposta da conexão base | ||
|
Solicitação
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP com senha - Solicitação de conexão básica | |||||||||||||||||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP com chave SSH - Solicitação de conexão básica | |||||||||||||||||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| SFTP - Resposta de conexão básica | ||
|
Adicionar criptografia aos arquivos exportados add-encryption
Como opção, você pode adicionar criptografia aos arquivos exportados. Para fazer isso, você precisa adicionar itens do objeto encryption. Consulte o exemplo de solicitação abaixo com os parâmetros obrigatórios destacados:
| code language-json line-numbers data-start-1 data-line-offset-4 h-26-27 |
|---|
|
Solicitação
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha ao copiar e colar a solicitação no terminal de sua escolha.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-19 |
|---|
|
Resposta
| code language-json |
|---|
|
Observe a ID de conexão da resposta. Essa ID será necessária na próxima etapa ao criar a conexão de destino.
Criar uma conexão de destino create-target-connection
Em seguida, é necessário criar uma conexão de destino. As conexões de destino armazenam os parâmetros de exportação para os públicos exportados. Os parâmetros de exportação incluem local de exportação, formato de arquivo, compactação e outros detalhes. Por exemplo, para arquivos CSV, é possível selecionar várias opções de exportação. Obtenha informações abrangentes sobre todas as opções de exportação de CSV compatíveis na página de configurações de formatação de arquivo.
Consulte as propriedades targetSpec fornecidas no connection spec do destino para entender as propriedades com suporte para cada tipo de destino. Consulte as guias abaixo para obter as propriedades targetSpec de todos os destinos com suporte.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
| accordion | ||
|---|---|---|
| SFTP - Connection spec mostrando parâmetros de conexão de destino | ||
|
Observe as linhas destacadas com comentários embutidos no exemplo connection spec abaixo, que fornecem informações adicionais sobre onde encontrar os parâmetros target spec na especificação da conexão. Você também pode ver no exemplo abaixo quais parâmetros de destino são não aplicáveis a destinos de exportação de público.
|
Usando a especificação acima, você pode criar uma solicitação de conexão de destino específica para seu destino de armazenamento na nuvem desejado, como mostrado nas guias abaixo.
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitação de conexão de destino | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitação de conexão de destino com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitação de conexão de destino | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitação de conexão de destino com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitação de conexão de destino | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitação de conexão de destino com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Solicitação de conexão de destino | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Solicitação de conexão de destino com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitação de conexão de destino | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitação de conexão de destino com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Solicitação
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Solicitação de conexão do Target | |||||
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Solicitação de conexão do Target com opções CSV | |||||
|
Resposta
| accordion | ||
|---|---|---|
| Conexão do Target - Resposta | ||
|
Anote o target connection ID da resposta. Essa ID será necessária na próxima etapa, ao criar o fluxo de dados para exportar públicos.
Uma resposta bem-sucedida retorna a ID (id) da conexão de origem de destino recém-criada e um etag. Anote a ID de conexão de destino, pois ela será necessária posteriormente ao criar o fluxo de dados.
Criar um fluxo de dados create-dataflow
A próxima etapa na configuração de destino é criar um fluxo de dados. Um fluxo de dados une entidades criadas anteriormente e também fornece opções para configurar o agendamento de exportação de público. Para criar o fluxo de dados, use as cargas abaixo, dependendo do destino do armazenamento na nuvem desejado, e substitua as IDs de entidade de fluxo das etapas anteriores. Observe que, nessa etapa, você não está adicionando informações relacionadas ao mapeamento de atributo ou identidade para o fluxo de dados. Isso seguirá na próxima etapa.
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para Amazon S3 destino - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para Azure Blob Storage destino - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para Azure Data Lake Gen 2(ADLS Gen2) destino - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para Data Landing Zone destino - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para Google Cloud Storage destino - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Solicitação
| accordion | ||
|---|---|---|
| Criar fluxo de dados de exportação de público para destino SFTP - Solicitação | ||
|
Observe as linhas destacadas com comentários em linha no exemplo de solicitação, que fornecem informações adicionais. Remova os comentários em linha na solicitação ao copiar e colar a solicitação no terminal de sua escolha.
|
Resposta
| accordion | ||
|---|---|---|
| Criar fluxo de dados - Resposta | ||
|
Observe a ID de fluxo de dados na resposta. Essa ID será necessária em etapas posteriores.
Adicionar públicos-alvo à exportação add-audiences
Nesta etapa, também é possível selecionar quais públicos-alvo você deseja exportar para o destino. Para obter informações abrangentes sobre esta etapa e o formato da solicitação para adicionar um público-alvo ao fluxo de dados, veja os exemplos na seção Atualizar um fluxo de dados de destino da documentação de referência da API.
Configurar mapeamento de atributo e identidade attribute-and-identity-mapping
Depois de criar o fluxo de dados, é necessário configurar o mapeamento dos atributos e identidades que deseja exportar. Complete as etapas a seguir na ordem:
- Recupere o esquema de entrada.
- Recupere e inspecione o esquema do parceiro.
- Crie o esquema de saída, incluindo todos os campos que deseja exportar como um destino de mapeamento.
- Confirme se cada destino de mapeamento existe no esquema de saída.
- Crie o conjunto de mapeamento.
- Atualize o fluxo de dados com o conjunto de mapeamento.
Por exemplo, para obter o mapeamento a seguir mostrado na interface do usuário do, seria necessário percorrer as etapas listadas acima e detalhadas nos próximos cabeçalhos.
firstName, lastName ou Email, já deve existir no esquema de saída antes da criação do conjunto de mapeamento. Se um campo de destino de mapeamento estiver ausente no esquema de saída, a solicitação do conjunto de mapeamento falhará.Criar um esquema de entrada create-input-schema
Para criar um esquema de entrada, primeiro é necessário recuperar o esquema de união e as identidades que podem ser exportadas para o destino. Este é o esquema de atributos e identidades que você pode selecionar como mapeamento de origem.
Veja abaixo exemplos de solicitações e respostas para recuperar atributos e identidades.
Solicitação para obter atributos
| code language-shell |
|---|
|
Resposta
A resposta abaixo foi encurtada por questões de brevidade.
| code language-json |
|---|
|
Solicitação para obter identidades
| code language-shell |
|---|
|
Resposta
A resposta retorna as identidades que você pode usar ao criar o esquema de entrada. Observe que esta resposta retorna os namespaces de identidade padrão e personalizados configurados no Experience Platform.
| code language-json |
|---|
|
Em seguida, é necessário copiar a resposta acima e usá-la para criar o esquema de entrada. Você pode copiar toda a resposta JSON da resposta acima e colocá-la no objeto jsonSchema indicado abaixo.
Solicitação para criar o esquema de entrada
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
A ID na resposta representa o identificador exclusivo do esquema de entrada criado. Copie a ID da resposta, pois você reutilizará isso em uma etapa posterior.
Criar um esquema de saída create-output-schema
Em seguida, você deve configurar o schema de saída para sua exportação. Primeiro, é necessário encontrar e inspecionar o esquema de parceiro existente.
Solicitação
Observe que o exemplo abaixo usa connection spec ID para Amazon S3. Substitua esse valor pela ID de especificação da conexão específica ao seu destino.
| code language-shell |
|---|
|
Resposta com um exemplo de esquema
Inspecione a resposta obtida ao executar a chamada acima. Você precisa detalhar a resposta para localizar o objeto targetSpec.attributes.partnerSchema.jsonSchema
| code language-json |
|---|
|
Em seguida, é necessário criar um schema de saída. Copie a resposta JSON recebida acima e cole-a no objeto jsonSchema abaixo.
O esquema de parceiro contém apenas estruturas genéricas, como attributes, identityMap e segmentMembership. Antes de criar o conjunto de mapeamento na próxima etapa, adicione uma propriedade ao objeto jsonSchema para cada campo para o qual você pretende mapear. A API de mapeamento valida cada destino de mapeamento em relação ao esquema de saída, de modo que um campo de destino de mapeamento que não existe no esquema de saída causa falha na solicitação do conjunto de mapeamento.
A solicitação e a resposta de exemplo abaixo mostram as propriedades firstName, lastName, Email, personalEmail_address e segmentMembership_status já adicionadas ao esquema de saída junto com as estruturas attributes, identityMap e segmentMembership genéricas do esquema parceiro. Estas propriedades correspondem aos destinos de mapeamento usados no exemplo de conjunto de mapeamento posteriormente nesta seção.
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
A ID na resposta representa o identificador exclusivo do esquema de saída criado. Copie a ID da resposta, pois você reutilizará isso em uma etapa posterior.
Criar conjunto de mapeamento create-mapping-set
Em seguida, use a API de preparação de dados para criar o conjunto de mapeamento usando a ID do esquema de entrada, a ID do esquema de saída e os mapeamentos de campo desejados.
Solicitação
| note important |
|---|
| IMPORTANT |
|
Antes de criar o conjunto de mapeamento, verifique o seguinte:
- Cada campo de destino de mapeamento, como
firstName,lastNameeEmail, já existe no esquema de saída. - Todo caminho de origem existe no esquema de entrada.
- Os mapeamentos de identidade usam namespaces de identidade válidos.
- Campos de associação de segmento, como
segmentMembership_status, são definidos no esquema de saída se você referenciá-los em um mapeamento. - O esquema de entrada, o esquema de saída e o conjunto de mapeamento pertencem à mesma sandbox.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-16-42 |
|---|
|
Resposta
| code language-json |
|---|
|
MAPPER-3101-400 informando que o caminho XDM é inválido, um ou mais valores destination do mapeamento não existirão no esquema de saída. Adicione os campos ausentes ao esquema de saída e repita a solicitação do conjunto de mapeamento.Observe a ID do conjunto de mapeamento, pois será necessário na próxima etapa para atualizar o fluxo de dados existente com a ID do conjunto de mapeamento.
Em seguida, obtenha a ID do fluxo de dados que você deseja atualizar.
Consulte recuperar os detalhes de um fluxo de dados de destino para obter informações sobre como recuperar a ID de um fluxo de dados.
Finalmente, é necessário PATCH o fluxo de dados com as informações do conjunto de mapeamento que você acabou de criar.
Solicitação
| code language-shell |
|---|
|
Resposta
A resposta da API do Serviço de fluxo retorna a ID do fluxo de dados atualizado.
| code language-json |
|---|
|
Fazer outras atualizações de fluxo de dados other-dataflow-updates
Para fazer atualizações no fluxo de dados, use a operação PATCH. Por exemplo, você pode adicionar uma ação de marketing aos fluxos de dados, atualizar os fluxos de dados para selecionar campos como chaves obrigatórias ou chaves de desduplicação, adicionar atributos de enriquecimento para públicos de upload personalizados ou adicionar a geração de manifesto de arquivo aos destinos existentes.
Adicionar uma ação de marketing add-marketing-action
Para adicionar uma ação de marketing, consulte os exemplos de solicitação e resposta abaixo.
If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a versão exclusiva do fluxo de dados que você deseja atualizar. O valor da tag é atualizado com cada atualização bem-sucedida de uma entidade de fluxo, como fluxo de dados, conexão de destino e outras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, em que {ID} é a ID do fluxo de dados que você deseja atualizar.If-Match entre aspas duplas, como nos exemplos abaixo, ao fazer solicitações PATCH.Solicitação
| code language-shell |
|---|
|
Resposta
Uma resposta bem-sucedida retorna o código de resposta 200 junto com a ID do fluxo de dados atualizado e a eTag atualizada.
| code language-json |
|---|
|
Adicionar uma chave obrigatória add-mandatory-key
Para adicionar uma chave obrigatória, consulte os exemplos de solicitação e resposta abaixo.
If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a versão exclusiva do fluxo de dados que você deseja atualizar. O valor da tag é atualizado com cada atualização bem-sucedida de uma entidade de fluxo, como fluxo de dados, conexão de destino e outras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, em que {ID} é a ID do fluxo de dados que você deseja atualizar.If-Match entre aspas duplas, como nos exemplos abaixo, ao fazer solicitações PATCH.Solicitação
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Adicionar uma chave de desduplicação add-deduplication-key
Para adicionar uma chave de desduplicação, consulte os exemplos de solicitação e resposta abaixo
If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a versão exclusiva do fluxo de dados que você deseja atualizar. O valor da tag é atualizado com cada atualização bem-sucedida de uma entidade de fluxo, como fluxo de dados, conexão de destino e outras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, em que {ID} é a ID do fluxo de dados que você deseja atualizar.If-Match entre aspas duplas, como nos exemplos abaixo, ao fazer solicitações PATCH.Solicitação
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Adicionar geração de manifesto de arquivo ao destino existente add-file-manifest
Os arquivos JSON de manifesto contêm informações sobre o local de exportação, o tamanho da exportação e muito mais. O manifesto é nomeado usando o formato manifest-<<destinationId>>-<<dataflowRunId>>.json. Exibir um arquivo de manifesto de exemplo. O arquivo de manifesto inclui os seguintes campos:
flowRunId: A execução do fluxo de dados que gerou o arquivo exportado.scheduledTime: A hora em UTC quando o arquivo foi exportado.exportResults.sinkPath: O caminho no local de armazenamento onde o arquivo exportado está depositado.exportResults.name: O nome do arquivo exportado.size: O tamanho do arquivo exportado, em bytes.
Para adicionar a geração de manifesto de arquivo a um destino existente, é necessário atualizar os parâmetros de conexão de destino usando a operação PATCH. Isso habilita a geração de arquivo de manifesto para o seu destino, que fornece metadados sobre os arquivos exportados.
If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a versão exclusiva da conexão de destino que você deseja atualizar. O valor da tag é atualizado com cada atualização bem-sucedida de uma entidade de fluxo, como fluxo de dados, conexão de destino e outras.https://platform.adobe.io/data/foundation/flowservice/targetConnections/{ID}, em que {ID} é a ID de conexão de destino que você deseja atualizar.If-Match entre aspas duplas, como nos exemplos abaixo, ao fazer solicitações PATCH.Solicitação
| code language-shell |
|---|
|
Adicionar atributos de enriquecimento add-enrichment-attributes
Os atributos de enriquecimento se aplicam quando você ativa Públicos-alvo de upload personalizado, que são públicos-alvo assimilados na Experience Platform como arquivos CSV. Use esse fluxo de trabalho para selecionar quais atributos desses públicos-alvo serão incluídos no arquivo exportado.
O fluxo de trabalho requer dois estágios: primeiro, crie um conjunto de mapeamento que defina quais atributos serão exportados (Etapas 1 a 2) e, em seguida, faça referência a esse conjunto de mapeamento ao adicionar o público-alvo ao seu fluxo de dados (Etapa 3).
InvalidParameterException: "One deduplication key (i.e. primary field) must be specified when activating audiences with enrichment info".Etapa 1: Recuperar o conjunto de dados e o esquema de carga enrichment-step1
Para cada público-alvo que tenha o enriquecimento ativado, recupere o conjunto de dados de carga associado e o esquema XDM. As propriedades do esquema são usadas como esquema de entrada e saída ao criar conjuntos de mapeamento.
Etapa 1a: busca de públicos em massa com metadados do conjunto de dados de carga
Envie as IDs de público-alvo que deseja enriquecer para o endpoint de obtenção em massa do Serviço de segmentação.
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Anote o campo originName e o payloadDatasetId da resposta. Você precisa de ambos nas etapas a seguir.
Etapa 1b: Buscar o conjunto de dados de conteúdo
Use o payloadDatasetId da resposta anterior para buscar o conjunto de dados do Serviço de catálogo.
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Extraia o valor schemaRef.id. Você precisa disso na próxima etapa.
Etapa 1c: Buscar o esquema XDM do Registro de Esquemas
Use o schemaRef.id da resposta do conjunto de dados para recuperar o esquema XDM completo. Codificação de URL da ID do esquema ao usá-la como um parâmetro de caminho.
Por exemplo, https://ns.adobe.com/acme/schemas/88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176 torna-se https%3A%2F%2Fns.adobe.com%2Facme%2Fschemas%2F88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176.
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Etapa 1d: Extrair o esquema JSON
O esquema JSON usado na Etapa 2a depende do tipo de público-alvo, identificado por originName da Etapa 1a.
Para públicos onde originName não é AUDIENCE_ORCHESTRATION, extraia somente o subobjeto tenant-namespaced em properties[meta:tenantNamespace] e combine-o com o title de nível superior. Descartar campos do sistema como _id e timestamp.
Exemplo de esquema JSON extraído:
| code language-json |
|---|
|
Para públicos em que originName é AUDIENCE_ORCHESTRATION, use o conjunto completo de propriedades de nível superior da resposta do Registro de Esquemas. Adicionar meta:xdmType: "object" e type: "object" explicitamente. O title é sempre retirado da resposta do Registro de Esquemas de nível superior.
Exemplo de esquema JSON extraído:
| code language-json |
|---|
|
A tabela a seguir resume qual origem de esquema e campos usar para cada tipo de público-alvo.
originName não é AUDIENCE_ORCHESTRATIONproperties[meta:tenantNamespace]originName é AUDIENCE_ORCHESTRATIONpropertiesEtapa 2: Criar o conjunto de mapeamento enrichment-step2
A criação de um conjunto de mapeamento é uma sequência de duas chamadas: registre o esquema JSON da Etapa 1d como um esquema de conversão para obter uma ID de esquema e, em seguida, crie o conjunto de mapeamento que faz referência a essa ID de esquema.
Etapa 2a: Criar o esquema de conversão
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Etapa 2b: Criar o conjunto de mapeamento
Use o {CONVERSION_SCHEMA_ID} da resposta anterior como inputSchema.id e outputSchema.id. Cada chave de propriedade do esquema é source e destination. O sourceType deve ser sempre text/x.schema-path.
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Armazene os valores id e version retornados. Estes são os mappingSet.id e mappingSet.version que você menciona na próxima etapa.
Etapa 3: adicionar atributos de enriquecimento ao fluxo de dados enrichment-step3
Com o conjunto de mapeamento criado, use uma solicitação PATCH para adicionar o público-alvo com sua configuração de enriquecimento ao seu fluxo de dados.
If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a versão exclusiva do fluxo de dados que você deseja atualizar. O valor da tag é atualizado com cada atualização bem-sucedida de uma entidade de fluxo, como fluxo de dados, conexão de destino e outras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, em que {ID} é a ID do fluxo de dados que você deseja atualizar.If-Match entre aspas duplas, como nos exemplos abaixo, ao fazer solicitações PATCH.Solicitação
| code language-shell |
|---|
|
O objeto enrichmentInfo tem as seguintes propriedades:
enabledsourceTypeAUDIENCE_DATASET.mappingSet.idmappingSet.versionQuando o fluxo for executado, os atributos de enriquecimento resolvidos estarão disponíveis no template de exportação em:
destination.enrichmentAttributes.{namespace}.{segmentId}
enrichmentInfo.enabled como false para todos os públicos. Nenhum conjunto de mapeamento é necessário neste caso.Validar fluxo de dados (obter as execuções do fluxo de dados) get-dataflow-runs
Para verificar as execuções de um fluxo de dados, use a API de execuções de fluxo de dados:
Solicitação
| code language-shell |
|---|
|
Resposta
| code language-json |
|---|
|
Você pode encontrar informações sobre os vários parâmetros retornados pela API de execuções do Fluxo de Dados na documentação de referência da API.
Manipulação de erros de API api-error-handling
Os endpoints de API neste tutorial seguem os princípios gerais de mensagem de erro da API do Experience Platform. Consulte códigos de status da API e erros no cabeçalho da solicitação no guia de solução de problemas do Experience Platform para obter mais informações sobre como interpretar respostas de erro.
Próximas etapas next-steps
Você conectou com sucesso o Experience Platform a um dos destinos de armazenamento na nuvem de sua preferência e configurou um fluxo de dados para o respectivo destino para exportar públicos. Consulte as seguintes páginas para obter mais detalhes, como editar fluxos de dados existentes usando a API do Serviço de fluxo: