Para se conectar a um destino, é necessário Gerenciar destinos permissão de controle de acesso.
Para ativar os dados, é necessário Gerenciar destinos, Ativar destinos, Exibir perfis e Exibir segmentos permissões de controle de acesso.
Leia o visão geral do controle de acesso ou entre em contato com o administrador do produto para obter as permissões necessárias.
Este tutorial demonstra como usar chamadas de API para se conectar aos dados do Adobe Experience Platform, criar uma conexão com um destino de armazenamento da nuvem de streaming (Amazon Kinesis ou Hubs de Eventos do Azure), crie um fluxo de dados para o novo destino criado e ative os dados para o 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 preferir usar a interface do usuário no Platform para se conectar a um destino e ativar dados, consulte o Conectar um destino e Ativar os dados do público-alvo para os destinos de exportação do segmento de fluxo tutoriais.
Este guia requer uma compreensão funcional dos seguintes componentes do Adobe Experience Platform:
As seções a seguir fornecem informações adicionais que você precisará saber para ativar dados para destinos de transmissão na plataforma.
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.
accessKeyId
, secretKey
, region
ou connectionUrl
sasKeyName
, sasKey
, namespace
Este tutorial 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 exemplos de chamadas de API no guia de solução de problemas do Experience Platform.
Para fazer chamadas para APIs da plataforma, primeiro conclua 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 do Experience Platform, conforme mostrado abaixo:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Os recursos no Experience Platform podem ser isolados para sandboxes virtuais específicas. Em solicitações para APIs da plataforma, é possível especificar o nome e a ID da sandbox em que a operação ocorrerá. Esses são parâmetros opcionais.
{SANDBOX_NAME}
Para obter mais informações sobre sandboxes no Experience Platform, consulte o 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 de tipo de mídia adicional:
application/json
Você pode encontrar a documentação de referência complementar para todas as chamadas de API neste tutorial no Swagger. Consulte a Documentação da API do Serviço de fluxo no Adobe I/O. Recomendamos que você use este tutorial e a página de documentação do Swagger em paralelo.
Como primeiro passo, você deve decidir para qual destino de transmissão ativar os dados. Para começar, execute uma chamada para solicitar uma lista de destinos disponíveis para os quais você pode conectar e ativar segmentos. Execute a seguinte solicitação de GET para o connectionSpecs
endpoint 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: {ORG_ID}' \
--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, como ele será necessário em outras etapas. Por exemplo, se você deseja se conectar e entregar 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",
...
...
}
Em seguida, você deve se conectar aos dados do Experience Platform, para que possa exportar os dados do perfil e ativá-los no destino preferido. É composto por duas subetapas descritas abaixo.
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: {ORG_ID}' \
--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 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Resposta
Uma resposta bem-sucedida contém o identificador exclusivo da conexão base (id
). Armazene esse valor conforme for necessário na próxima etapa para criar a conexão de origem.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
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: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connecting to 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 - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo (id
) para a conexão de origem recém-criada com o Serviço de perfil. Isso confirma que você se conectou com êxito aos dados de Experience Platform. Armazene esse valor conforme for necessário em uma etapa posterior.
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
Nesta etapa, você está configurando uma conexão com o destino de transmissão desejado. É composto por duas subetapas descritas abaixo.
Formato da API
POST /connections
Solicitação
O exemplo abaixo inclui comentários de código com o prefixo //
. Esses comentários destacam onde valores diferentes devem ser usados para destinos de transmissão diferentes. Remova os comentários antes de usar o trecho.
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: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connection for Amazon Kinesis/ Azure Event Hubs",
"description": "summer advertising 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 de destinos disponíveis.{AUTHENTICATION_CREDENTIALS}
: preencha o nome do seu destino de transmissão: Aws Kinesis authentication credentials
ou Azure EventHub authentication credentials
.{ACCESS_ID}
: Para Amazon Kinesis conexões. Sua ID de acesso para o local de armazenamento do Amazon Kinesis.{SECRET_KEY}
: Para Amazon Kinesis conexões. Sua chave secreta para o local de armazenamento do Amazon Kinesis.{REGION}
: Para Amazon Kinesis conexões. A região em seu Amazon Kinesis , onde a Platform fará o stream de seus dados.{SAS_KEY_NAME}
: Para Azure Event Hubs conexões. Preencha o nome da chave SAS. Saiba mais sobre como autenticar para Azure Event Hubs com chaves SAS no Documentação do Microsoft.{SAS_KEY}
: Para Azure Event Hubs conexões. Preencha a chave SAS. Saiba mais sobre como autenticar para Azure Event Hubs com chaves SAS no Documentação do Microsoft.{EVENT_HUB_NAMESPACE}
: Para Azure Event Hubs conexões. Preencha o Azure Event Hubs namespace, onde a Platform fará o stream de seus dados. Para obter mais informações, consulte Criar um namespace de Hubs de eventos no Microsoft documentação.Resposta
Uma resposta bem-sucedida contém o identificador exclusivo da conexão base (id
). Armazene esse valor conforme for necessário na próxima etapa para criar uma conexão de destino.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
Formato da API
POST /targetConnections
Solicitação
O exemplo abaixo inclui comentários de código com o prefixo //
. Esses comentários destacam onde valores diferentes devem ser usados para destinos de transmissão diferentes. Remova os comentários antes de usar o trecho.
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: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Amazon Kinesis/ Azure Event Hubs target connection",
"description": "Connection to Amazon Kinesis/ Azure Event Hubs",
"baseConnectionId": "{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 a especificação de conexão obtida na etapa Obtenha a lista de destinos disponíveis.{NAME_OF_DATA_STREAM}
: Para Amazon Kinesis conexões. Forneça o nome do seu fluxo de dados existente no Amazon Kinesis conta. A Platform exportará dados para esse fluxo.{REGION}
: Para Amazon Kinesis conexões. A região na sua conta Amazon Kinesis, onde a Platform fará o stream dos dados.{EVENT_HUB_NAME}
: Para Azure Event Hubs conexões. Preencha o Azure Event Hub nomeie o local onde a Platform fará o fluxo de seus dados. Para obter mais informações, consulte Criar um hub de eventos no Microsoft documentação.Resposta
Uma resposta bem-sucedida retorna o identificador exclusivo (id
) para a conexão de destino recém-criada para o seu destino de transmissão. Armazene esse valor conforme for necessário em etapas posteriores.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
Usando as IDs obtidas nas etapas anteriores, agora é possível criar um fluxo de dados entre os dados do Experience Platform e o destino para o qual você ativará os dados. Pense nessa etapa como construindo o pipeline, por meio 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 de POST, conforme mostrado abaixo, fornecendo os valores mencionados abaixo dentro da carga útil.
Execute a seguinte solicitação do 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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Azure Event Hubs",
"description": "Azure Event Hubs",
"flowSpec": {
"id": "{FLOW_SPEC_ID}",
"version": "1.0"
},
"sourceConnectionIds": [
"{SOURCE_CONNECTION_ID}"
],
"targetConnectionIds": [
"{TARGET_CONNECTION_ID}"
],
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
]
},
"segmentSelectors": {
"selectors": [
]
}
}
}
]
}
{FLOW_SPEC_ID}
: A ID de especificação de fluxo para destinos com base em perfil é 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 de destino obtida na etapa Conectar ao destino de transmissão.Resposta
Uma resposta bem-sucedida retorna a ID (id
) do fluxo de dados recém-criado e um etag
. Observe os dois valores. como você fará na próxima etapa, para ativar segmentos.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
Depois de criar todas as conexões e o fluxo de dados, agora você pode ativar os dados do seu perfil na plataforma de transmissão. Nesta 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 novo destino, você deve executar uma operação JSON PATCH, 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 o Especificação 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: {ORG_ID}' \
--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/profileSelectors/selectors/-",
"value": {
"type": "JSON_PATH",
"value": {
"operator": "EXISTS",
"path": "{PROFILE_ATTRIBUTE}"
}
}
}
]
Propriedade | Descrição |
---|---|
{DATAFLOW_ID} |
No URL, use a ID do fluxo de dados criado na etapa anterior. |
{ETAG} |
Obtenha o {ETAG} na resposta da etapa anterior, Criar um fluxo de dados. O formato de resposta na etapa anterior escapou das aspas. Você deve usar os valores sem escape no cabeçalho da solicitação. Veja o exemplo abaixo:
O valor da tag é atualizado com cada atualização bem-sucedida de um fluxo de dados. |
{SEGMENT_ID} |
Forneça a ID do segmento que deseja exportar para esse destino. Para recuperar IDs de segmento para os segmentos que você deseja ativar, consulte recuperar uma definição de segmento na referência da API do Experience Platform. |
{PROFILE_ATTRIBUTE} |
Por exemplo, "person.lastName" |
op |
A chamada de operação usada para definir a ação necessária para atualizar o fluxo de dados. As operações incluem: add , replace e remove . Para adicionar um segmento a um fluxo de dados, use o add operação. |
path |
Define a parte do fluxo que deve ser atualizada. Ao adicionar um segmento a um fluxo de dados, use o caminho especificado no exemplo. |
value |
O novo valor com o qual você deseja atualizar seu parâmetro. |
id |
Especifique a ID do segmento que você está adicionando ao fluxo de dados de destino. |
name |
Opcional. Especifique o nome do segmento que você está adicionando ao fluxo de dados de destino. Observe que este campo não é obrigatório e você pode adicionar um segmento com êxito ao fluxo de dados de destino sem fornecer seu nome. |
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.
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 de 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: {ORG_ID}' \
--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
os segmentos e os atributos do perfil que você enviou na etapa anterior. Uma amostra transformations
na resposta, pode ser a 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 em AWS Kinesis e Azure Event Hubs também incluirá informações sobre o mapa de identidade. Isso representa as identidades dos perfis exportados (por exemplo, ECID, ID móvel, Google ID, endereço de email etc.). Veja um exemplo abaixo.
{
"person": {
"email": "yourstruly@adobe.com"
},
"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"
}
]
}
}
Para se conectar aos destinos de transmissão descritos neste tutorial de forma mais simplificada, você pode usar Postman.
Postman é uma ferramenta que pode ser usada para fazer chamadas de API e gerenciar bibliotecas de chamadas e ambientes predefinidos.
Neste tutorial específico, as seguintes opções Postman as coleções foram anexadas:
Clique em here para baixar o arquivo de coleções.
Cada coleção inclui as solicitações necessárias e as variáveis de ambiente, para AWS Kinesise Azure Event Hub, respectivamente.
Para se conectar com sucesso aos destinos usando o Postman coleções, siga estas etapas:
Os endpoints de API neste tutorial seguem os princípios gerais da mensagem de erro da API de Experience Platform. Consulte Códigos de status da API e erros do cabeçalho da solicitação no guia de solução de problemas da plataforma para obter mais informações sobre a interpretação das respostas dos erros.
Ao seguir este tutorial, você conectou com sucesso a Plataforma a um de seus destinos de transmissão preferidos e configurou 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: