Desenvolvimento de integrações de ETL para o Adobe Experience Platform

O guia de integração ETL descreve as etapas gerais para criar conectores seguros e de alto desempenho para Experience Platform e assimilar dados em Platform.

Este guia também inclui exemplos de chamadas de API a serem usadas ao projetar um conector ETL, com links para a documentação que descreve cada serviço Experience Platform e o uso de sua API, com mais detalhes.

Uma amostra de integração está disponível em GitHub por meio do ETL Ecosystem Integration Reference Code sob a Apache License Version 2.0.

Fluxo de trabalho

O diagrama de workflow a seguir fornece uma visão geral de alto nível para a integração de componentes do Adobe Experience Platform com um aplicativo e conector ETL.

Componentes do Adobe Experience Platform

Há vários componentes do Experience Platform envolvidos nas integrações do conector ETL. A lista a seguir descreve vários componentes e funcionalidades principais:

  • Sistema Adobe Identity Management (IMS) - fornece a estrutura para autenticação dos serviços da Adobe.
  • Organização IMS - uma entidade corporativa que pode ser proprietária ou licenciar produtos e serviços e permitir o acesso a seus membros.
  • Usuário do IMS - Membros de uma organização IMS. A relação Organização-Usuário é de muitas para muitas.
  • Sandbox - Uma partição virtual, uma única Platform instância, para ajudar a desenvolver aplicativos de experiência digital.
  • Data Discovery - registra os metadados de dados assimilados e transformados no Experience Platform.
  • Data Access - Fornece aos usuários uma interface para acessar seus dados no Experience Platform.
  • Data Ingestion - Força os dados para o Experience Platform com Data Ingestion APIs.
  • Schema Registry - Define e armazena um schema que descreve a estrutura dos dados a serem usados no Experience Platform.

Introdução às APIs Experience Platform

As seções a seguir fornecem informações adicionais que você precisará saber ou ter em mãos para fazer chamadas com êxito para APIs Experience Platform.

Lendo exemplos de chamadas de API

Este guia fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações do . Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O JSON de exemplo retornado nas respostas da API também é fornecido. 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 Experience Platform guia de solução de problemas.

Coletar valores para cabeçalhos necessários

Para fazer chamadas para Platform APIs, primeiro complete o tutorial de autenticação. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API Experience Platform, conforme mostrado abaixo:

  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Todos os recursos em Experience Platform são isolados para sandboxes virtuais específicas. Todas as solicitações para Platform APIs exigem um cabeçalho que especifica o nome da sandbox em que a operação ocorrerá:

  • x-sandbox-name: {SANDBOX_NAME}
OBSERVAÇÃO

Para obter mais informações sobre sandboxes em Platform, consulte a documentação de visão geral da sandbox.

Todas as solicitações que contêm uma carga útil (POST, PUT, PATCH) exigem um cabeçalho adicional:

  • Tipo de conteúdo: application/json

Fluxo geral do usuário

Para começar, um usuário de ETL faz logon na Experience Platform interface do usuário (UI) e cria conjuntos de dados para assimilação usando um conector padrão ou um conector de serviço de push.

Na interface do usuário, o usuário cria o conjunto de dados de saída selecionando um esquema de conjunto de dados. A escolha do schema depende do tipo de dados (registro ou série de tempo) que está sendo assimilado em Platform. Ao clicar na guia Schemas na interface do usuário, o usuário poderá exibir todos os esquemas disponíveis, incluindo o tipo de comportamento compatível com o esquema.

Na ferramenta ETL, o usuário começará a projetar suas transformações de mapeamento após configurar a conexão apropriada (usando suas credenciais). Pressupõe-se que a ferramenta ETL já tenha Experience Platform conectores instalados (processo não definido neste Guia de Integração).

Os mockups de uma ferramenta ETL de amostra e workflow foram fornecidos no ETL workflow. Embora as ferramentas ETL possam diferir no formato, a maioria expõe funcionalidade semelhante.

OBSERVAÇÃO

