Show Menu
TÓPICOS×

Ingressar dados de parquet de um sistema de armazenamento em nuvem de terceiros usando a Flow Service API

Flow Service é usada para coletar e centralizar dados do cliente de várias fontes diferentes no Adobe Experience Platform. O serviço fornece uma interface de usuário e uma RESTful API a partir da qual todas as fontes compatíveis são conectáveis.
Este tutorial usa a Flow Service API para guiá-lo pelas etapas para assimilar dados de busca de um sistema de armazenamento em nuvem de terceiros.

Introdução

Este guia exige uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
  • Fontes : Experience Platform permite que os dados sejam ingeridos de várias fontes e, ao mesmo tempo, fornece a você a capacidade de estruturar, rotular e aprimorar os dados recebidos usando Platform serviços.
  • Caixas de proteção : Experience Platform fornece caixas de proteção virtuais que particionam uma única Platform instância em ambientes virtuais separados para ajudar a desenvolver e desenvolver aplicativos de experiência digital.
As seções a seguir fornecem informações adicionais que você precisará saber para assimilar com êxito os dados de busca de um armazenamento em nuvem de terceiros usando a Flow Service API.

Lendo chamadas de exemplo da API

Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e cargas de solicitação formatadas corretamente. O JSON de amostra retornado em respostas de API também é fornecido. Para obter informações sobre as convenções usadas na documentação para chamadas de API de amostra, consulte a seção sobre como ler chamadas de API de exemplo no guia de Experience Platform solução de problemas.

Reunir valores para cabeçalhos necessários

Para fazer chamadas para Platform APIs, você deve primeiro concluir 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 Experience Platform API, como 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, incluindo os pertencentes a Flow Service, são isolados para caixas de proteção virtuais específicas. Todas as solicitações para Platform APIs exigem um cabeçalho que especifique o nome da caixa de proteção em que a operação ocorrerá:
  • 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

Criar uma conexão

Para assimilar dados de busca usando Platform APIs, é necessário ter uma conexão válida para a fonte de armazenamento na nuvem de terceiros que você está acessando. Se você ainda não tiver uma conexão para o armazenamento com o qual deseja trabalhar, poderá criar uma através dos seguintes tutoriais:
Obtenha e armazene o identificador exclusivo ( $id ) da conexão e prossiga para a próxima etapa deste tutorial.

Criar um schema de público alvo

Para que os dados de origem sejam usados em Platform, um schema de público alvo também deve ser criado para estruturar os dados de origem de acordo com suas necessidades. O schema do público alvo é então usado para criar um Platform conjunto de dados no qual os dados de origem estão contidos.
Se você preferir usar a interface do usuário no Experience Platform, o tutorial do Editor de Schemas fornece instruções passo a passo para executar ações semelhantes no Editor de Schemas.
Formato da API
POST /schemaregistry/tenant/schemas

Solicitação
A solicitação de exemplo a seguir cria um schema XDM que estende a Individual Profile classe XDM.
curl -X POST \
    'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
    -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 'Content-Type: application/json' \
    -d '{
    "type": "object",
    "title": "Sample Demo Profile XDM {{$guid}}",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-subscriptions"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap"
        }
    ],
    "meta:containerId": "tenant",
    "meta:resourceType": "schemas",
    "meta:xdmType": "object",
    "meta:class": "https://ns.adobe.com/xdm/context/profile"
}'

Resposta
Uma resposta bem-sucedida retorna detalhes do schema recém-criado, incluindo seu identificador exclusivo ( $id ). Essa ID é necessária na próxima etapa para criar uma conexão de origem.
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
    "meta:altId": "_{TENANT_ID}.schemas.e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "Sample Demo Profile XDM 8d96a964-aad8-43c5-a73a-c8b9b1ccbfb1",
    "type": "object",
    "description": "",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-work-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-subscriptions",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/identitymap",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/context/profile-subscriptions",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/profile-work-details"
    ],
    "imsOrg": "{IMS_ORG}",
    "meta:extensible": false,
    "meta:abstract": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/xdm/context/profile-personal-details",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/context/profile-subscriptions",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/profile-work-details"
    ],
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1584673864341,
        "repo:lastModifiedDate": 1584673864341,
        "xdm:createdClientId": "{CREATED_CLIENT_ID}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT_ID}",
        "xdm:createdUserId": "{CREATED_USER_ID}",
        "xdm:lastModifiedUserId": "{MODIFIED_USER_ID}",
        "eTag": "fa704f80da907c8f0f66f453ffcac3e52958687edbf55d71231dc5e1522193c4"
    },
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:containerId": "tenant",
    "meta:tenantNamespace": "_{TENANT_ID}"
}

Criar uma conexão de origem

Com um schema XDM de público alvo criado, uma conexão de origem agora pode ser criada usando uma solicitação POST para a Flow Service API. Uma conexão de origem consiste em uma conexão para a API, um formato de dados de origem e uma referência para o schema XDM do público alvo recuperado na etapa anterior.
Formato da API
POST /sourceConnections

Solicitação
curl -X POST \
    'http://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
    -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 'Content-Type: application/json' \
    -d '{
        "name": "Source Connection S3 {{$guid}}",
        "baseConnectionId": "5831c52c-c261-4945-b1c5-2cc261d945b2",
        "connectionSpec": {
            "id": "ecadc60c-7455-4d87-84dc-2a0e293d997b",
            "version": 1
        },
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80",
                "id": "",
                "version": "application/vnd.adobe.xed-full+json;version=1.0"
            }
        },
        "params": {
            "path": "partners-demo/samples",
            "recursive": "true"
        }
    }'

