[Ultimate]{class="badge positive"}

HTTP API 연결

개요 overview

IMPORTANT
이 대상은 다음에만 사용할 수 있습니다. Adobe Real-time Customer Data Platform Ultimate 고객.

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

프로필 데이터를 HTTP 끝점으로 보내려면 먼저 대상에 연결 위치: Adobe Experience Platform.

사용 사례 use-cases

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

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

지원되는 대상자 supported-audiences

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

대상자 원본
지원됨
설명
Segmentation Service
✓ 덧신
Experience Platform을 통해 생성된 대상자 세분화 서비스.
사용자 정의 업로드
✓ 덧신
대상 가져옴 csv 파일에서 Experience Platform으로 변환했습니다.

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

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

항목
유형
참고
내보내기 유형
프로필 기반
의 매핑 화면에서 선택한 대로 원하는 스키마 필드(예: 이메일 주소, 전화번호, 성)와 함께 세그먼트의 모든 멤버를 내보냅니다. 대상 활성화 워크플로.
내보내기 빈도
스트리밍
스트리밍 대상은 "항상" API 기반 연결입니다. 대상자 평가를 기반으로 Experience Platform에서 프로필이 업데이트되는 즉시 커넥터가 업데이트 다운스트림을 대상 플랫폼으로 전송합니다. 자세한 내용 스트리밍 대상.

전제 조건 prerequisites

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

  • REST API를 지원하는 HTTP 끝점이 있어야 합니다.
  • HTTP 끝점은 Experience Platform 프로필 스키마를 지원해야 합니다. HTTP API 대상에서는 서드파티 페이로드 스키마로의 변환이 지원되지 않습니다. 다음을 참조하십시오. 내보낸 데이터 섹션에 Experience Platform 출력 스키마의 예를 추가했습니다.
  • HTTP 끝점은 헤더를 지원해야 합니다.
TIP
다음을 사용할 수도 있습니다. Adobe Experience Platform Destination SDK 통합을 설정하고 Experience Platform 프로필 데이터를 HTTP 끝점으로 전송합니다.

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

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

mTLS 는 정보를 공유하는 두 당사자가 데이터를 공유하기 전에 자신이 누구인지를 확인하는 상호 인증을 위한 종단간 보안 방법입니다. mTLS 에 비해 추가 단계가 포함됩니다. TLS를 사용하여 서버에서 클라이언트의 인증서를 요청하고 클라이언트 끝에서 확인합니다.

을(를) 사용하려면 mTLS 포함 HTTP API 대상, 서버 주소 입력 대상 세부 사항 페이지에 다음이 있어야 합니다. TLS 프로토콜이 비활성화되고 mTLS 활성화되었습니다. 다음과 같은 경우 TLS 1.2 프로토콜이 끝점에서 여전히 활성화되어 있으므로 클라이언트 인증을 위한 인증서가 전송되지 않습니다. 이는 을(를) 사용하는 것을 의미합니다. mTLS (으)로 HTTP API 대상, "수신" 서버 엔드포인트는 mTLS연결 끝점만 활성화했습니다.

인증서 다운로드 certificate

다음을 확인하려는 경우: Common Name (CN) 및 Subject Alternative Names (SAN) 추가적인 타사 유효성 검사를 수행하려면 아래 인증서를 다운로드할 수 있습니다.

허용 목록에 추가하다 IP 주소 ip-address-allowlist

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

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

HTTP API 대상은 HTTP 끝점에 대한 여러 인증 유형을 지원합니다.

  • 인증이 없는 HTTP 끝점;
  • 전달자 토큰 인증;
  • OAuth 2.0 클라이언트 자격 증명 본문 양식 인증, 사용 client ID, client secret, 및 grant type 아래 예와 같이 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

IMPORTANT
대상에 연결하려면 다음이 필요합니다. 대상 보기대상 관리 액세스 제어 권한. 읽기 액세스 제어 개요 필요한 권한을 얻으려면 제품 관리자에게 문의하십시오.

이 대상에 연결하려면 다음과같이 하십시오. 대상 구성 자습서. 이 대상에 연결할 때 다음 정보를 제공해야 합니다.

인증 정보 authentication-information

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

을(를) 선택하는 경우 전달자 토큰 인증 유형 - HTTP 끝점에 연결하려면 아래 필드를 입력하고 다음을 선택합니다. 대상에 연결:

전달자 토큰 인증을 사용하여 HTTP API 대상에 연결할 수 있는 UI 화면의 이미지입니다.

  • 전달자 토큰: HTTP 위치에 인증할 전달자 토큰을 삽입합니다.

