Show Menu
TÓPICOS×

Conecte-se aos destinos de streaming e ative os dados no Platform de dados do cliente em tempo real da Adobe usando APIs

Os destinos Amazon Kinesis e Azure Event Hubs no Adobe Real-time CDP estão atualmente em beta. A documentação e a funcionalidade estão sujeitas a alterações.
Este tutorial demonstra como usar chamadas de API para se conectar aos dados do seu Adobe Experience Platform, criar uma conexão com um destino de armazenamento de nuvem de fluxo ( Amazon Kinesis ou Azure Evento Hubs ), criar um fluxo de dados para o seu novo destino criado e ativar os dados para o seu novo destino criado.
Este tutorial usa o Amazon Kinesis destino em todos os exemplos, mas as etapas são idênticas para Azure Event Hubs.
Se você preferir usar a interface do usuário no CDP em tempo real da Adobe para se conectar a um destino e ativar dados, consulte o Connect um destino e Ativar perfis e segmentos em tutoriais de destino .

Comece já

Este guia exige uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
  • Sistema do Experience Data Model (XDM): A estrutura padronizada pela qual o Experience Platform organiza os dados de experiência do cliente.
  • Serviço de catálogo: Catálogo é o sistema de registro para localização de dados e linhagem dentro do Experience Platform.
  • Caixas de proteção : O Experience Platform fornece caixas de proteção virtuais que particionam uma única instância do Platform 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 ativar os dados para o streaming de destinos no Adobe Real-time CDP.

Reunir credenciais obrigatórias

Para concluir as etapas neste tutorial, você deve ter as seguintes credenciais prontas, dependendo do tipo de destinos aos quais você está conectando e ativando segmentos.
  • Para Amazon Kinesis conexões: accessKeyId , secretKey , region ou connectionUrl
  • Para Azure Event Hubs conexões: sasKeyName , sasKey , namespace

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 solução de problemas do Experience Platform.

Coletar valores para cabeçalhos obrigatórios e opcionais

Para fazer chamadas para as APIs da Platform, 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 API de Experience Platform, como mostrado abaixo:
  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Os recursos no Experience Platform podem ser isolados para caixas de proteção virtuais específicas. Em solicitações para APIs da Platform, você pode especificar o nome e a ID da caixa de proteção em que a operação ocorrerá. Esses são parâmetros 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 do Swagger

Você pode encontrar a documentação de referência para todas as chamadas de API neste tutorial no Swagger. Consulte a documentação da API do Serviço de Fluxo no Adobe.io . Recomendamos que você use este tutorial e a página de documentação do Swagger em paralelo.

Obtenha a lista dos destinos de streaming disponíveis

Como primeira etapa, você deve decidir para qual destino de fluxo deve ativar os dados. Para começar, execute uma chamada para solicitar uma lista de destinos disponíveis aos quais você possa se conectar e ativar segmentos. Execute a seguinte solicitação GET ao connectionSpecs ponto de extremidade para retornar uma lista de destinos disponíveis:
Formato da API
GET /connectionSpecs

Solicitação
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Resposta
Uma resposta bem-sucedida contém uma lista de destinos disponíveis e seus identificadores exclusivos ( id ). Armazene o valor do destino que você planeja usar, pois ele será necessário em outras etapas. Por exemplo, se você deseja conectar e fornecer segmentos para Amazon Kinesis ou Azure Event Hubs, procure o seguinte trecho na resposta:
{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

Conecte-se aos seus dados de Experience Platform

Em seguida, você deve se conectar aos dados do Experience Platform para poder exportar os dados do perfil e ativá-los no destino preferencial. Este conjunto consiste em duas etapas descritas abaixo.
  1. Primeiro, você deve executar uma chamada para autorizar o acesso aos seus dados no Experience Platform, configurando uma conexão básica.
  2. Em seguida, usando a ID de conexão básica, você fará outra chamada na qual você cria uma conexão de origem, que estabelece a conexão com seus dados de Experience Platform.

Autorizar acesso aos seus dados no Experience Platform

Formato da API
POST /connections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME} \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão para o serviço de Perfil unificado - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
Resposta
Uma resposta bem-sucedida contém o identificador exclusivo ( id ) da conexão base. Armazene esse valor conforme necessário na próxima etapa para criar a conexão de origem.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Conecte-se aos seus dados de Experience Platform