O conector ETL deve especificar um filtro de carimbo de data/hora que marque a data para assimilar dados e deslocamento (ou seja, a janela para a qual os dados devem ser lidos). A ferramenta ETL deve suportar a inclusão desses dois parâmetros nesta ou em outra interface de usuário relevante. No Adobe Experience Platform, esses parâmetros serão mapeados para datas disponíveis (se presentes) ou para a data capturada presente no objeto de lote do conjunto de dados.

Exibir lista de conjuntos de dados

Usando a fonte de dados para mapeamento, uma lista de todos os conjuntos de dados disponíveis pode ser obtida usando o Catalog API.

Você pode emitir uma única solicitação de API para exibir todos os conjuntos de dados disponíveis (por exemplo, GET /dataSets), com a prática recomendada sendo incluir parâmetros de consulta que limitam o tamanho da resposta.

Nos casos em que informações completas do conjunto de dados estão sendo solicitadas, a carga da resposta pode atingir mais de 3 GB, o que pode retardar o desempenho geral. Portanto, usar parâmetros de consulta para filtrar apenas as informações necessárias tornará as consultas Catalog mais eficientes.

Filtragem de lista

Ao filtrar respostas, você pode usar vários filtros em uma única chamada ao separar parâmetros com um E comercial (&). Alguns parâmetros de consulta aceitam listas de valores separadas por vírgulas, como o filtro "propriedades" na solicitação de amostra abaixo.

Catalog as respostas são medidas automaticamente de acordo com os limites configurados, no entanto, o parâmetro de consulta "limite" pode ser usado para personalizar as restrições e limitar o número de objetos retornados. Os limites de resposta Catalog pré-configurados são:

  • Se um parâmetro de limite não for especificado, o número máximo de objetos por carga de resposta será 20.
  • O limite global para todas as outras consultas Catalog é de 100 objetos.
  • Para consultas de conjunto de dados, se observableSchema for solicitado usando o parâmetro de consulta de propriedades, o número máximo de conjuntos de dados retornados será 20.
  • Parâmetros de limite inválidos (incluindo limit=0) são atendidos com um erro HTTP 400 que descreve intervalos adequados.
  • Se os limites ou deslocamentos forem passados como parâmetros de consulta, eles terão precedência sobre os passados como cabeçalhos.

Os parâmetros de consulta são abordados com mais detalhes na Visão geral do Serviço de Catálogo.

Formato da API

GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Consulte a Visão geral do serviço de catálogo para obter exemplos detalhados de como fazer chamadas para o Catalog API.

Resposta

A resposta inclui três conjuntos de dados (limit=3) que mostram o "nome", a "descrição" e o "schemaRef", conforme indicado pelo parâmetro de consulta properties.