인증 없음 no-authentication

을(를) 선택하는 경우 없음 http 끝점에 연결하는 인증 유형:

인증을 사용하지 않고 HTTP API 대상에 연결할 수 있는 UI 화면의 이미지입니다.

이 인증 열기를 선택할 때는 선택하기만 하면 됩니다. 대상에 연결 엔드포인트에 대한 연결이 설정됩니다.

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

을(를) 선택하는 경우 OAuth 2 암호 인증 유형 - HTTP 끝점에 연결하려면 아래 필드를 입력하고 다음을 선택합니다. 대상에 연결:

암호 인증이 있는 OAuth 2를 사용하여 HTTP API 대상에 연결할 수 있는 UI 화면의 이미지입니다.

  • 토큰 URL 액세스: 액세스 토큰을 발행하고 선택적으로 토큰을 새로 고치는 사용자 측의 URL입니다.
  • 클라이언트 ID: client ID 시스템이 Adobe Experience Platform에 할당하는 것입니다.
  • 클라이언트 암호: client secret 시스템이 Adobe Experience Platform에 할당하는 것입니다.
  • 사용자 이름: HTTP 끝점에 액세스하기 위한 사용자 이름입니다.
  • 암호: HTTP 끝점에 액세스하기 위한 암호입니다.

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

을(를) 선택하는 경우 OAuth 2 클라이언트 자격 증명 인증 유형 - HTTP 끝점에 연결하려면 아래 필드를 입력하고 다음을 선택합니다. 대상에 연결:

클라이언트 자격 증명 인증과 함께 OAuth 2를 사용하여 HTTP API 대상에 연결할 수 있는 UI 화면의 이미지입니다.

  • 토큰 URL 액세스: 액세스 토큰을 발행하고 선택적으로 토큰을 새로 고치는 사용자 측의 URL입니다.

  • 클라이언트 ID: client ID 시스템이 Adobe Experience Platform에 할당하는 것입니다.

  • 클라이언트 암호: client secret 시스템이 Adobe Experience Platform에 할당하는 것입니다.

  • 클라이언트 자격 증명 유형: 끝점에서 지원하는 OAuth2 클라이언트 자격 증명 부여 유형을 선택합니다.

    • 본문이 인코딩됨: 이 경우 client ID 및 client secret 포함 요청 본문에서 을(를) 대상으로 보냈습니다. 예를 보려면 지원되는 인증 유형 섹션.
    • 기본 인증: 이 경우 client ID 및 client secret 포함 다음에서 Authorization 머리글 base64로 인코딩되어 대상으로 전송된 후 예를 보려면 지원되는 인증 유형 섹션.

대상 세부 정보 입력 destination-details

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

HTTP 대상 세부 사항에 대한 완료된 필드를 보여주는 UI 화면의 이미지입니다.

  • 이름: 나중에 이 대상을 인식할 이름을 입력합니다.
  • 설명: 나중에 이 대상을 식별하는 데 도움이 되는 설명을 입력합니다.
  • 헤더: 대상 호출에 포함할 사용자 지정 헤더를 다음 형식으로 입력합니다. header1:value1,header2:value2,...headerN:valueN.
  • HTTP 끝점: 프로필 데이터를 전송할 HTTP 끝점의 URL입니다.
  • 쿼리 매개 변수: 원할 경우 HTTP 끝점 URL에 쿼리 매개 변수를 추가할 수 있습니다. 사용하는 쿼리 매개변수 형식(예: parameter1=value&parameter2=value)을 지정합니다.
  • 세그먼트 이름 포함: 데이터 내보내기에 내보낼 대상자의 이름을 포함하려면 전환합니다. 이 옵션을 선택한 데이터 내보내기의 예는 다음을 참조하십시오. 내보낸 데이터 추가 아래에 섹션을 추가했습니다.
  • 세그먼트 타임스탬프 포함: 대상자를 만들고 업데이트할 때 UNIX 타임스탬프와, 대상자가 활성화 대상에 매핑될 때 UNIX 타임스탬프를 데이터 내보내기에 포함하도록 하려면 전환합니다. 이 옵션을 선택한 데이터 내보내기의 예는 다음을 참조하십시오. 내보낸 데이터 추가 아래에 섹션을 추가했습니다.

경고 활성화 enable-alerts

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

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

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

IMPORTANT

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

대상 속성 attributes

