Fontes de dados externas external-data-sources

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 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:

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).

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:

Somente caracteres alfanuméricos e sublinhados são permitidos. O comprimento máximo é de 30 caracteres.

Para o conjunto de parâmetros “long/lat”, criamos um grupo de campos com as seguintes informações:

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:

{"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:

Definição do endpoint que será chamado para gerar o token de acesso custom-authentication-endpoint

Definição da forma como o token de acesso deve ser inserido na solicitação HTTP da ação custom-authentication-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"
    },
  },

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.

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:

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:

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:

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"
}

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
}