[Ultimate]{class="badge positive"}

Conexão da API HTTP

Visão geral overview

IMPORTANT
Este destino está disponível somente para clientes do Adobe Real-time Customer Data Platform Ultimate.

O destino da API HTTP é um destino de streaming Adobe Experience Platform 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 você deve se conectar ao destino em Adobe Experience Platform.

Casos de uso use-cases

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

Origem do público
Suportado
Descrição
Segmentation Service
Públicos gerados por meio do Serviço de segmentação do Experience Platform.
Uploads personalizados
Públicos importados para o Experience Platform de arquivos CSV.

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.

Item
Tipo
Notas
Tipo de exportação
Baseado em perfil
Você está exportando todos os membros de um segmento, juntamente com os campos de esquema desejados (por exemplo: endereço de email, número de telefone, sobrenome), conforme escolhido na tela de mapeamento do fluxo de trabalho de ativação de destino.
Frequência de exportação
Streaming
Os destinos de transmissão são conexões baseadas em API "sempre ativas". Assim que um perfil é atualizado em Experience Platform com base na avaliação do público-alvo, o conector envia a atualização downstream para a plataforma de destino. Leia mais sobre destinos de streaming.

Pré-requisitos prerequisites

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 seção dados exportados para obter um exemplo do esquema de saída de Experience Platform.
  • Seu ponto de extremidade HTTP deve oferecer suporte a cabeçalhos.
TIP
Você também pode usar o Adobe Experience Platform Destination SDK para configurar uma integração e enviar dados de perfil de Experience Platform para um ponto de extremidade HTTP.

Suporte e certificado do protocolo mTLS mtls-protocol-support

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

mTLS é um método de segurança completo para autenticação mútua que garante que ambas as partes que compartilham informações sejam quem afirmam ser antes que os dados sejam compartilhados. mTLS inclui uma etapa adicional em comparação a TLS, na qual o servidor também solicita o certificado do cliente e o verifica ao final.

Se você quiser usar mTLS com HTTP API destinos, o endereço do servidor inserido na página detalhes do destino deve ter TLS protocolos desabilitados e apenas mTLS habilitado. Se o protocolo TLS 1.2 ainda estiver habilitado no ponto de extremidade, nenhum certificado será enviado para a autenticação de cliente. Isso significa que para usar mTLS com seu destino HTTP API, seu ponto de extremidade de servidor de "recebimento" deve ser um ponto de extremidade de conexão habilitado somente para mTLS.

Baixar certificado certificate

Se você quiser verificar o Common Name (CN) e o Subject Alternative Names (SAN) para fazer validação adicional de terceiros, poderá baixar o certificado abaixo:

INCLUIR NA LISTA DE PERMISSÕES endereço 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 pelo destino da API HTTP. Consulte inclui na lista de permissões de endereço IPs para destinos de transmissão para obter a lista completa de IPs para incluir 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:

  • Endpoint HTTP sem autenticação;
  • Autenticação do token portador;
  • Autenticação de credenciais de cliente OAuth 2.0 com o formulário de 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>'
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

IMPORTANT
Para se conectar ao destino, você precisa de Exibir Destinos e Gerenciar Destinos permissões de controle de acesso. Leia a visão geral do controle de acesso ou contate o administrador do produto para obter as permissões necessárias.

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 os campos abaixo e selecione Conectar ao destino:

Imagem da tela da interface do usuário onde você pode se conectar ao destino da API HTTP, usando a autenticação de token de portador.

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

Sem autenticação no-authentication

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

Imagem da tela da interface do usuário onde você pode se conectar ao destino da API HTTP sem autenticação.

Ao selecionar esta autenticação aberta, você só precisa selecionar Conectar ao destino e a conexão com o 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 os campos abaixo e selecione Conectar-se ao destino:

Imagem da tela da interface do usuário onde você pode se conectar ao destino da API HTTP, usando OAuth 2 com autenticação de Senha.

  • URL do Token de Acesso: a URL no seu lado que emite tokens de acesso e, opcionalmente, atualiza tokens.
  • 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 de usuário: o nome de usuário para acessar seu ponto de extremidade HTTP.
  • Senha: a senha para acessar seu ponto de extremidade HTTP.

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 os campos abaixo e selecione Conectar ao destino:

Imagem da tela da interface do usuário na qual você pode se conectar ao destino da API HTTP, usando o OAuth 2 com autenticação de Credenciais de Cliente.

  • URL do Token de Acesso: a URL no seu lado que emite tokens de acesso e, opcionalmente, atualiza tokens.

  • 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 de Cliente OAuth2 suportada pelo seu ponto de extremidade:

    • Formulário de Corpo Codificado: neste caso, client ID e client secret estão incluídos no corpo da solicitação enviada para o seu destino. Para ver um exemplo, consulte a seção Tipos de autenticação suportados.
    • Autorização básica: neste caso, o client ID e o client secret estão incluídos em um cabeçalho Authorization depois de serem codificados em base64 e enviados para o seu destino. Para ver um exemplo, consulte a seção Tipos de autenticação suportados.

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.