다음에서 속성 선택 Adobe은 다음 단계에서 고유 식별자를 선택할 것을 권장합니다. 유니온 스키마. 대상으로 내보낼 고유 식별자 및 기타 XDM 필드를 선택합니다.

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

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

  • 프로필 업데이트는 대상에 매핑된 대상자 중 하나 이상에 대한 대상자 멤버십 변경에 따라 결정되었습니다. 예를 들어 프로필이 대상에 매핑된 대상자 중 하나에 대해 자격이 있거나 대상에 매핑된 대상자 중 하나를 종료했습니다.
  • 프로필 업데이트는 의 변경 사항으로 결정됩니다. id 맵. 예를 들어 대상에 매핑된 대상자 중 하나에 대해 이미 자격이 있는 프로필이 ID 맵 특성에 새 ID를 추가했습니다.
  • 프로필 업데이트는 대상에 매핑된 속성 중 하나 이상에 대한 속성 변경에 의해 결정되었습니다. 예를 들어 매핑 단계에서 대상에 매핑된 속성 중 하나가 프로필에 추가됩니다.

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

변경 내용이 있는 위치에 관계없이 매핑된 모든 속성을 프로파일에 대해 내보냅니다. 따라서 위의 예에서는 속성 자체가 변경되지 않았더라도 이러한 5개의 새 프로필에 대해 매핑된 모든 속성을 내보냅니다.

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

주어진 프로필에 대해 내보내는 데이터와 관련하여 의 두 가지 다른 개념을 이해하는 것이 중요합니다 http API 대상에 대한 데이터 내보내기를 결정하는 사항내보내기에 포함되는 데이터.

대상 내보내기를 결정하는 사항
대상 내보내기에 포함된 사항
  • 매핑된 속성 및 대상은 대상 내보내기에 대한 큐 역할을 합니다. 즉, 매핑된 대상자의 상태가 (에서) 변경되는 경우 nullrealized 또는 부터 realizedexiting) 매핑된 속성이 업데이트되면 대상 내보내기가 시작됩니다.
  • ID는 현재 HTTP API 대상에 매핑될 수 없으므로 주어진 프로필의 ID를 변경하면 대상 내보내기도 결정됩니다.
  • 속성에 대한 변경 사항은 동일한 값인지 여부에 관계없이 속성에 대한 모든 업데이트로 정의됩니다. 즉, 값 자체가 변경되지 않았더라도 속성에 대한 덮어쓰기를 변경 사항으로 간주합니다.
  • 다음 segmentMembership 객체에는 활성화 데이터 흐름에 매핑된 대상자가 포함됩니다. 이 대상자 상태는 자격 또는 대상자 종료 이벤트 후 변경되었습니다. 프로필의 자격이 되는 매핑되지 않은 다른 대상자가 동일한 대상자에 속하는 경우 대상 내보내기의 일부가 될 수 있습니다 병합 정책 활성화 데이터 흐름에서 매핑된 대상자입니다.
  • 의 모든 ID identityMap 개체도 포함됩니다(현재 Experience Platform은 HTTP API 대상에서 ID 매핑을 지원하지 않음).
  • 매핑된 속성만 대상 내보내기에 포함됩니다.

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

HTTP API 대상 데이터 흐름의 예입니다.

대상으로 프로필을 내보내는 방법은 대상 중 하나를 선택하거나 종료하는 프로필에 의해 결정됩니다. 세 개의 매핑된 세그먼트. 그러나 데이터 내보내기에서 segmentMembership 오브젝트(참조) 내보낸 데이터 아래 섹션) 특정 프로필이 멤버이고 내보내기를 트리거한 대상과 동일한 병합 정책을 공유하는 경우 매핑되지 않은 다른 대상자가 나타날 수 있습니다. 프로필이 다음에 대한 자격이 있는 경우: DeLorean 자동차를 사용하는 고객 세그먼트이지만 의 구성원이기도 합니다. Back to the Future 시청 동영상 및 의 팬 세그먼트를 가리키면 이 다른 두 대상도 segmentMembership 데이터 흐름에서 매핑되지 않은 데이터 내보내기의 객체입니다. 이러한 객체가 과 동일한 병합 정책을 공유하는 경우 DeLorean 자동차를 사용하는 고객 세그먼트.

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

내역 데이터 채우기 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 섹션
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"
          }
        }
      }
아래의 데이터 내보내기 샘플에는 의 대상 타임스탬프가 포함됩니다. 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,
          }
        }
      }

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

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

HTTP API 대상에 대한 요청이 실패한 경우 Experience Platform은 실패한 요청을 저장하고 두 번 다시 시도하여 요청을 엔드포인트에 보냅니다.

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