[Ultimate]{class="badge positive"}

HTTP API 연결

개요 overview

HTTP API 대상은 프로필 데이터를 타사 HTTP 끝점으로 전송하는 데 도움이 되는 Experience Platform 스트리밍 대상입니다.

프로필 데이터를 HTTP 끝점으로 보내려면 먼저 Experience Platform에서 대상에 연결해야 합니다.

사용 사례 use-cases

HTTP API 대상을 사용하여 XDM 프로필 데이터 및 대상을 일반 HTTP 종단점으로 내보냅니다. 여기에서 자체 분석을 실행하거나 Experience Platform에서 내보낸 프로필 데이터에 대해 필요할 수 있는 다른 작업을 수행할 수 있습니다.

HTTP 끝점은 고객의 자체 시스템 또는 타사 솔루션이 될 수 있습니다.

지원되는 대상자 supported-audiences

이 섹션에서는 이 대상으로 내보낼 수 있는 대상자 유형을 설명합니다.

대상 데이터 유형별 지원되는 대상:

내보내기 유형 및 빈도 export-type-frequency

대상 내보내기 유형 및 빈도에 대한 자세한 내용은 아래 표를 참조하십시오.

사전 요구 사항 prerequisites

HTTP API 대상을 사용하여 Experience Platform에서 데이터를 내보내려면 다음 사전 요구 사항을 충족해야 합니다.

mTLS 프로토콜 지원 및 인증서 mtls-protocol-support

Mutual Transport Layer Security​(mTLS)를 사용하여 HTTP API 대상 연결에 대한 아웃바운드 연결에서 보안을 강화할 수 있습니다.

mTLS는 데이터를 공유하기 전에 정보를 공유하는 양쪽이 자신의 소유자임을 보장하는 상호 인증 프로토콜입니다. mTLS에는 표준 TLS와 비교하여 추가 단계가 포함되어 있습니다. 서버에서 클라이언트의 인증서를 요청하고 확인하는 반면 클라이언트는 서버의 인증서를 확인합니다.

mTLS 고려 사항 mtls-considerations

HTTP API 대상에 대한 mTLS 지원은 프로필 내보내기가 전송되는 데이터 수신 끝점​ (대상 세부 정보의 ​​ HTTP 끝점​​ 필드)에만 ​적용됩니다.

데이터 내보내기를 위한 mTLS 구성 configuring-mtls

HTTP API 대상에 mTLS를 사용하려면 대상 세부 정보 페이지에서 구성한 HTTP 끝점(데이터 수신 끝점)에 TLS 프로토콜이 비활성화되어 있어야 하며 mTLS만 활성화되어야 합니다. 끝점에서 TLS 1.2 프로토콜이 여전히 활성화되어 있으면 클라이언트 인증을 위한 인증서가 전송되지 않습니다. 즉, HTTP API 대상에 mTLS를 사용하려면 데이터 수신 서버 끝점이 mTLS 전용 활성화 연결 끝점이어야 합니다.

인증서 세부 정보 검색 및 검사 certificate

추가 타사 유효성 검사를 위해 CN(일반 이름) 및 SAN(주체 대체 이름)과 같은 인증서 세부 정보를 검사하려면 API를 사용하여 인증서를 검색하고 응답에서 해당 필드를 추출하십시오.

자세한 내용은 공개 인증서 끝점 설명서를 참조하세요.

IP 주소 ip-address-allowlist

고객 보안 및 규정 준수 요구 사항을 충족하기 위해 Experience Platform에서는 HTTP API 대상에 대해 허용 목록에 추가하다할 수 있는 정적 IP 목록을 제공합니다. 스트리밍 대상에 대한 IP 주소의 전체 IP 목록(허용 목록에 추가하다)을 참조하십시오.

지원되는 인증 유형 supported-authentication-types

HTTP API 대상은 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'

대상에 연결 connect-destination

이 대상에 연결하려면 대상 구성 자습서에 설명된 단계를 따르십시오. 이 대상에 연결할 때 다음 정보를 제공해야 합니다.

인증 정보 authentication-information

전달자 토큰 인증 bearer-token-authentication

HTTP 끝점에 연결할 전달자 토큰 인증 유형을 선택한 경우 아래 정보를 입력하고 대상에 연결​을 선택하십시오.

인증 없음 no-authentication

없음 인증 유형을 선택하여 HTTP 끝점에 연결하는 경우:

이 인증 옵션을 선택하면 대상에 연결​만 선택하면 끝점에 연결됩니다.

OAuth 2 암호 인증 oauth-2-password-authentication

HTTP 끝점에 연결할 OAuth 2 암호 인증 유형을 선택한 경우 아래 정보를 입력하고 대상에 연결​을 선택하십시오.

OAuth 2 클라이언트 자격 증명 인증 oauth-2-client-credentials-authentication

HTTP 끝점에 연결할 OAuth 2 클라이언트 자격 증명 인증 유형을 선택한 경우 아래 정보를 입력하고 대상에 연결​을 선택하십시오.

대상 세부 정보 입력 destination-details

대상에 대한 세부 정보를 구성하려면 아래의 필수 및 선택 필드를 채우십시오. UI에서 필드 옆에 있는 별표는 필드가 필수임을 나타냅니다.

경고 활성화 enable-alerts