Imagem da tela da interface do usuário mostrando campos concluídos para os detalhes de destino HTTP.

  • Nome: digite um nome pelo qual você reconhecerá este destino no futuro.
  • Descrição: insira uma descrição que ajudará você a identificar este destino no futuro.
  • Cabeçalhos: insira todos os cabeçalhos personalizados que você deseja incluir nas chamadas de destino, seguindo este formato: header1:value1,header2:value2,...headerN:valueN.
  • Ponto de Extremidade HTTP: A URL do ponto de extremidade HTTP para o qual você deseja enviar os dados do perfil.
  • Parâmetros de consulta: como opção, você pode adicionar parâmetros de consulta à 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 quiser que a exportação de dados inclua os nomes dos públicos-alvo que você está exportando. Para obter um exemplo de exportação de dados com essa opção selecionada, consulte a seção Dados exportados, mais abaixo.
  • Incluir carimbos de data/hora do segmento: ative se desejar que a exportação de dados inclua o carimbo de data/hora UNIX quando os públicos-alvo foram criados e atualizados, bem como o carimbo de data/hora UNIX quando os públicos-alvo foram mapeados para o destino para ativação. Para obter um exemplo de exportação de dados com essa opção selecionada, consulte a seção Dados exportados, mais abaixo.

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

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

Ativar públicos-alvo para esse destino activate

IMPORTANT

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, o Adobe recomenda que você selecione 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 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 público-alvo 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 de público-alvo para pelo menos um dos públicos-alvo mapeados para o destino. Por exemplo, o perfil se qualificou para um dos públicos mapeados para o destino ou saiu de um dos públicos 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 públicos-alvo 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 público-alvo 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 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.

O que determina uma exportação de destino
O que está incluído na exportação de destino
  • Atributos e públicos mapeados servem como indicação para uma exportação de destino. Isso significa que se qualquer público mapeado alterar os estados (de null para realized ou de realized para exiting) ou se qualquer atributo mapeado for atualizado, uma exportação de destino será iniciada.
  • Como as identidades não podem ser mapeadas para destinos da API HTTP no momento, as alterações em qualquer identidade em um determinado perfil também determinam as exportações de destino.
  • Uma alteração em um atributo é definida como qualquer atualização no atributo, seja ou não o mesmo valor. Isso significa que uma substituição em um atributo é considerada uma alteração, mesmo que o valor em si não tenha sido alterado.
  • O objeto segmentMembership inclui o público mapeado no fluxo de dados de ativação, para o qual o status do perfil foi alterado após um evento de qualificação ou de saída de público. Observe que outros públicos não mapeados para os quais o perfil se qualificou podem fazer parte da exportação de destino, se esses públicos pertencerem à mesma política de mesclagem que o público mapeado no fluxo de dados de ativação.
  • Todas as identidades no objeto identityMap também estão incluídas (no momento, o Experience Platform não oferece suporte ao mapeamento de identidade no destino da API HTTP).
  • Somente os atributos mapeados são incluídos na exportação de destino.

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.

Um exemplo de fluxo de dados de destino da API HTTP.

Uma exportação de perfil para o destino pode ser determinada por um perfil qualificado para ou saindo dos três segmentos mapeados. No entanto, na exportação de dados, no objeto segmentMembership (consulte a seção Dados Exportados abaixo), outros públicos não mapeados poderão ser exibidos se esse perfil específico for membro deles e se eles compartilharem a mesma política de mesclagem que o público-alvo que acionou a exportação. Se um perfil se qualificar para o segmento Cliente com carros DeLoree, mas também for membro dos segmentos Filme "De volta para o futuro" assistido e Fãs de ficção científica, esses outros dois públicos-alvo também estarão presentes no objeto segmentMembership da exportação de dados, mesmo que eles não estejam mapeados no fluxo de dados, se eles compartilharem a mesma política de mesclagem com o segmento Cliente com carros DeLorea.

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 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 de interface do usuário que você selecionar no fluxo de destino de conexão para as opções Incluir nomes de segmento e Incluir carimbos de data/hora de segmento:

A amostra de exportação de dados abaixo inclui nomes de público na seção segmentMembership
code language-json
"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"
          }
        }
      }
A amostra de exportação de dados abaixo inclui carimbos de data/hora de público-alvo na seção segmentMembership
code language-json
"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

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.

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6