Propriedade
Descrição
baseConnectionId
A conexão da API que representa o armazenamento da nuvem.
data.schema.id
O ( $id ) se o schema xdm do público alvo for recuperado na etapa anterior.
params.path
O caminho do arquivo de origem.
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da conexão de origem recém-criada. Armazene esse valor conforme necessário em etapas posteriores para criar uma conexão de público alvo.
{
    "id": "73bc8911-505a-4e46-bc89-11505a6e466f",
    "etag": "\"c4004435-0000-0200-0000-5e7437d90000\""
}

Criar uma conexão básica de conjunto de dados

Para ingerir dados externos em Platform, uma conexão de base de Experience Platform conjunto de dados deve ser adquirida primeiro.
Para criar uma conexão base de conjunto de dados, siga as etapas descritas no tutorial de conexão base de conjunto de dados.
Continue seguindo as etapas descritas no guia do desenvolvedor até que você tenha criado uma conexão base de conjunto de dados. Obtenha e armazene o identificador exclusivo ( $id ) e continue a usá-lo como a ID de conexão básica na próxima etapa para criar uma conexão de público alvo.

Criar um conjunto de dados de público alvo

É possível criar um conjunto de dados de público alvo executando uma solicitação POST para a API do serviço de catálogo, fornecendo a ID do schema do público alvo dentro da carga.
Formato da API
POST /catalog/dataSets

Solicitação
curl -X POST \
    'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
    -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 'Content-Type: application/json' \
    -d '{
        "name": "Leads Dataset {{$guid}}",
        "schemaRef": {
            "id": ""https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80"",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "fileDescription": {
            "format": "parquet"
        }
    }'

Propriedade
Descrição
schemaRef.id
A ID do schema XDM do público alvo.
Resposta
Uma resposta bem-sucedida retorna uma matriz que contém a ID do conjunto de dados recém-criado no formato "@/datasets/{DATASET_ID}" . A ID do conjunto de dados é uma sequência de caracteres somente leitura, gerada pelo sistema, usada para fazer referência ao conjunto de dados em chamadas de API. Armazene a ID do conjunto de dados do público alvo conforme necessário em etapas posteriores para criar uma conexão de público alvo e um fluxo de dados.
[
    "@/dataSets/5e7439b1ad55a618ad4c5102"
]

Criar uma conexão de público alvo

Agora você tem os identificadores exclusivos para uma conexão básica de conjunto de dados, um schema de público alvo e um conjunto de dados de público alvo. Usando esses identificadores, é possível criar uma conexão de público alvo usando a Flow Service API para especificar o conjunto de dados que conterá os dados de origem de entrada.
Formato da API
POST /targetConnections

Solicitação
curl -X POST \
    'http://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -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 'Content-Type: application/json' \
    -d '{
        "baseConnectionId": "291257e3-c560-4e07-9257-e3c5606e07d1",
        "connectionSpec": {
            "id":"c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        },
        "name": "Target Connection {{$guid}}",
        "data": {
            "format": "parquet_xdm",
            "schema": {
                "id": ""https://ns.adobe.com/{TENANT_ID}/schemas/e15530faf88aeb52d9ca5c5671a059f44f1a42ea7f5fdb80"",
                "version": "application/vnd.adobe.xed-full+json;version=1.0"
            }
        },
        "params": {
            "dataSetId": "5e7439b1ad55a618ad4c5102"
        }
    }'

Propriedade
Descrição
baseConnectionId
A ID da conexão básica do conjunto de dados.
data.schema.id
A $id do schema XDM do público alvo.
params.dataSetId
A ID do conjunto de dados do público alvo.
connectionSpec.id
A ID de especificação de conexão do seu armazenamento em nuvem.
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da nova conexão com o público alvo. Armazene esse valor conforme necessário em etapas posteriores.
{
    "id": "9b3abc95-f2e9-47c1-babc-95f2e927c1ec",
    "etag": "\"7501936b-0000-0200-0000-5e743bcc0000\""
}

Criar um fluxo de dados

A última etapa para assimilar dados de parquet de um armazenamento de nuvem de terceiros é criar um fluxo de dados. Agora, você tem os seguintes valores obrigatórios preparados:
Um fluxo de dados é responsável por programar e coletar dados de uma fonte. Você pode criar um fluxo de dados executando uma solicitação POST enquanto fornece os valores mencionados anteriormente na carga.
Formato da API
POST /flows

Solicitação
curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/flows' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Demo Parquet Ingestion Flow {{$guid}}",
        "flowSpec": {
            "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "73bc8911-505a-4e46-bc89-11505a6e466f"
        ],
        "targetConnectionIds": [
            "9b3abc95-f2e9-47c1-babc-95f2e927c1ec"
        ],
        "scheduleParams": {
            "startTime": {{$timestamp}},
            "frequency": "minute",
            "interval": 1000,
            "backfill": true
        }
    }'

Propriedade
Descrição
sourceConnectionIds
A ID da conexão de origem recuperada em uma etapa anterior.
targetConnectionIds
A ID de conexão do público alvo recuperada em uma etapa anterior.
Resposta
Uma resposta bem-sucedida retorna a ID ( id ) do fluxo de dados recém-criado.
{
    "id": "89ff50ef-b082-426e-bf50-efb082d26e78",
    "etag": "\"890070b8-0000-0200-0000-5e743c040000\""
}

Próximas etapas

Ao seguir este tutorial, você criou um conector de origem para coletar dados de parâmetros do sistema de armazenamentos em nuvem de terceiros de forma programada. Os dados recebidos agora podem ser usados por Platform serviços de downstream, como Real-time Customer Profile e Data Science Workspace. Consulte os seguintes documentos para obter mais detalhes: