Conexão da API HTTP

Visão geral

O destino da API HTTP é um Adobe Experience Platform destino de fluxo que ajuda a enviar dados de perfil para pontos de extremidade HTTP de terceiros.

Para enviar dados de perfil para pontos de extremidade HTTP, primeiro é necessário conectar-se ao destino em Adobe Experience Platform.

Casos de uso

O destino da API HTTP permite exportar dados de perfil XDM e segmentos de público-alvo para pontos de extremidade HTTP genéricos. Lá, você pode executar suas próprias análises ou executar qualquer outra operação necessária nos dados de perfil exportados do Experience Platform.

Os endpoints HTTP podem ser sistemas próprios do cliente ou soluções de terceiros.

Tipo e frequência de exportação

Consulte a tabela abaixo para obter informações sobre o tipo e a frequência da exportação de destino.

Pré-requisitos

Para usar o destino da API HTTP para exportar dados do Experience Platform, você deve atender aos seguintes pré-requisitos:

• Você deve ter um terminal HTTP compatível com REST API.
• Seu terminal HTTP deve oferecer suporte ao esquema de perfil Experience Platform. Nenhuma transformação em um esquema de carga de terceiros é compatível com o destino da API HTTP. Consulte a dados exportados para obter um exemplo do schema de saída Experience Platform.
• Seu terminal HTTP deve suportar cabeçalhos.

Endereço IP lista de permissões

Para atender aos requisitos de segurança e conformidade dos clientes, o Experience Platform fornece uma lista de IPs estáticos que você pode lista de permissões para o destino da API HTTP. Consulte LISTA DE PERMISSÕES de endereço IP para destinos de transmissão para obter a lista completa de IPs a serem lista de permissões.

Tipos de autenticação compatíveis

O destino da API HTTP suporta vários tipos de autenticação para o seu ponto de extremidade HTTP:

• Ponto de extremidade HTTP sem autenticação;
• Autenticação do token portador;
• Credenciais do cliente OAuth 2.0 autenticação com o formulário body, com client ID, client secret e grant type no corpo da solicitação HTTP, como mostrado no exemplo abaixo.

curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

• Credenciais do cliente OAuth 2.0 com autorização básica, com um cabeçalho de autorização que contém codificação de URL client ID e client secret.

curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

• Concessão de senha do OAuth 2.0.

Conecte-se ao destino

Para se conectar a esse destino, siga as etapas descritas na tutorial de configuração de destino. Ao se conectar a esse destino, você deve fornecer as seguintes informações:

Informações de autenticação

Autenticação de token portador

Se você selecionar a variável Token de portador tipo de autenticação para se conectar ao terminal HTTP, insira os campos abaixo e selecione Ligar ao destino:

• Token de portador: insira o token portador para autenticar no seu local HTTP.

Sem autenticação

Se você selecionar a variável Nenhum tipo de autenticação para se conectar ao terminal HTTP:

Ao selecionar essa autenticação aberta, você só precisa selecionar Ligar ao destino e a conexão com seu terminal é estabelecida.

Autenticação de senha OAuth 2

Se você selecionar a variável Senha do OAuth 2 tipo de autenticação para se conectar ao terminal HTTP, insira os campos abaixo e selecione Ligar ao destino:

• URL do token de acesso: O URL do seu lado que emite tokens de acesso e, opcionalmente, de atualização.
• ID do cliente: O client ID que seu sistema atribui à Adobe Experience Platform.
• Segredo do cliente: O client secret que seu sistema atribui à Adobe Experience Platform.
• Nome do usuário: O nome de usuário para acessar o terminal HTTP.
• Senha: A senha para acessar o terminal HTTP.

Autenticação de credenciais de cliente OAuth 2

Se você selecionar a variável Credenciais do Cliente OAuth 2 tipo de autenticação para se conectar ao terminal HTTP, insira os campos abaixo e selecione Ligar ao destino:

• URL do token de acesso: O URL do seu lado que emite tokens de acesso e, opcionalmente, de atualização.
• ID do cliente: O client ID que seu sistema atribui à Adobe Experience Platform.
• Segredo do cliente: O client secret que seu sistema atribui à Adobe Experience Platform.
• Tipo de credenciais do cliente: Selecione o tipo de concessão de Credenciais do Cliente OAuth2 com suporte do seu ponto de extremidade:
  • Formulário de corpo codificado: Nesse caso, a variável client ID e client secret estão incluídos no corpo do pedido enviado para o seu destino. Para ver um exemplo, consulte a Tipos de autenticação compatíveis seção.
  • Autorização básica: Nesse caso, a variável client ID e client secret estão incluídos em um Authorization header depois de ser codificado em base64 e enviado para seu destino. Para ver um exemplo, consulte a Tipos de autenticação compatíveis seção.

Detalhes do destino

Depois de estabelecer a conexão de autenticação com o endpoint HTTP, forneça as seguintes informações para o destino:

