[Ultimate]{class="badge positive"}

Conexão da API HTTP

Visão geral overview

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

Para enviar dados de perfil para pontos de extremidade HTTP, primeiro você deve se conectar ao destino no Experience Platform.

Casos de uso use-cases

Use o destino da API HTTP para exportar dados de perfil XDM e públicos-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.

Públicos-alvo compatíveis supported-audiences

Esta seção descreve quais tipos de públicos-alvo você pode exportar para esse destino.

Públicos-alvo compatíveis por tipo de dados de público-alvo:

Tipo e frequência de exportação export-type-frequency

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

Pré-requisitos prerequisites

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

Suporte e certificado do protocolo mTLS mtls-protocol-support

Você pode usar o Mutual Transport Layer Security (mTLS) para garantir a segurança aprimorada em conexões de saída com suas conexões de destino de API HTTP.

O mTLS é um protocolo de autenticação mútua que garante que ambas as partes que compartilham informações sejam quem afirmam ser antes que os dados sejam compartilhados. O mTLS inclui uma etapa adicional em comparação ao TLS padrão, no qual o servidor também solicita e verifica o certificado do cliente, enquanto o cliente verifica o certificado do servidor.

Considerações sobre mTLS mtls-considerations

O suporte mTLS para destinos de API HTTP se aplica somente ao ponto de extremidade de recebimento de dados para o qual são enviadas exportações de perfil (o campo Ponto de Extremidade HTTP em detalhes de destino).

Configuração de mTLS para exportação de dados configuring-mtls

Para usar mTLS com destinos da API HTTP, o Ponto de Extremidade HTTP (ponto de extremidade de recebimento de dados) configurado na página detalhes do destino deve ter os protocolos TLS desabilitados e somente o mTLS habilitado. Se o protocolo TLS 1.2 ainda estiver habilitado no endpoint, nenhum certificado será enviado para a autenticação de cliente. Isso significa que para usar mTLS com seu destino da API HTTP, o ponto de extremidade do servidor de recebimento de dados deve ser um ponto de extremidade de conexão habilitado somente para mTLS.

Recuperar e inspecionar detalhes do certificado certificate

Se você quiser inspecionar detalhes do certificado, como Nome Comum (CN) e Nomes Alternativos da Entidade (SAN), para validação adicional de terceiros, use a API para recuperar o certificado e extrair esses campos da resposta.

Consulte a documentação do ponto de extremidade do certificado público para obter mais informações.

INCLUO NA LISTA DE PERMISSÕES de endereços IP ip-address-allowlist

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 para o destino da API HTTP. Consulte incluo na lista de permissões de endereços IP para destinos de streaming para obter a lista completa de IPs a serem incluídos na lista de permissões.

Tipos de autenticação compatíveis supported-authentication-types

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

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

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'

Conectar ao destino connect-destination

Para se conectar a este 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 authentication-information

Autenticação de token do portador bearer-token-authentication

Se você selecionar o tipo de autenticação Token de portador para se conectar ao seu ponto de extremidade HTTP, insira as informações abaixo e selecione Conectar-se ao destino:

Sem autenticação no-authentication

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

Ao selecionar essa opção de autenticação, você só precisa selecionar Conectar-se ao destino e a conexão com seu ponto de extremidade é estabelecida.

Autenticação de senha do OAuth 2 oauth-2-password-authentication

Se você selecionar o tipo de autenticação Senha do OAuth 2 para se conectar ao seu ponto de extremidade HTTP, insira as informações abaixo e selecione Conectar-se ao destino:

Autenticação de Credenciais de Cliente OAuth 2 oauth-2-client-credentials-authentication

Se você selecionar o tipo de autenticação Credenciais de Cliente OAuth 2 para se conectar ao seu ponto de extremidade HTTP, insira as informações abaixo e selecione Conectar ao destino:

Preencher detalhes do destino destination-details

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.

Ativar alertas enable-alerts

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 destino usando a interface.

Quando terminar de fornecer detalhes da conexão de destino, selecione Avançar.

Ativar públicos-alvo para esse destino activate

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

Atributos de destino attributes

Na etapa Selecionar atributos, a Adobe recomenda selecionar um identificador exclusivo do seu 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 profile-export-behavior

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

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 público-alvo mapeado para o fluxo de destino tiver cem membros e cinco novos perfis se qualificarem para o público-alvo, a exportação para o destino será incremental e incluirá apenas os cinco novos perfis.

O que determina uma exportação de dados e o que está incluído na exportação what-determines-export-what-is-included

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

Por exemplo, considere esse fluxo de dados para um destino HTTP, onde três públicos-alvo são selecionados no fluxo de dados e quatro atributos são mapeados para o destino.

Uma exportação de perfil para o destino é acionada quando um perfil se qualifica para ou sai de um dos três públicos mapeados. Quando a opção Incluir somente públicos mapeados está ativada, o objeto segmentMembership (consulte Dados Exportados abaixo) inclui somente os três públicos mapeados. Quando esta opção está desativada, o objeto segmentMembership também pode incluir públicos não mapeados, se esse perfil for um membro deles e se eles compartilharem a mesma política de mesclagem que o público-alvo que acionou a exportação. Por exemplo, se um perfil se qualificar para o público-alvo Cliente com carros DeLosands, mas também for membro do filme Assistido “De volta para o futuro” e dos fãs de ficção científica, esses dois públicos-alvo também aparecerão no objeto segmentMembership quando Incluir somente públicos-alvo mapeados estiver desativado, desde que compartilhem a mesma política de mesclagem com o público-alvo Cliente com carros DeLosands.

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 historical-data-backfill

Quando você adiciona um novo público a um destino existente ou cria um novo destino e mapeia públicos a ele, o Experience Platform exporta dados históricos de qualificação de público para o destino. Os perfis qualificados para o público-alvo antes de o público-alvo ser adicionado ao destino são exportados para o destino em aproximadamente uma hora.

Dados exportados exported-data

Os dados exportados do Experience Platform chegam ao destino HTTP no formato JSON. Por exemplo, a exportação abaixo contém um perfil que se qualificou para um determinado público-alvo, é membro de outros dois públicos-alvo e saiu de outro público-alvo. 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 de interface do usuário selecionadas no fluxo de destino de conexão para as opções Incluir nomes de público-alvo e Incluir carimbos de data/hora de público-alvo:

"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"
          },
          "354e086f-2e11-49a2-9e39-e5d9a76be683": {
            "lastQualificationTime": "2020-04-15T02:41:50+0000",
            "status": "realized"
          }
        }
      }

"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 limits-retry-policy

95% do tempo, 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 a um destino HTTP.

Quando as solicitações para o destino da API HTTP falham, o Experience Platform as armazena e tenta novamente duas vezes.

Solução de problemas troubleshooting

Para garantir a entrega de dados confiável e evitar problemas de tempo limite, verifique se o seu ponto de extremidade HTTP responde em 2 segundos às solicitações do Experience Platform, conforme especificado na seção pré-requisitos. Respostas que demoram mais resultarão em erros de tempo limite.