Formato da API
POST /sourceConnections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Unified Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "json"
            },
            "params" : {}
}'

  • {BASE_CONNECTION_ID} : Use a ID obtida na etapa anterior.
  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão para o serviço de Perfil unificado - 8a9c3494-9708-43d7-ae3f-cda01e5030e1 .
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da conexão de origem recém-criada ao Serviço de Perfil Unificado. Isso confirma que você se conectou com êxito aos dados de Experience Platform. Armazene esse valor conforme necessário em uma etapa posterior.
{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Conectar ao destino de streaming

Nesta etapa, você está configurando uma conexão com o destino de streaming desejado. Este conjunto consiste em duas etapas descritas abaixo.
  1. Primeiro, você deve executar uma chamada para autorizar o acesso ao destino de streaming, configurando uma conexão básica.
  2. Em seguida, usando a ID de conexão básica, você fará outra chamada na qual criará uma conexão de público alvo, que especifica o local em sua conta de armazenamento onde os dados exportados serão entregues, bem como o formato dos dados que serão exportados.

Autorizar acesso ao destino de streaming

Formato da API
POST /connections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connection for Amazon Kinesis/ Azure Event Hubs",
    "description": "your company's holiday campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{AUTHENTICATION_CREDENTIALS}",
        "params": { // use these values for Amazon Kinesis connections
            "accessKeyId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}",
            "region": "{REGION}"
        },
        "params": { // use these values for Azure Event Hubs connections
            "sasKeyName": "{SAS_KEY_NAME}",
            "sasKey": "{SAS_KEY}",
            "namespace": "{EVENT_HUB_NAMESPACE}"
        }        
    }
}'

  • {CONNECTION_SPEC_ID} : Use a ID de especificação de conexão obtida na etapa Obtenha a lista dos destinos disponíveis.
  • {AUTHENTICATION_CREDENTIALS} : preencha o nome do seu destino de streaming, por exemplo: Amazon Kinesis authentication credentials ou Azure Event Hubs authentication credentials .
  • {ACCESS_ID} : Para conexões Amazon Kinesis. Sua ID de acesso para a localização do armazenamento Amazon Kinesis.
  • {SECRET_KEY} : Para conexões Amazon Kinesis. Sua chave secreta para a localização do seu armazenamento Amazon Kinesis.
  • {REGION} : Para conexões Amazon Kinesis. A região em sua conta Amazon Kinesis na qual o Adobe Real-time CDP fará o stream dos seus dados.
  • {SAS_KEY_NAME} : Para conexões de Hubs de Evento do Azure. Preencha o nome da chave SAS. Saiba mais sobre como autenticar Azure Event Hubs com chaves SAS na documentação da Microsoft.
  • {SAS_KEY} : Para conexões de Hubs de Evento do Azure. Preencha sua chave SAS. Saiba mais sobre como autenticar Azure Event Hubs com chaves SAS na documentação da Microsoft.
  • {EVENT_HUB_NAMESPACE} : Para conexões de Hubs de Evento do Azure. Preencha a namespace dos Hubs do Evento do Azure onde a CDP em tempo real da Adobe fará o stream dos seus dados. Para obter mais informações, consulte Criar uma namespace de Hubs de Evento na documentação da Microsoft.
Resposta
Uma resposta bem-sucedida contém o identificador exclusivo ( id ) da conexão base. Armazene esse valor conforme necessário na próxima etapa para criar uma conexão de público alvo.
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Especificar a localização do armazenamento e o formato dos dados

Formato da API
POST /targetConnections

Solicitação
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Amazon Kinesis/ Azure Event Hubs target connection",
    "description": "Connection to Amazon Kinesis/ Azure Event Hubs",
    "baseConnection": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json",
    },
    "params": { // use these values for Amazon Kinesis connections
        "stream": "{NAME_OF_DATA_STREAM}", 
        "region": "{REGION}"
    },
    "params": { // use these values for Azure Event Hubs connections
        "eventHubName": "{EVENT_HUB_NAME}"
    }
}'

  • {BASE_CONNECTION_ID} : Use a ID de conexão básica obtida na etapa acima.
  • {CONNECTION_SPEC_ID} : Use as especificações de conexão obtidas na etapa Obtenha a lista dos destinos disponíveis.
  • {NAME_OF_DATA_STREAM} : Para conexões Amazon Kinesis. Forneça o nome do seu fluxo de dados existente na sua conta da Amazon Kinesis. A CDP em tempo real da Adobe exportará dados para esse fluxo.
  • {REGION} : Para conexões Amazon Kinesis. A região em sua conta Amazon Kinesis na qual o Adobe Real-time CDP fará o stream dos seus dados.
  • {EVENT_HUB_NAME} : Para conexões de Hubs de Evento do Azure. Preencha o nome do Hub do Evento do Azure no qual a CDP em tempo real da Adobe fará o stream dos seus dados. Para obter mais informações, consulte Criar um hub de eventos na documentação da Microsoft.
Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo ( id ) da conexão de público alvo recém-criada para o destino de streaming. Armazene esse valor conforme necessário em etapas posteriores.
{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

Criar um fluxo de dados

Usando as IDs obtidas nas etapas anteriores, agora é possível criar um fluxo de dados entre seus dados de Experience Platform e o destino para o qual você ativará os dados. Pense nessa etapa como construindo o pipeline, através do qual os dados fluirão posteriormente, entre o Experience Platform e o destino desejado.
Para criar um fluxo de dados, execute uma solicitação POST, como mostrado abaixo, enquanto fornece os valores mencionados abaixo dentro da carga.
Execute a seguinte solicitação POST para criar um fluxo de dados.
Formato da API
POST /flows

Solicitação
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "Create dataflow to Amazon Kinesis/ Azure Event Hubs",
        "description": "This operation creates a dataflow to Amazon Kinesis/ Azure Event Hubs",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ]
    }

  • {FLOW_SPEC_ID} : A ID de especificação de fluxo para destinos baseados em perfis é 71471eba-b620-49e4-90fd-23f1fa0174d8 . Use esse valor na chamada.
  • {SOURCE_CONNECTION_ID} : Use a ID de conexão de origem obtida na etapa Conecte-se ao seu Experience Platform .
  • {TARGET_CONNECTION_ID} : Use a ID de conexão do público alvo obtida na etapa Conectar ao destino de streaming.
