Nesta página: conecte-se a APIs REST de terceiros e configure a autenticação para que você possa receber dados externos em suas jornadas para condições e personalização.
Trabalhar com fontes de dados externas gs-ext-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 Adobe Experience Platform interna, você pode criar quantas fontes de dados externas forem necessárias.
-
As garantias ao trabalhar com sistemas externos estão listadas em esta página.
-
Como as respostas agora são compatíveis, você deve usar ações personalizadas em vez de fontes de dados para casos de uso de fontes de dados externas. Para obter mais informações sobre respostas, consulte respostas da ação personalizada. Ações personalizadas sem persistência do Data Lake são a escolha certa quando os dados são úteis somente dentro da jornada e o sistema externo é acessível por meio de um endpoint da API. Para obter uma comparação de todas as opções de acesso a dados, consulte Escolher sua estratégia de acesso a dados.
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).
cacheDuration do Journey Optimizer , especialmente em cargas de trabalho pesadas, para evitar incompatibilidades de expiração e erros 401.Criar e configurar uma fonte de dados externa create-ext-data-sources
Abaixo estão as principais etapas para criar e configurar uma nova fonte de dados externa:
-
Na lista de fontes de dados, clique em Criar Source 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.
Somente caracteres alfanuméricos e sublinhados são permitidos. O comprimento máximo é 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 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ásica, Personalizada 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 -
Quando a chamada de autenticação é executada, a cadeia de caracteres
<username>:<password>, codificada em base64, é adicionada ao cabeçalho Authentication. -
Adobe Journey Optimizer criptografa automaticamente segredos definidos em ações personalizadas. As chaves de criptografia de cada organização são gerenciadas com segurança em um cofre dedicado vinculado à organização. Quando as credenciais são exibidas na interface, elas são mascaradas por padrão para evitar exposição acidental.
Para obter mais informações sobre o modo de autenticação personalizado, consulte a seção modo de autenticação personalizado. No nosso exemplo, escolhemos o modo de autenticação da chave de API, conforme abaixo:
-
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)
-
Local: “Parâmetro de consulta” (a chave de API está localizada na URL)
-
-
Adicione um novo grupo de campos para cada conjunto de parâmetros da API clicando em Adicionar Novo Grupo de Campos. Somente caracteres alfanuméricos e sublinhados são permitidos no nome do grupo de campos. O comprimento máximo é de 30 caracteres. 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 ícone Exibir jornadas 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” em nosso exemplo. Como os valores dos parâmetros dependem do contexto de execução, eles serão definidos nas jornadas. Saiba mais sobre expressões
- Carga de resposta: clique dentro do campo 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 desejar alterar a carga transmitida no momento.
- Carga Enviada: 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ê insere os parâmetros no campo Valores dinâmicos e eles são adicionados automaticamente no final da chamada. No caso de uma chamada POST, é necessário:
- listar os parâmetros a serem transmitidos no momento da chamada no campo 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:
{"id":{"param":"identifier"}}
Depois que as alterações forem salvas, a fonte de dados será configurada e estará pronta para ser usada nas jornadas, por exemplo, nas 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
O modo de autenticação personalizado é usado para autenticação complexa, frequentemente usada para chamar protocolos de empacotamento automático 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, use o botão Clique para verificar a autenticação para controlar se a carga útil de autenticação personalizada está configurada corretamente.
Quando o teste for bem-sucedido, o botão ficará verde.
Com esse modo de 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 custom-authentication-endpoint
-
endpoint: URL a ser usada para gerar o ponto de extremidade -
método da solicitação HTTP no ponto de extremidade (
GETouPOST) -
headers: pares de chave-valor a serem inseridos como cabeçalhos nesta chamada, se necessário -
body: 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 custom-authentication-access-token
-
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 inserido no cabeçalho de Autorização, como: Autorização: Portador <token de acesso>header: indica que o token de acesso deve ser inserido como um cabeçalho, o nome do cabeçalho definido pela propriedadetokenTarget. Por exemplo, se otokenTargetformyHeader, 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 de consulta 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:
{
"type": "customAuthorization",
"endpoint": "https://<your_auth_endpoint>/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"
},
},
-
O token de autenticação é armazenado em cache por jornada: se duas jornadas estiverem usando a mesma ação personalizada, cada jornada terá seu próprio token armazenado em cache. Esse token não é compartilhado entre essas jornadas.
-
A duração do cache ajuda a evitar muitas chamadas para os pontos de extremidade de autenticação. A retenção do token de autenticação é armazenada em cache nos serviços; não há persistência. Se um serviço for reiniciado, ele será iniciado com um cache limpo. A duração padrão do cache é de 1 hora. Na carga de autenticação personalizada, ela pode ser adaptada especificando outra duração de retenção.
Autenticação personalizada baseada em certificado certificate-credential
Para APIs corporativas que impõem a verificação de identidade baseada em certificado — como Microsoft Entra ID —, é possível configurar a autenticação personalizada baseada em certificado adicionando "subType": "certificateCredential" à sua carga de autorização personalizada. O Journey Optimizer usa o certificado gerenciado do Adobe para assinar uma declaração de cliente JWT e trocá-la por um token de acesso. Nenhum segredo de cliente é necessário.
Esta opção adiciona dois campos obrigatórios ao esquema padrão customAuthorization: subType e aud. Todos os outros campos (endpoint, method, parâmetros de corpo, tokenInResponse) permanecem inalterados. Quando subType está ausente, o comportamento é idêntico à autenticação personalizada padrão — as configurações existentes não são afetadas.
subType: Defina como"certificateCredential"para ativar a autenticação baseada em certificado.aud: o valor de público incluído na asserção do cliente JWT. Para a Microsoft Entra ID, é o mesmo que a URLendpoint, mas ela deve ser sempre definida explicitamente.
Os campos client_assertion e client_assertion_type nunca foram criados pelo usuário. Eles são inseridos automaticamente pela plataforma no tempo de execução, imediatamente antes da chamada do endpoint de token.
Como funciona certificate-credential-how-it-works
A autenticação personalizada baseada em certificado implementa as credenciais de cliente OAuth 2.0 com uma asserção de cliente JWT, conforme definido na RFC 7523 — o mesmo padrão aceito pela Microsoft Entra ID e pelo Okta. Em vez de um segredo do cliente, o Journey Optimizer comprova sua identidade usando um JWT assinado com a chave privada gerenciada da Adobe. Seu provedor de identidade verifica a assinatura usando o certificado público da Adobe, que você registra uma vez em seu provedor de identidade.
A troca de token segue estas etapas:
- O Journey Optimizer cria uma asserção de cliente JWT assinada com a chave privada da Adobe.
- A declaração é enviada para o ponto de extremidade do token junto com
client_id,grant_typeescope. - Seu provedor de identidade verifica a assinatura JWT em relação ao certificado público registrado da Adobe.
- O provedor de identidade retorna um token de acesso do portador.
- O Journey Optimizer usa esse token para chamar seu endpoint de ação personalizada.
Detalhes do certificado do Adobe certificate-credential-details
O Adobe gerencia o certificado e sua chave privada associada. A tabela a seguir resume suas principais propriedades:
expiryDate e reconfigurar o IDP antes que o certificado antigo seja revogado.O Adobe gira automaticamente o certificado 60 dias antes da expiração. O certificado anterior permanece válido até 30 dias antes da expiração. Os clientes não são notificados no momento — consulte a Proteção de rotação de certificados abaixo para saber como monitorar a rotação programaticamente.
Estrutura de asserção JWT certificate-credential-jwt
Você não cria a asserção do cliente JWT — o Journey Optimizer a gera e a assina para você. A estrutura esperada é fornecida aqui para que a equipe do provedor de identidade possa validar as declarações.
Cabeçalho:
{
"alg": "RS256",
"x5t": "<base64url SHA-1 thumbprint of Adobe's leaf certificate>"
}
Carga:
{
"iss": "<client_id>",
"sub": "<client_id>",
"aud": "<token endpoint URL>",
"iat": "<current unix timestamp>",
"exp": "<iat + 600 seconds>",
"jti": "<unique UUID per request>"
}
Observe o seguinte:
exp-iaté sempre ≤ 10 minutos — consistente com os requisitos do Okta e da Entra ID.- Cada asserção usa um
jtiexclusivo, o que o torna seguro para ataques de repetição. client_assertioneclient_assertion_typesão inseridos automaticamente pela plataforma e nunca são criados.
Este é um exemplo do tipo de autenticação de credencial de certificado, para Microsoft Entra ID:
{
"type": "customAuthorization",
"subType": "certificateCredential",
"aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
"authorizationType": "Bearer",
"endpoint": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
"method": "POST",
"body": {
"bodyType": "form",
"bodyParams": {
"client_id": "<your-client-id>",
"grant_type": "client_credentials",
"scope": "https://api.example.com/.default"
}
},
"tokenInResponse": "json://access_token"
}
Este é um exemplo para o mesmo tipo de autenticação de credencial de certificado, para o Okta:
{
"type": "customAuthorization",
"subType": "certificateCredential",
"authorizationType": "bearer",
"endpoint": "https://<your-okta-domain>/oauth2/v1/token",
"aud": "https://<your-okta-domain>/oauth2/v1/token",
"method": "POST",
"body": {
"bodyType": "form",
"bodyParams": {
"client_id": "<your-okta-app-client-id>",
"grant_type": "client_credentials",
"scope": "<your-api-scope>"
}
},
"tokenInResponse": "json://access_token"
}
- URL do ponto de extremidade do token: deve ser HTTPS. Evite URLs contendo
?— este é um sinal de que o ponto de extremidade de autorização foi colado em vez do ponto de extremidade do token. method: Deve serPOST. Os endpoints do token OAuth só aceitam solicitações POST.client_id: não deve estar em branco e não deve conter espaços em branco à esquerda ou à direita. Um valor em branco produz um JWT de aparência válida que o Provedor de identidade rejeitará com um erro opaco.scope: Expressa como uma cadeia de caracteres separada por espaço embodyParams. Total máximo de 1000 caracteres.- Certificado: o Adobe gerencia o certificado e a chave privada — você nunca carrega ou insere um certificado. Antes de usar a ação personalizada em uma jornada em tempo real, você deve registrar o certificado folha da Adobe no seu Provedor de Identidade. Para recuperá-lo, chame a API de Certificado Público de mTLS e procure a entrada onde
certCommonNameéajo-journeys.aep-mtls.adobe.com. Registre o valorpublicCertificatedessa entrada — não use os certificados da autoridade de certificação intermediária ou raiz. Como os clientes não são notificados sobre a rotação de certificados, você deve chamar periodicamente a API de Certificado público mTLS para verificar oexpiryDatee atualizar o certificado registrado no IDP antes que o certificado antigo seja revogado 30 dias antes da expiração.
Veja um exemplo do tipo de autenticação de cabeçalho:
{
"type": "customAuthorization",
"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"
},
"authorizationType": "header",
"tokenTarget": "x-auth-token"
}
Este é um exemplo da resposta da chamada de API de logon:
{
"token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
"expiryDuration" : 5
}
bodyParams) são suportados.This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.
For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.
- TL;DR: This page explains how to create and configure external data sources that connect to third-party REST APIs, including the supported authentication modes, field group setup, custom authentication payloads, and certificate-based custom authentication.
Intents:
- Create and configure an external data source that connects to a third-party REST API
- Choose an authentication mode among No authentication, Basic, Custom, and API key
- Define field groups per API parameter set with Method, Dynamic Values, and payload fields
- Configure custom authentication for protocols such as OAuth2 and check it with the check authentication button
- Configure certificate-based custom authentication for enterprise APIs such as Microsoft Entra ID and Okta
- Set the token cache duration to limit calls to the authentication endpoint
Glossary:
- External data source: A connection to a third-party system that you create; you can create as many as you need (product-specific)
- Field group: A set of fields configured per API parameter set, with Method, Dynamic Values, Response Payload, and (for POST) Sent Payload (product-specific)
- Custom authentication mode: An authentication mode for complex protocols such as OAuth2, where the action execution is a two-step process that first generates an access token and then injects it in the HTTP request (product-specific)
- cacheDuration: The parameter that specifies the retention duration of the generated token in the cache (product-specific)
- Certificate-based custom authentication: A custom authentication subtype (
subType: certificateCredential) where Journey Optimizer uses Adobe’s managed certificate to sign a JWT client assertion and exchange it for an access token, with no client secret required (product-specific)
Guardrails:
- REST APIs using POST or GET and returning JSON are supported; API Key, basic, and custom authentication modes are supported.
- Adobe addresses that are not publicly available and the use of IP addresses are not allowed; HTTPS is strongly recommended for security reasons.
- Data source name: only alphanumeric characters and underscores are allowed, maximum length 30 characters (hard limit).
- Field group name: only alphanumeric characters and underscores are allowed, maximum length 30 characters (hard limit).
- The Sent Payload field is only available if you select the POST method.
- The default cache duration is 1 hour (default) and can be adapted in the custom authentication payload; a one-minute buffer between the external API’s token expiration and the
cacheDurationsetting is recommended to avoid 401 errors. - The authentication token is cached per journey and is not shared between journeys; there is no persistence, so a service restart starts with a clean cache.
- Encode64 is the only function available in the authentication payload.
- For certificate-based custom authentication,
subTypeandaudare mandatory; the token endpoint URL must be HTTPS,methodmust bePOST,client_idmust not be blank and must have no leading or trailing whitespace. scopeis a single space-separated string inbodyParams, maximum 1000 characters total (hard limit).- You never upload or enter a certificate; before using the custom action in a live journey you must register Adobe’s leaf certificate (not the intermediate or root CA) in your Identity Provider.
- The Adobe certificate uses RS256 (RSA); Adobe rotates it 60 days before expiry (certificate lifetime 13 months) and the previous certificate remains valid until 30 days before expiry; customers are not currently notified, so periodically call the mTLS Public Certificate API to check the
expiryDate. - Nested JSON objects (for example, sub-objects within
bodyParams) are supported.
Terminology:
- Canonical name: external data source — Acronym: n/a — variants: external data sources, third-party data source
- Synonyms: “check the authentication” = “Click to check the authentication” button
- Do not confuse: “Dynamic Values” (parameters defined in journeys and passed at call time) ≠ “Response Payload” (example payload returned by the call) ≠ “Sent Payload” (payload sent to the third-party system, POST only)
- Do not confuse: “standard custom authentication” ≠ “certificate-based custom authentication” (
subType: certificateCredential, using Adobe’s managed certificate instead of a client secret)
FAQ:
- Q: What kinds of APIs are supported for external data sources? — REST APIs using POST or GET and returning JSON, with API Key, basic, or custom authentication modes.
- Q: What is the maximum length of a data source or field group name? — 30 characters, using only alphanumeric characters and underscores.
- Q: How do I verify that my custom authentication payload is configured correctly? — Use the Click to check the authentication button; when the test is successful, the button turns green.
- Q: What is the default token cache duration and can I change it? — The default cache duration is 1 hour, and you can adapt it by specifying another retention duration in the
cacheDurationparameter of the custom authentication payload. - Q: Do I need to upload a certificate for certificate-based custom authentication? — No, Adobe manages the certificate and private key; you register Adobe’s leaf certificate in your Identity Provider, retrieved from the mTLS Public Certificate API.
- Q: Are nested JSON objects allowed in the custom authentication body? — Yes, nested JSON objects such as sub-objects within
bodyParamsare supported.