Conexão da API HTTP

Visão geral

O destino da API HTTP é um Adobe Experience Platform destino de transmissão que ajuda a enviar dados do perfil para endpoints HTTP de terceiros.

Para enviar dados de perfil para endpoints HTTP, primeiro você deve conectar ao destino in Adobe Experience Platform.

Casos de uso

O destino da API HTTP permite exportar dados de perfil XDM e segmentos de público-alvo para endpoints HTTP genéricos. Lá, você pode executar suas próprias análises ou executar outras operações que possam ser necessárias nos dados de perfil exportados do Experience Platform.

Os endpoints HTTP podem ser sistemas próprios dos clientes 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 endpoint HTTP compatível com REST API.
• Seu ponto de extremidade HTTP deve ser compatível com o esquema do perfil de 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 ponto de extremidade HTTP deve oferecer suporte a cabeçalhos.

INCLUIR NA LISTA DE PERMISSÕES endereço IP

Para atender aos requisitos de segurança e conformidade dos clientes, o Experience Platform fornece uma lista de IPs estáticos que você pode incluir na lista de permissões pelo 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 incluídos na lista de permissões.

Tipos de autenticação compatíveis

O destino da API HTTP oferece suporte a vários tipos de autenticação para o terminal HTTP:

• Endpoint HTTP sem autenticação;
• Autenticação do token portador;
• Credenciais de cliente do OAuth 2.0 autenticação com o formulário do corpo, 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 de cliente do OAuth 2.0 com autorização básica, com um cabeçalho de autorização que contém URL codificado 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.

Conectar ao destino

Para se conectar a esse destino, siga as etapas descritas no 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 do 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 Conectar ao destino:

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

Sem autenticação

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

Ao selecionar essa autenticação para abrir, você só precisa selecionar Conectar ao destino e a conexão com o terminal for estabelecida.

Autenticação de senha do 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 Conectar ao destino:

• URL do token de acesso: o URL no seu lado que emite tokens de acesso e, opcionalmente, atualiza tokens.
• ID do cliente: A variável client ID que seu sistema atribui à Adobe Experience Platform.
• Segredo do cliente: A variável client secret que seu sistema atribui à Adobe Experience Platform.
• Nome de usuário: o nome de usuário para acessar seu endpoint HTTP.
• Senha: a senha para acessar seu ponto de extremidade HTTP.

Autenticação de Credenciais de Cliente OAuth 2

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

• URL do token de acesso: o URL no seu lado que emite tokens de acesso e, opcionalmente, atualiza tokens.
• ID do cliente: A variável client ID que seu sistema atribui à Adobe Experience Platform.
• Segredo do cliente: A variável client secret que seu sistema atribui à Adobe Experience Platform.
• Tipo de credenciais do cliente: selecione o tipo de concessão de Credenciais de cliente OAuth2 suportada pelo 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 da solicitação enviado ao seu destino. Para obter 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 cabeçalho depois de ser codificado em base64 e enviado para o seu destino. Para obter um exemplo, consulte a Tipos de autenticação compatíveis seção.

Preencher detalhes do destino

Para configurar detalhes para o destino, preencha os campos obrigatórios e opcionais abaixo. Um asterisco ao lado de um campo na interface do usuário indica que o campo é obrigatório.

• Nome: digite 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 todos os cabeçalhos personalizados que 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 endpoint HTTP. Formate os parâmetros de consulta usados desta forma: parameter1=value&parameter2=value.
• Incluir nomes de segmentos: alterne se quiser 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 seção mais abaixo.
• Incluir carimbos de data e hora do segmento: alterne se quiser que a exportação de dados inclua o carimbo de data e hora UNIX quando os segmentos tiverem sido criados e atualizados, bem como o carimbo de data e hora UNIX quando os segmentos tiverem sido mapeados para o destino para ativação. Para obter um exemplo de exportação de dados com essa opção selecionada, consulte Dados exportados seção mais abaixo.

Ativar alertas

Você pode ativar os alertas para receber notificações sobre o status do fluxo de dados para o seu destino. Selecione um alerta na lista para assinar e receber notificações sobre o status do seu fluxo de dados. Para obter mais informações sobre alertas, consulte o manual sobre assinatura de alertas de destinos usando a interface do.

Quando terminar de fornecer detalhes da conexão de destino, selecione Próxima.

Ativar segmentos para este destino

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

Atributos de destino

No Selecionar atributos etapa, o Adobe recomenda que você selecione um identificador exclusivo de sua esquema de união. Selecione o identificador exclusivo e quaisquer outros campos XDM que você deseja exportar para o destino.

Comportamento de exportação de perfil

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

• A atualização do perfil foi determinada por uma alteração na associação do segmento de 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 recebeu uma nova identidade no atributo de mapa de identidade.
• A atualização do perfil foi determinada por uma alteração nos atributos de 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 em que ocorreram atualizações relevantes 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 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 estejam as alterações. 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

Em 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 seu destino da API HTTP e quais dados estão incluídos na exportação.

Por exemplo, considere esse fluxo de dados para 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 qualificado para ou que sai de um dos três segmentos mapeados. No entanto, na exportação de dados, no campo segmentMembership objeto (consulte Dados exportados abaixo), outros segmentos não mapeados poderão ser exibidos se esse perfil específico for um membro deles e se eles compartilharem a mesma política de mesclagem que o segmento que acionou a exportação. Se um perfil se qualificar para a variável Cliente com DeLorean Cars segmento, mas também é membro do Assistido "De volta ao futuro" filme e Fãs de ficção científica segmentos, esses outros dois segmentos também estarão presentes no segmentMembership objeto da exportação de dados, mesmo que não estejam mapeados no fluxo de dados, se compartilharem a mesma política de mesclagem com o Cliente com DeLorean Cars segmento.

Do ponto de vista dos atributos de 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

Quando você adiciona um novo segmento a um destino existente ou cria um novo destino e mapeia segmentos a ele, o Experience Platform exporta dados históricos de qualificação de segmento para o destino. Perfis que se qualificaram para o segmento antes o segmento foi adicionado ao destino e é exportado para o destino em aproximadamente uma hora.

Dados exportados

Seu exportado Experience Platform os dados chegam em 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 nome, sobrenome, data de nascimento e endereço de email pessoal do atributo de perfil. As identidades para esse 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":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "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 mais exemplos de dados exportados, dependendo das configurações da interface do usuário que você selecionar no fluxo de destino de conexão para o 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": "realized",
            "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": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Política de limites e novas tentativas

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

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

Recursos do Business.Adobe.com