경고를 활성화하여 대상에 대한 데이터 흐름 상태에 대한 알림을 받을 수 있습니다. 목록에서 경고를 선택하여 데이터 흐름 상태에 대한 알림을 수신합니다. 경고에 대한 자세한 내용은 UI를 사용하여 대상 경고 구독에 대한 안내서를 참조하십시오.

대상 연결에 대한 세부 정보를 모두 제공했으면 다음​을 선택합니다.

이 대상으로 대상자 활성화 activate

이 대상으로 대상을 활성화하는 방법에 대한 지침은 스트리밍 프로필 내보내기 대상으로 대상 데이터 활성화를 참조하십시오.

대상 속성 attributes

특성 선택 단계에서는 유니온 스키마에서 고유 식별자를 선택하는 것이 좋습니다. 대상으로 내보낼 고유 식별자 및 기타 XDM 필드를 선택합니다.

프로필 내보내기 동작 profile-export-behavior

Experience Platform은 대상 자격 또는 기타 중요한 이벤트 후에 프로필에 대한 관련 업데이트가 발생한 경우에만 데이터를 API 종단점으로 내보내도록 HTTP API 대상에 대한 프로필 내보내기 동작을 최적화합니다. 프로필은 다음과 같은 경우 대상으로 내보내집니다.

위에서 설명한 모든 경우에 관련 업데이트가 발생한 프로필만 대상으로 내보냅니다. 예를 들어 대상 플로우에 매핑된 대상자에 100명의 멤버가 있고 5개의 새 프로필이 대상자에 적합한 경우 대상으로의 내보내기는 증분 것이며 5개의 새 프로필만 포함합니다.

데이터 내보내기를 결정하는 사항 및 내보내기에 포함되는 사항 what-determines-export-what-is-included

지정된 프로필에 대해 내보내는 데이터와 관련하여 HTTP API 대상으로 데이터 내보내기를 결정하는 요소 및 내보내기에 포함되는 데이터​의 두 가지 다른 개념을 이해하는 것이 중요합니다.

예를 들어 데이터 흐름에서 3개의 대상이 선택되고 대상에 4개의 속성이 매핑되는 HTTP 대상에 대한 이 데이터 흐름을 고려해 보십시오.

프로필이 3개의 매핑된 대상자 중 하나를 사용하거나 종료하면 대상으로 프로필 내보내기가 트리거됩니다. 매핑된 대상자만 포함 옵션이 켜져 있으면 segmentMembership 개체(아래 내보낸 데이터 참조)에 매핑된 대상자 세 개만 포함됩니다. 이 옵션이 꺼져 있으면 segmentMembership 개체가 매핑되지 않은 대상도 포함할 수 있습니다. 해당 프로필이 이 대상들의 구성원이고 내보내기를 트리거한 대상과 동일한 병합 정책을 공유하는 경우 이 개체가 대상자와 매핑되지 않은 대상자를 포함할 수 있습니다. 예를 들어, 프로필이 Demorean Cars를 사용하는 고객 대상자를 대상으로 하지만 Watched “Back to the Future” 영화 및 Sf 팬 대상자의 멤버인 경우 Demorean Cars를 사용하는 고객 대상자와 동일한 병합 정책을 공유하는 경우 매핑된 대상자만 포함​이 꺼지면 해당 두 대상자도 segmentMembership 개체에 나타납니다.

프로필 속성 관점에서 위에 매핑된 네 개의 속성에 대한 변경 사항은 대상 내보내기를 결정하고 프로필에 있는 네 개의 매핑된 속성 중 하나는 데이터 내보내기에 표시됩니다.

내역 데이터 채우기 historical-data-backfill

기존 대상에 새 대상을 추가하거나 새 대상을 만들고 대상에 대상을 매핑하면 Experience Platform에서 이전 대상 자격 데이터를 대상으로 내보냅니다. 대상에 대상을 추가하기 전에 대상 이전​에 대해 자격이 있는 프로필은 약 1시간 내에 대상으로 내보냅니다.

내보낸 데이터 exported-data

내보낸 Experience Platform 데이터는 HTTP 대상에 JSON 형식으로 도착합니다. 예를 들어, 아래 내보내기에는 특정 대상에 대해 자격이 있고 다른 두 대상의 멤버이며 다른 대상을 종료한 프로필이 포함됩니다. 내보내기에는 프로필 속성 이름, 성, 생년월일 및 개인 이메일 주소도 포함됩니다. 이 프로필의 ID는 ECID와 이메일입니다.

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

다음은 대상 이름 포함 및 대상 타임스탬프 포함 옵션에 대해 연결 대상 흐름에서 선택한 UI 설정에 따라 내보낸 데이터의 추가 예입니다.

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

제한 및 재시도 정책 limits-retry-policy

시간의 95%를 차지하는 Experience Platform은 HTTP 대상에 대한 각 데이터 흐름의 초당 요청 수가 10,000개 미만인 상태로 성공적으로 전송된 메시지에 대해 10분 미만의 처리량 지연 시간을 제공하려고 합니다.

HTTP API 대상에 대한 요청이 실패하면 Experience Platform은 이 요청을 저장하고 두 번 다시 시도합니다.

문제 해결 troubleshooting

신뢰할 수 있는 데이터 전달을 보장하고 시간 초과 문제를 방지하려면 HTTP 끝점이 필수 구성 요소 섹션에 지정된 대로 Experience Platform 요청에 2초 이내에 응답하는지 확인하십시오. 시간이 오래 걸리는 응답은 시간 초과 오류를 발생시킵니다.