• Nome: Insira um nome pelo qual você reconhecerá esse destino no futuro.
• Descrição: Insira uma descrição que ajudará a identificar esse destino no futuro.
• Cabeçalhos: Insira quaisquer cabeçalhos personalizados que você deseja incluir nas chamadas de destino, seguindo este formato: header1:value1,header2:value2,...headerN:valueN.
• Endpoint HTTP: O URL do endpoint HTTP para o qual você deseja enviar os dados do perfil.
• Parâmetros de consulta: Opcionalmente, é possível adicionar parâmetros de consulta ao URL do ponto de extremidade HTTP. Formate os parâmetros de consulta usados desta forma: parameter1=value&parameter2=value.
• Incluir nomes de segmentos: Alterne se deseja que a exportação de dados inclua os nomes dos segmentos que você está exportando. Para obter um exemplo de exportação de dados com essa opção selecionada, consulte Dados exportados mais abaixo.
• Incluir carimbos de data e hora do segmento: Alterne se deseja que a exportação de dados inclua o carimbo de data e hora UNIX quando os segmentos foram criados e atualizados, bem como o carimbo de data e hora UNIX quando os segmentos foram mapeados para o destino para ativação. Para obter um exemplo de exportação de dados com essa opção selecionada, consulte Dados exportados mais abaixo.

Ativar segmentos para este destino

Consulte Ativar dados do público-alvo para destinos de exportação de perfil de fluxo para obter instruções sobre como ativar segmentos de público-alvo para este destino.

Atributos de destino

No Selecionar atributos , o Adobe recomenda selecionar um identificador exclusivo de schema de união. Selecione o identificador exclusivo e quaisquer outros campos XDM que deseja exportar para o destino.

Comportamento de exportação de perfil

O Experience Platform otimiza o comportamento de exportação do perfil para o destino da API HTTP, a fim de exportar apenas dados para o ponto de extremidade da API quando ocorrerem atualizações relevantes para um perfil após a qualificação de segmento ou outros eventos significativos. Os perfis são exportados para o seu destino nas seguintes situações:

• A atualização de perfil foi determinada por uma alteração na associação de segmento para pelo menos um dos segmentos mapeados para o destino. Por exemplo, o perfil se qualificou para um dos segmentos mapeados para o destino ou saiu de um dos segmentos mapeados para o destino.
• A atualização do perfil foi determinada por uma alteração no mapa de identidade. Por exemplo, um perfil que já se qualificou para um dos segmentos mapeados para o destino foi adicionado a uma nova identidade no atributo do mapa de identidade.
• A atualização do perfil foi determinada por uma alteração nos atributos para pelo menos um dos atributos mapeados para o destino. Por exemplo, um dos atributos mapeados para o destino na etapa de mapeamento é adicionado a um perfil.

Em todos os casos descritos acima, somente os perfis onde as atualizações relevantes ocorreram são exportados para o seu destino. Por exemplo, se um segmento mapeado para o fluxo de destino tiver cem membros e cinco novos perfis se qualificarem para o segmento, a exportação para o seu destino será incremental e incluirá apenas os cinco novos perfis.

Observe que todos os atributos mapeados são exportados para um perfil, independentemente de onde as alterações se encontrem. Portanto, no exemplo acima, todos os atributos mapeados para esses cinco novos perfis serão exportados mesmo se os atributos em si não tiverem sido alterados.

O que determina uma exportação de dados e o que está incluído na exportação

Com relação aos dados exportados para um determinado perfil, é importante entender os dois conceitos diferentes de o que determina uma exportação de dados para o destino da API HTTP e que dados estão incluídos na exportação.

Por exemplo, considere esse fluxo de dados como um destino HTTP, onde três segmentos são selecionados no fluxo de dados e quatro atributos são mapeados para o destino.

Uma exportação de perfil para o destino pode ser determinada por um perfil que se qualifica para ou sai de um dos três segmentos mapeados. No entanto, na exportação de dados, no segmentMembership objeto (consulte Dados exportados seção abaixo), outros segmentos não mapeados podem aparecer, se esse perfil específico for membro deles. Se um perfil se qualificar para o segmento Cliente com Carros coreanos, mas também for membro do filme "Voltar ao futuro" assistido e dos segmentos de fãs de ficção científica, esses dois outros segmentos também estarão presentes segmentMembership objeto da exportação de dados, mesmo que não estejam mapeados no fluxo de dados.

Do ponto de vista dos atributos do perfil, qualquer alteração nos quatro atributos mapeados acima determinará uma exportação de destino e qualquer um dos quatro atributos mapeados presentes no perfil estará presente na exportação de dados.

Preenchimento retroativo de dados históricos

Ao adicionar um novo segmento a um destino existente ou ao criar um novo destino e mapear segmentos a ele, o Experience Platform exporta os dados de qualificação de segmento históricos para o destino. Perfis que se qualificaram para o segmento before o segmento adicionado ao destino é exportado para o destino dentro de aproximadamente uma hora.

Dados exportados

Seu exportado Experience Platform os dados chegam ao seu HTTP destino no formato JSON. Por exemplo, a exportação abaixo contém um perfil que se qualificou para um determinado segmento, é um membro de outros dois segmentos e saiu de outro segmento. A exportação também inclui o atributo de perfil nome, sobrenome, data de nascimento e endereço de email pessoal. As identidades desse perfil são ECID e email.

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"existing"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"existing"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

Abaixo estão outros exemplos de dados exportados, dependendo das configurações da interface do usuário selecionadas no fluxo de destino de conexão para a variável Incluir nomes de segmentos e Incluir carimbos de data e hora do segmento opções:

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "existing",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Limites e política de repetição

Em 95% das vezes, o Experience Platform tenta oferecer uma latência de taxa de transferência inferior a 10 minutos para mensagens enviadas com êxito com uma taxa inferior a 10.000 solicitações por segundo para cada fluxo de dados para um destino HTTP.

No caso de solicitações com falha no destino da API HTTP, o Experience Platform armazena as solicitações com falha e tenta novamente duas vezes para enviar as solicitações para o terminal.