{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Exibir esquema do conjunto de dados

A propriedade "schemaRef" de um conjunto de dados contém um URI que faz referência ao esquema XDM no qual o conjunto de dados se baseia. O esquema XDM ("schemaRef") representa todos os campos em potencial que podem ser usados pelo conjunto de dados, não necessariamente os campos que estão sendo usados (consulte "observableSchema" abaixo).

O esquema XDM é o esquema usado quando é necessário apresentar ao usuário uma lista de todos os campos disponíveis que podem ser gravados.

O primeiro valor "schemaRef.id" no objeto de resposta anterior (https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18) é um URI que aponta para um esquema XDM específico no Schema Registry. O esquema pode ser recuperado fazendo uma solicitação de pesquisa (GET) para a API Schema Registry.

OBSERVAÇÃO

A propriedade "schemaRef" substitui a propriedade "schema", agora obsoleta. Se "schemaRef" estiver ausente do conjunto de dados ou não contiver um valor, será necessário verificar a presença de uma propriedade "schema". Isso pode ser feito substituindo "schemaRef" por "schema" no parâmetro de consulta properties na chamada anterior. Mais detalhes sobre a propriedade "schema" estão disponíveis na seção Dataset "schema" Property que se segue.

Formato da API

GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

Solicitação

A solicitação usa o URL codificado id URI do esquema (o valor do atributo "schemaRef.id") e requer um cabeçalho Accept.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \

O formato de resposta depende do tipo de cabeçalho Accept enviado na solicitação. As solicitações de pesquisa também exigem que version seja incluído no cabeçalho Aceitar. A tabela a seguir descreve os cabeçalhos Aceitos disponíveis para pesquisas:

Accept Descrição
application/vnd.adobe.xed-id+json Listar solicitações (GET), títulos, ids e versões
application/vnd.adobe.xed-full+json; version={major version} $refs e allOf resolvidos, tem títulos e descrições
application/vnd.adobe.xed+json; version={major version} Bruto com $ref e allOf, tem títulos e descrições
application/vnd.adobe.xed-notext+json; version={major version} Simples com $ref e allOf, sem títulos ou descrições
application/vnd.adobe.xed-full-notext+json; version={major version} $refs e allOf resolvidos, sem títulos ou descrições
application/vnd.adobe.xed-full-desc+json; version={major version} $refs e allOf resolvidos, descritores incluídos
OBSERVAÇÃO

application/vnd.adobe.xed-id+json e application/vnd.adobe.xed-full+json; version={major version} são os cabeçalhos Accept mais usados. application/vnd.adobe.xed-id+json é preferível para listar recursos no , Schema Registry pois retorna somente o "título", "id" e "versão". application/vnd.adobe.xed-full+json; version={major version} é preferível para visualizar um recurso específico (por sua "id"), pois retorna todos os campos (aninhados em "propriedades"), bem como títulos e descrições.

Resposta

O esquema JSON retornado descreve a estrutura e as informações de nível de campo ("type", "format", "Minimum", "maximum" etc.) dos dados, serializado como JSON. Se estiver usando um formato de serialização diferente de JSON para assimilação (como Parquet ou Scala), o Guia do Registro de Schema contém uma tabela que mostra o tipo JSON desejado ("meta:xdmType") e sua representação correspondente em outros formatos.

Junto com esta tabela, o Schema Registry Guia do Desenvolvedor contém exemplos aprofundados de todas as chamadas possíveis que podem ser feitas usando a API Schema Registry.

Propriedade "schema" do conjunto de dados (OBSOLETO - EOL 2019-05-30)

Os conjuntos de dados podem conter uma propriedade "schema" que agora está obsoleta e permanece disponível temporariamente para compatibilidade com versões anteriores. Por exemplo, uma solicitação de listagem (GET) semelhante à feita anteriormente, em que "schema" foi substituído por "schemaRef" no parâmetro de consulta properties, pode retornar o seguinte:

{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

Se a propriedade "schema" de um conjunto de dados for preenchida, isso indicará que o schema é um schema /xdms obsoleto e, onde suportado, o conector ETL deverá usar o valor na propriedade "schema" com o endpoint /xdms (um endpoint obsoleto no Catalog API) para recuperar o schema herdado.

Formato da API

GET /catalog/{"schema" property without the "@"}

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
OBSERVAÇÃO

Um parâmetro de consulta opcional, expansion=xdm, instrui a API a expandir e incorporar completamente todos os esquemas referenciados. Talvez você queira fazer isso ao apresentar uma lista de todos os campos em potencial ao usuário.

Resposta

Semelhante às etapas para visualizar esquema de conjunto de dados, a resposta contém um esquema JSON que descreve a estrutura e as informações de nível de campo dos dados, serializadas como JSON.

OBSERVAÇÃO

Quando o campo "schema" estiver vazio ou ausente totalmente, o conector deverá ler o campo "schemaRef" e usar a API do Registro de Schema, conforme mostrado nas etapas anteriores para exibir um esquema de conjunto de dados.

A propriedade "observableSchema"

A propriedade "observableSchema" de um conjunto de dados tem uma estrutura JSON correspondente à do JSON do esquema XDM. O "observableSchema" contém os campos que estavam presentes nos arquivos de entrada. Ao gravar dados em Experience Platform, não é necessário que o usuário use cada campo do schema de destino. Em vez disso, eles devem fornecer apenas os campos que estão sendo usados.

O schema observável é o schema que você usaria ao ler os dados ou apresentar uma lista de campos disponíveis para ler/mapear.

{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

Visualizar dados

O aplicativo ETL pode fornecer uma capacidade de visualização de dados ("Figura 8" no fluxo de trabalho ETL). A API de acesso aos dados fornece várias opções para a visualização dos dados.

Informações adicionais, incluindo orientação passo a passo para a visualização de dados usando a API de acesso aos dados, podem ser encontradas no tutorial de acesso a dados.

Obter detalhes do conjunto de dados usando o parâmetro de consulta "propriedades"

Conforme mostrado nas etapas acima para visualizar uma lista de conjuntos de dados, você pode solicitar "arquivos" usando o parâmetro de consulta "propriedades".

Você pode consultar a Visão geral do serviço de catálogo para obter informações detalhadas sobre a consulta de conjuntos de dados e filtros de resposta disponíveis.

Formato da API

GET /catalog/dataSets?limit={value}&properties={value}

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Resposta

A resposta incluirá um conjunto de dados (limit=1) que mostra a propriedade "files".

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files"
  }
}

Listar arquivos do conjunto de dados usando o atributo "arquivos"

Também é possível usar uma solicitação do GET para buscar detalhes do arquivo usando o atributo "files".

Formato da API

GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Resposta

A resposta inclui a ID do arquivo do conjunto de dados como a propriedade de nível superior, com detalhes do arquivo contidos no objeto de ID do arquivo do conjunto de dados.

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Buscar detalhes do arquivo

As IDs de arquivo do conjunto de dados retornadas na resposta anterior podem ser usadas em uma solicitação do GET para buscar mais detalhes do arquivo por meio da API Data Access.

A visão geral do acesso a dados contém detalhes sobre como usar a API Data Access.

Formato da API

GET /export/files/{DATASET_FILE_ID}

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Resposta

[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

Visualizar dados do arquivo

A propriedade "href" pode ser usada para buscar dados de visualização por meio do Data Access API.

Formato da API

GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

A resposta à solicitação acima conterá uma pré-visualização do conteúdo do arquivo.

Mais informações sobre a API Data Access, incluindo solicitações e respostas detalhadas, estão disponíveis na visão geral do acesso a dados.

Obter "fileDescription" do conjunto de dados

O componente de destino como saída de dados transformados, o engenheiro de dados escolherá um conjunto de dados de saída ("Figura 12" no fluxo de trabalho ETL). O esquema XDM está associado ao conjunto de dados de saída. Os dados a serem gravados serão identificados pelo atributo "fileDescription" da entidade do conjunto de dados das APIs de Descoberta de Dados. Essas informações podem ser buscadas usando uma ID de conjunto de dados ({DATASET_ID}). A propriedade "fileDescription" na resposta JSON fornecerá as informações solicitadas.

Formato da API

GET /catalog/dataSets/{DATASET_ID}
Propriedade Descrição
{DATASET_ID} O valor id do conjunto de dados que você está tentando acessar.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key : {API_KEY}"

Resposta

{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

Os dados serão gravados em Experience Platform usando API de assimilação de dados. A gravação de dados é um processo assíncrono. Quando os dados são gravados no Adobe Experience Platform, um lote é criado e marcado como um sucesso somente após os dados serem totalmente gravados.

Os dados em Experience Platform devem ser gravados na forma de arquivos Parquet.

Fase de execução

Conforme a execução é iniciada, o conector (conforme definido no componente de origem) lerá os dados de Experience Platform usando o Data Access API. O processo de transformação lerá os dados de um determinado intervalo de tempo. Internamente, ele consultará lotes de conjuntos de dados de origem. Ao fazer consultas, ele usará uma data inicial parametrizada (rolando para dados de séries de tempo ou dados incrementais) e listará arquivos de conjunto de dados para esses lotes e começará a fazer solicitações de dados para esses arquivos de conjunto de dados.

Exemplos de transformações

O documento de amostra de transformações de ETL contém várias transformações de exemplo, incluindo manuseio de identidade e mapeamentos de tipo de dados. Use essas transformações para referência.

Ler dados de Experience Platform

Usando o Catalog API, você pode buscar todos os lotes entre uma hora inicial e uma hora final especificadas e classificá-los pela ordem em que foram criados.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: application/json" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Detalhes sobre os lotes de filtragem podem ser encontrados no tutorial de Acesso a Dados.

Obter arquivos de um lote

Depois de ter a ID do lote que está procurando ({BATCH_ID}), é possível recuperar uma lista de arquivos pertencentes a um lote específico por meio do Data Access API. Os detalhes para fazer isso estão disponíveis no Data Access tutorial.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Acessar arquivos usando a ID do arquivo

Usando a ID exclusiva de um arquivo ({FILE_ID), o Data Access API pode ser usado para acessar os detalhes específicos do arquivo, incluindo seu nome, tamanho em bytes e um link para baixá-lo.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key : {API_KEY}"

A resposta pode apontar para um único arquivo ou um diretório. Os detalhes de cada um podem ser encontrados no Data Access tutorial.

Acessar conteúdo do arquivo

O Data Access API pode ser usado para acessar o conteúdo de um arquivo específico. Para buscar o conteúdo, uma solicitação do GET é feita usando o valor retornado para _links.self.href ao acessar um arquivo usando a ID do arquivo.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

A resposta a essa solicitação contém o conteúdo do arquivo . Para obter mais informações, incluindo detalhes sobre a paginação de resposta, consulte o tutorial Como consultar dados por meio da API de acesso a dados .

Validar registros para conformidade de esquema

Quando os dados são gravados, os usuários podem optar por validar os dados de acordo com as regras de validação definidas no esquema XDM. Mais informações sobre a validação do esquema podem ser encontradas no ETL Ecosystem Integration Reference Code em GitHub.

Se estiver usando a implementação de referência encontrada em GitHub, você pode ativar a validação do esquema nesta implementação usando a propriedade do sistema -DenableSchemaValidation=true.

A validação pode ser executada para tipos XDM lógicos, usando atributos como minLength e maxlength para cadeias de caracteres, minimum e maximum para números inteiros e muito mais. O Guia do desenvolvedor da API do Registro de Schema contém uma tabela que descreve os tipos XDM e as propriedades que podem ser usadas para validação.

OBSERVAÇÃO

Os valores mínimo e máximo fornecidos para vários tipos integer são os valores MIN e MAX que o tipo pode suportar, mas esses valores podem ser restritos ainda mais aos mínimos e máximos de sua escolha.

Criar um lote

Depois que os dados forem processados, a ferramenta ETL gravará os dados em Experience Platform usando a API de assimilação em lote. Antes de serem adicionados a um conjunto de dados, os dados devem ser vinculados a um lote que será carregado posteriormente em um conjunto de dados específico.

Solicitação

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -d '{
        "datasetId":"{DATASET_ID}"
      }'

Detalhes para criar um lote, incluindo solicitações e respostas de amostra, podem ser encontrados na Visão geral da assimilação de lote.

Gravar no conjunto de dados

Depois de criar um novo lote com êxito, os arquivos podem ser carregados em um conjunto de dados específico. Vários arquivos podem ser publicados em um lote até que sejam promovidos. Os arquivos podem ser carregados usando a API de upload de arquivo pequeno; no entanto, se os arquivos forem muito grandes e o limite do gateway for excedido, você poderá usar a API de upload de arquivo grande. Os detalhes para usar o Upload de arquivo grande e pequeno podem ser encontrados na Visão geral da assimilação de lote.

Solicitação

Os dados em Experience Platform devem ser gravados na forma de arquivos Parquet.

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/dataSets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id:{IMS_ORG}" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -H "x-api-key: API_KEY" \
  -H "content-type: application/octet-stream" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Marcar upload em lote concluído

Depois que todos os arquivos tiverem sido carregados no lote, o lote poderá ser sinalizado para conclusão. Ao fazer isso, as entradas Catalog "DataSetFile" são criadas para os arquivos concluídos e associadas ao lote gerado. O lote Catalog é então marcado como bem-sucedido, o que aciona os fluxos de downstream para assimilar os dados disponíveis.

Os dados chegarão primeiro ao local de preparo no Adobe Experience Platform e serão movidos para o local final após a catalogação e validação. Os lotes serão marcados como bem-sucedidos assim que todos os dados forem movidos para um local permanente.

Solicitação

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Se bem-sucedido, a resposta retornará HTTP Status 200 OK e o corpo da resposta estará vazio.

A ferramenta ETL deve observar o carimbo de data e hora dos conjuntos de dados de origem conforme os dados são lidos.

Na próxima execução da transformação, provavelmente por invocação de agendamento ou evento, o ETL começará a solicitar os dados do carimbo de data e hora salvo anteriormente e todos os dados a partir de então.

Obter o status do último lote

Antes de executar novas tarefas na ferramenta ETL, verifique se o último lote foi concluído com êxito. O Catalog Service API fornece uma opção específica para cada lote que fornece os detalhes dos lotes relevantes.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Resposta

Novas tarefas podem ser agendadas se o valor do "status" do lote anterior for "bem-sucedido", conforme mostrado abaixo:

"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Obter o status do último lote por ID

Um status de lote individual pode ser recuperado por meio de Catalog Service API, emitindo uma solicitação de GET usando {BATCH_ID}. O {BATCH_ID} usado seria o mesmo que o ID retornado quando o lote era criado.

Solicitação

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Resposta - Sucesso

A resposta a seguir mostra um "sucesso":

"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Resposta - Falha

Em caso de falha, os "erros" podem ser extraídos da resposta e aparecer na ferramenta ETL como mensagens de erro.

"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

Dados e eventos incrementais vs instantâneos vs perfis

Os dados podem ser representados em uma matriz dois por dois da seguinte maneira:

Eventos incrementais Perfis incrementais
Eventos de instantâneo (menos provável) Perfis de instantâneo

Os dados do evento normalmente são quando há colunas de carimbo de data e hora indexadas em cada linha.

Os dados do perfil normalmente são quando não há um carimbo de data e hora nos dados e cada linha pode ser identificada por uma chave primária/composta.

Os dados incrementais são o local onde somente os dados novos/atualizados entram no sistema e anexam aos dados atuais nos conjuntos de dados.

Dados de instantâneo são quando todos os dados entram no sistema e substituem alguns ou todos os dados anteriores em um conjunto de dados.

No caso de eventos incrementais, a ferramenta ETL deve usar as datas disponíveis/criar a data da entidade em lote. No caso do serviço de push, as datas disponíveis não estarão presentes, portanto, a ferramenta usará a data de criação/atualização do lote para marcação de incrementos. Todo lote de eventos incrementais deve ser processado.

Para perfis incrementais, a ferramenta ETL usará datas criadas/atualizadas da entidade em lote. Geralmente, cada lote de dados de perfil incrementais deve ser processado.

Os eventos de instantâneo são muito menos prováveis devido ao tamanho absoluto dos dados. Mas se isso for necessário, a ferramenta ETL deve selecionar apenas o último lote para processamento.

Quando perfis de instantâneo são usados, a ferramenta ETL terá que selecionar o último lote de dados que chegou ao sistema. Mas se o requisito for monitorar as versões das alterações, todos os lotes serão processados. O processamento de desduplicação no processo ETL ajudará a controlar os custos de armazenamento.

Reprodução em lote e reprocessamento de dados

A reprodução em lote e o reprocessamento de dados podem ser necessários nos casos em que um cliente descubra que, nos últimos "n" dias, os dados que estão sendo processados ETL não ocorreram como esperado ou os dados de origem podem não ter sido corretos.

Para fazer isso, os administradores de dados do cliente usarão a interface Platform para remover os lotes que contêm dados corrompidos. Em seguida, o ETL provavelmente precisará ser executado novamente, preenchendo-o novamente com os dados corretos. Se a fonte em si tiver dados corrompidos, o engenheiro/administrador de dados precisará corrigir os lotes de origem e assimilar novamente os dados (no Adobe Experience Platform ou por meio de conectores ETL).

Com base no tipo de dados que está sendo gerado, será a opção do engenheiro de dados remover um único lote ou todos os lotes de determinados conjuntos de dados. Os dados serão removidos/arquivados de acordo com as diretrizes Experience Platform.

É provável que a funcionalidade ETL para limpar dados seja importante.

Quando a limpeza for concluída, os administradores do cliente precisarão reconfigurar o Adobe Experience Platform para reiniciar o processamento dos serviços principais a partir do momento em que os lotes forem excluídos.

Processamento em lote simultâneo

A critério do cliente, os administradores/engenheiros de dados podem decidir extrair, transformar e carregar dados de forma sequencial ou simultânea, dependendo das características de um conjunto de dados específico. Isso também se baseará no caso de uso que o cliente está direcionando com os dados transformados.

Por exemplo, se o cliente persistir em um armazenamento de persistência atualizável e a sequência ou a ordem dos eventos for importante, o cliente pode precisar processar trabalhos estritamente com transformações de ETL sequenciais.

Em outros casos, os dados fora de ordem podem ser processados por aplicativos/processos downstream que classificam internamente usando um carimbo de data/hora especificado. Nesses casos, as transformações paralelas de ETL podem ser viáveis para melhorar os tempos de processamento.

Para lotes de origem, ele novamente dependerá da preferência do cliente e da restrição do consumidor. Se os dados de origem puderem ser coletados em paralelo sem considerar a regência/pedido de uma linha, o processo de transformação poderá criar lotes de processos com um grau mais alto de paralelismo (otimização baseada em processamento fora de ordem). Mas, se a transformação tiver que honrar os carimbos de data e hora ou alterar a ordem de precedência, a API de acesso aos dados ou o agendador/invocação da ferramenta ETL terão que garantir que os lotes não sejam processados fora de ordem sempre que possível.

Adiamento

Adiamento é um processo no qual os dados de entrada ainda não estão completos o suficiente para serem enviados para processos downstream, mas podem ser utilizáveis no futuro. Os clientes determinarão sua tolerância individual para a janela de dados para correspondência futura versus o custo de processamento para informar sua decisão de colocar dados de lado e reprocessá-los na próxima execução de transformação, na esperança de que possam ser enriquecidos e reconciliados/compilados em algum momento futuro dentro da janela de retenção. Esse ciclo está em andamento até que a linha seja processada o suficiente ou seja considerado obsoleto para continuar investindo no. Cada iteração gerará dados adiados que são um superconjunto de todos os dados adiados em iterações anteriores.

A Adobe Experience Platform não identifica dados adiados no momento, portanto, as implementações do cliente devem depender das configurações manuais do ETL e do Conjunto de Dados para criar outro conjunto de dados em Platform espelhando o conjunto de dados de origem que pode ser usado para manter dados adiados. Nesse caso, os dados adiados serão semelhantes aos dados do instantâneo. Em cada execução da transformação de ETL, os dados de origem serão unidos com dados adiados e enviados para processamento.

Changelog

Data Ação Descrição
2019-01-2019 Remoção da propriedade "campos" dos conjuntos de dados Anteriormente, os conjuntos de dados incluíam uma propriedade "fields" que continha uma cópia do esquema. Esse recurso não deve mais ser usado. Se a propriedade "fields" for encontrada, ela deverá ser ignorada e, em vez disso, "observationSchema" ou "schemaRef" deverá ser usado.
2019-03-2015 propriedade "schemaRef" adicionada aos conjuntos de dados A propriedade "schemaRef" de um conjunto de dados contém um URI que faz referência ao esquema XDM no qual o conjunto de dados se baseia e representa todos os campos em potencial que podem ser usados pelo conjunto de dados.
2019-03-2015 Todos os identificadores de usuários finais mapeiam para a propriedade "identityMap" O "identityMap" é um encapsulamento de todos os identificadores exclusivos de um assunto, como ID do CRM, ECID ou ID do programa de fidelidade. Este mapa é usado por Identity Service para resolver todas as identidades conhecidas e anônimas de um assunto, formando um único gráfico de identidade para cada usuário final.
2019-05-30 EOL e Remover a propriedade "schema" dos conjuntos de dados A propriedade "schema" do conjunto de dados forneceu um link de referência para o esquema usando o endpoint /xdms obsoleto na API Catalog. Isso foi substituído por um "schemaRef" que fornece o "id", "version" e "contentType" do schema, conforme referenciado na nova API Schema Registry.

Nesta página