Resposta
Uma resposta bem-sucedida retorna a ID ( id ) do fluxo de dados recém-criado e um etag . Anote os dois valores. como você os fará na próxima etapa, para ativar segmentos.
{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

Ativar dados para o novo destino

Depois de criar todas as conexões e o fluxo de dados, agora você pode ativar os dados do perfil na plataforma de streaming. Nessa etapa, você seleciona quais segmentos e quais atributos de perfil está enviando para o destino e pode agendar e enviar dados para o destino.
Para ativar segmentos no seu novo destino, é necessário executar uma operação PATCH JSON, semelhante ao exemplo abaixo. Você pode ativar vários segmentos e atributos de perfil em uma chamada. Para saber mais sobre o JSON PATCH, consulte a especificação rfc6902 RFC.
Formato da API
PATCH /flows

Solicitação
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    },
        },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]

  • {DATAFLOW_ID} : Use o fluxo de dados obtido na etapa anterior.
  • {ETAG} : Use a tag obtida na etapa anterior.
  • {SEGMENT_ID} : Forneça a ID do segmento que deseja exportar para esse destino. Para recuperar IDs de segmento dos segmentos que você deseja ativar, vá para https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/, selecione API do Serviço de Segmentação no menu de navegação esquerdo e procure a GET /segment/jobs operação.
  • {PROFILE_ATTRIBUTE} : Por exemplo, personalEmail.address ou person.lastName
Resposta
Procure uma resposta 202 OK. Nenhum corpo de resposta é retornado. Para validar se a solicitação estava correta, consulte a próxima etapa, Validar o fluxo de dados.

Validar o fluxo de dados

Como etapa final do tutorial, você deve validar se os segmentos e os atributos do perfil foram corretamente mapeados para o fluxo de dados.
Para validar isso, execute a seguinte solicitação GET:
Formato da API
GET /flows

Solicitação
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"' 

  • {DATAFLOW_ID} : Use o fluxo de dados da etapa anterior.
  • {ETAG} : Use a tag da etapa anterior.
Resposta
A resposta retornada deve incluir no transformations parâmetro os segmentos e os atributos do perfil enviados na etapa anterior. Um exemplo de transformations parâmetro na resposta pode ser parecido com o seguinte:
"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                        "selectors": [
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "personalEmail.address",
                                    "operator": "EXISTS"
                                }
                            },
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "person.lastname",
                                    "operator": "EXISTS"
                                }
                            }
                        ]
                    },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

Dados exportados
Além dos atributos do perfil e dos segmentos na etapa Ativar dados para o novo destino , os dados exportados nos Hubs de Eventos AWS Kinesis e Azure também incluirão informações sobre o mapa de identidade. Isso representa a identidade dos perfis exportados (por exemplo, ECID , ID móvel, ID do Google, endereço de email etc.). Veja um exemplo abaixo.
{
  "person": {
    "email": "yourstruly@adobe.con"
  },
  "segmentMembership": {
    "ups": {
      "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
        "lastQualificationTime": "2020-03-03T21:24:39Z",
        "status": "exited"
      },
      "7841ba61-23c1-4bb3-a495-00d695fe1e93": {
        "lastQualificationTime": "2020-03-04T23:37:33Z",
        "status": "existing"
      }
    }
  },
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

Próximas etapas

Ao seguir este tutorial, você conectou com êxito o CDP em tempo real a um dos destinos de streaming preferidos e configura um fluxo de dados para o respectivo destino. Os dados de saída agora podem ser usados no destino para análises de clientes ou quaisquer outras operações de dados que você desejar executar. Consulte as seguintes páginas para obter mais detalhes: