Fontes de dados externas external-data-sources
Fontes de dados externas permitem definir uma conexão com sistemas de terceiros, por exemplo, se você estiver usando um sistema de reserva de hotel para verificar se a pessoa reservou um quarto. Ao contrário da fonte de dados integrada da Adobe Experience Platform, você pode criar quantas fontes de dados externas forem necessárias.
As APIs REST que usam POST ou GET e devolvem JSON são compatíveis. A chave de API, os modos de autenticação básicos e personalizados são compatíveis.
Vamos ver o exemplo de um serviço de API meteorológica usada para personalizar os comportamentos da jornada de acordo com os dados climáticos em tempo real.
Dois exemplos da chamada de API:
- https://api.adobeweather.org/weather?city=London,uk&appid=1234
- https://api.adobeweather.org/weather?lat=35&lon=139&appid=1234
A chamada é composta de um URL principal (https://api.adobeweather.org/weather), dois conjuntos de parâmetros ("city" para a cidade e "lat/long" para a latitude e a longitude) e a chave da API (appid).
Estas são as principais etapas para criar e configurar uma nova fonte de dados externa:
-
Na lista de fontes de dados, clique em Criar fonte de dados para criar uma nova fonte de dados externa.
Essa ação abre o painel de configuração da fonte de dados no lado direito da tela.
-
Insira um nome para a sua fonte de dados.
note note NOTE Não use espaços ou caracteres especiais. Não use mais de 30 caracteres. -
Adicione uma descrição à fonte de dados. Esta etapa é opcional.
-
Adicione o URL do serviço externo. Em nosso exemplo: https://api.adobeweather.org/weather.
note caution CAUTION Recomendamos o uso de HTTPS por motivos de segurança. Observe também que não permitimos o uso de endereços da Adobe que não estejam disponíveis publicamente, bem como o uso de endereços IP. 
-
Configure a autenticação dependendo da configuração do serviço externo: Sem autenticação, Básico, Personalizado ou Chave de API.
Para o modo de autenticação básico, é necessário preencher um nome de usuário e uma senha.
note note NOTE Quando a chamada de autenticação for realizada, a variável <username>:<password>A string, codificada em base64, é adicionada no cabeçalho Autenticação.Para obter mais informações sobre o modo de autenticação personalizado, consulte nesta seção. No nosso exemplo, escolhemos o modo de autenticação da chave de API:
- Tipo: "Chave de API"
- Nome: "appid" (este é o nome do parâmetro da chave de API)
- Valor: "1234" (este é o valor da nossa chave de API)
- Localização: "Parâmetro de query" (a chave de API está localizada no URL)
-
Adicione um novo grupo de campos para cada conjunto de parâmetros da API clicando em Adicionar um novo grupo de campos. Não use espaços ou caracteres especiais no nome do grupo de campos. Em nosso exemplo, precisamos criar dois grupos de campo, um para cada conjunto de parâmetros (city e long/lat).
Para o conjunto de parâmetros "long/lat", criamos um grupo de campos com as seguintes informações:
-
Usado em: exibe o número de jornadas que usam um grupo de campos. Você pode clicar no link Exibir jornadas ícone para exibir a lista de jornadas usando este grupo de campos.
-
Método: selecione o método POST ou GET. No nosso caso, selecionamos o método GET.
-
Valores dinâmicos: insira os diferentes parâmetros separados por vírgula, "long,lat" no nosso exemplo. Como os valores dos parâmetros dependem do contexto de execução, eles serão definidos nas jornadas. Saiba mais
-
Carga de resposta: clique dentro do Carga e cole um exemplo da carga útil retornada pela chamada. Para nosso exemplo, usamos uma carga encontrada em um site da API de meteorologia. Verifique se os tipos de campo estão corretos. Cada vez que a API é chamada, o sistema recuperará todos os campos incluídos no exemplo de carga útil. Observe que você pode clicar em Colar uma nova carga se quiser alterar a carga útil transmitida no momento.
-
Conteúdo enviado: este campo não aparece no nosso exemplo. Ele só estará disponível se você selecionar o método POST. Cole a carga útil que será enviada para o sistema de terceiros.
No caso de uma chamada GET que exige parâmetros, você informa os parâmetros na variável Valores dinâmicos e são adicionados automaticamente no final da chamada. No caso de uma chamada POST, é necessário:
-
listar os parâmetros que serão transmitidos no momento da chamada no Valores dinâmicos (no exemplo abaixo: "identificador").
-
especificá-los também com a mesma sintaxe no corpo da carga útil enviada. Para fazer isso, é necessário adicionar: "param": "nome do parâmetro" (no exemplo abaixo: "identificador"). Siga a sintaxe abaixo:
code language-none {"id":{"param":"identifier"}}
Clique em Salvar.
A fonte de dados agora está configurada e pronta para ser usada em suas jornadas, por exemplo em suas condições ou para personalizar um email. Se a temperatura estiver acima de 30°C, você pode decidir enviar uma comunicação específica.
Modo de autenticação personalizado custom-authentication-mode
Esse modo de autenticação é usado para autenticação complexa, frequentemente usada para chamar protocolos de empacotamento de API como OAuth2, para recuperar um token de acesso que será inserido na solicitação real HTTP para a ação.
Ao configurar a autenticação personalizada, você pode clicar no botão abaixo para verificar se a carga útil de autenticação personalizada está configurada corretamente.
Se o teste for bem-sucedido, o botão ficará verde.
Com essa autenticação, a execução da ação é um processo de duas etapas:
- Chame o endpoint para gerar o token de acesso.
- Chame a REST API inserindo de maneira correta o token de acesso.
Definição do endpoint que será chamado para gerar o token de acesso
-
endpoint: URL que será usado para gerar o endpoint
-
método da solicitação HTTP no endpoint (GET ou POST)
-
cabeçalhos: pares de valores chave que serão inseridos como cabeçalhos nesta chamada, se necessário
-
corpo: descreve o corpo da chamada se o método for POST. Oferecemos suporte a uma estrutura de corpo limitada, definida em bodyParams (pares de valores chave). O bodyType descreve o formato e a codificação do corpo na chamada:
- 'form': significa que o tipo de conteúdo será application/x-www-form-urlencoded (charset UTF-8) e que os pares de valor-chave serão serializados como estão: key1=value1&key2=value2&…
- "json": significa que o tipo de conteúdo será application/json (charset UTF-8) e que os pares de valores chave serão serializados como um objeto json como a seguir: { "key1": "value1", "key2": "value2", …}
Definição da forma como o token de acesso deve ser inserido na solicitação HTTP da ação
-
authorizationType: define como o token de acesso gerado deve ser inserido na chamada HTTP para a ação. Os valores possíveis são:
- bearer: indica que o token de acesso deve ser injetado no cabeçalho da Autorização, como: Authorization: Bearer <access token>
- header: indica que o token de acesso deve ser inserido como um cabeçalho, o nome do cabeçalho definido pela propriedade tokenTarget. Por exemplo, se o tokenTarget for myHeader, o token de acesso será inserido como um cabeçalho como: myHeader: <access token>
- queryParam: indica que o token de acesso deve ser inserido como um queryParam, o nome do parâmetro do query definido pela propriedade tokenTarget. Por exemplo, se o tokenTarget for myQueryParam, o URL da chamada de ação será: <url>?myQueryParam=<access token>
-
tokenInResponse: indica como extrair o token de acesso da chamada de autenticação. Essa propriedade pode ser:
- 'response': indica que a resposta HTTP é o token de acesso
- um seletor em um json (supondo que a resposta seja um json, não oferecemos suporte a outros formatos, como XML). O formato desse seletor é json://<path to the access token property>. Por exemplo, se a resposta da chamada for: { "access_token": "theToken", "timestamp": 12323445656 }, o tokenInResponse será: json: //access_token
O formato dessa autenticação é:
{
"type": "customAuthorization",
"endpoint": "<URL of the authentication endpoint>",
"method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
(optional) "headers": {
"<header name>": "<header value>",
...
},
(optional, mandatory if method is 'POST') "body": {
"bodyType": "<'form'or 'json'>,
"bodyParams": {
"param1": value1,
...
}
},
"tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'",
"cacheDuration": {
(optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
(optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
"timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
},
"authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
(optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
}
É possível alterar a duração do cache do token para uma fonte de dados de autenticação personalizada. Encontre abaixo um exemplo de payload de autenticação personalizada. A duração do cache é definida no parâmetro "cacheDuration". Especifica a duração de retenção do token gerado no cache. A unidade pode ser milissegundos, segundos, minutos, horas, dias, meses, anos.
Veja um exemplo do tipo de autenticação de portador:
{
"authentication": {
"type": "customAuthorization",
"authorizationType": "Bearer",
"endpoint": "https://localhost:${port}/epsilon/oauth2/access_token",
"method": "POST",
"headers": {
"Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
},
"body": {
"bodyType": "form",
"bodyParams": {
"scope": "cn mail givenname uid employeeNumber",
"grant_type": "password",
"username": "<epsilon User Name>",
"password": "<epsilon User Password>"
}
},
"tokenInResponse": "json://access_token",
"cacheDuration": {
"duration": 5,
"timeUnit": "minutes"
}
}
}
Veja um exemplo do tipo de autenticação de cabeçalho:
{
"type": "customAuthorization",
"authorizationType": "header",
"tokenTarget": "x-auth-token",
"endpoint": "https://myapidomain.com/v2/user/login",
"method": "POST",
"headers": {
"x-retailer": "any value"
},
"body": {
"bodyType": "form",
"bodyParams": {
"secret": "any value",
"username": "any value"
}
},
"tokenInResponse": "json://token",
"cacheDuration": {
"expiryInResponse": "json://expiryDuration",
"timeUnit": "minutes"
}
}
Este é um exemplo da resposta da chamada de API de logon:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}