애드혹 활성화 API를 통해 온디맨드로 대상자 활성화

개요 overview

임시 활성화 API 를 사용하면 마케터가 즉시 활성화가 필요한 상황에 대해 대상을 빠르고 효율적으로 프로그래밍 방식으로 활성화할 수 있습니다.

임시 활성화 API를 사용하여 필요에 따라 대상을 일괄 파일 기반 대상으로, v4부터 스트리밍 및 API 기반 대상으로 활성화합니다. 이 자습서에서는 아래의 임시 활성화 실행 트리거를 참조하십시오.

아래 다이어그램은 24시간마다 Experience Platform에서 발생하는 세분화 작업을 포함하여 임시 활성화 API를 통해 대상을 활성화하기 위한 전체적인 워크플로우를 보여 줍니다.

사용 사례 use-cases

플래시 판매 또는 프로모션 flash-sales

온라인 retailer은 제한된 플래시 세일을 준비하고 있으며 고객에게 짧은 시간에 알리기를 원합니다. 마케팅 팀은 Experience Platform 임시 활성화 API를 통해 온디맨드로 대상자를 내보내고 프로모션 이메일을 신속하게 고객 기반으로 전송할 수 있습니다.

최신 이벤트 또는 속보 current-events

A호텔 측은 앞으로 며칠간 악천후가 예상되며, 해당 팀은 도착 손님들에게 신속히 알리기를 원하기 때문에 그에 맞는 계획을 세울 수 있다. 마케팅 팀은 Experience Platform 애드혹 활성화 API 를 사용하여 대상을 온디맨드로 내보내고 게스트에게 알릴 수 있습니다.

통합 테스트 integration-testing

IT 관리자는 Experience Platform 임시 활성화 API를 사용하여 대상을 온디맨드로 내보낼 수 있으므로 Adobe Experience Platform과의 사용자 지정 통합을 테스트하고 모든 것이 올바르게 작동하는지 확인할 수 있습니다.

스트리밍 대상에 대한 대상 새로 고침 audience-refresh-streaming

스트리밍 또는 API 기반 대상은 Adobe Experience Platform에서 받는 대상 멤버십에 TTL(time-to-live)을 적용합니다. 해당 TTL이 대상 측에서 만료되면 이전에 자격을 부여한 프로필은 Experience Platform에서 자격을 유지한 경우에도 비활성 상태로 처리됩니다. 마케팅 팀은 애드혹 활성화 API v4를 사용하여 예정된 다음 새로 고침을 기다리지 않고 고객의 전체 현재 멤버십을 온디맨드로 다시 전송할 수 있습니다. 이 자습서에서는 아래의 임시 활성화 실행 트리거를 참조하십시오.

가드레일 guardrails

임시 활성화 API를 사용할 때는 다음 보호 기능에 유의하십시오.

세그먼테이션 고려 사항 segmentation-considerations

Adobe Experience Platform은(는) 예약된 세분화 작업을 24시간마다 한 번씩 실행합니다. 임시 활성화 API는 최신 세분화 결과를 기반으로 실행됩니다.

1단계: 사전 요구 사항 prerequisites

Adobe Experience Platform API를 호출하려면 먼저 다음 전제 조건을 충족하는지 확인하십시오.

2단계: 자격 증명 수집 credentials

Experience Platform API를 호출하려면 먼저 인증 자습서를 완료해야 합니다. 인증 자습서를 완료하면 아래와 같이 모든 Experience Platform API 호출에서 필요한 각 헤더에 대한 값이 제공됩니다.

Experience Platform의 리소스는 특정 가상 샌드박스로 분리될 수 있습니다. Experience Platform API 요청에서 작업이 수행될 샌드박스의 이름과 ID를 지정할 수 있습니다. 이러한 매개 변수는 선택 사항입니다.

페이로드(POST, PUT, PATCH)가 포함된 모든 요청에는 추가 미디어 유형 헤더가 필요합니다.

API 참조 설명서 api-reference-documentation

이 자습서에서 모든 API 작업에 대한 참조 설명서를 함께 찾을 수 있습니다. Ad Hoc Activation API 참조를 참조하십시오.

3단계: Experience Platform UI에서 활성화 흐름 만들기 activation-flow

임시 활성화 API를 통해 대상을 활성화하려면 먼저 선택한 대상에 대해 Experience Platform UI에 활성화 흐름이 구성되어 있어야 합니다.

여기에는 활성화 워크플로, 대상자 선택, 일정 구성 및 활성화가 포함됩니다. UI 또는 API를 사용하여 활성화 플로우를 만들 수 있습니다.

4단계: 최신 대상 내보내기 작업 ID 가져오기(v2에서는 필요하지 않음) segment-export-id

배치 대상에 대한 활성화 흐름을 구성하면 예약된 세분화 작업이 24시간마다 자동으로 실행됩니다.

임시 활성화 작업을 실행하려면 먼저 최신 대상자 내보내기 작업의 ID를 얻어야 합니다. 임시 활성화 작업 요청에서 이 ID를 전달해야 합니다.

여기에 설명된 지침에 따라 모든 대상자 내보내기 작업 목록을 검색합니다.

응답에서 아래의 스키마 속성을 포함하는 첫 번째 레코드를 찾습니다.

"schema":{
   "name":"_xdm.context.profile"
}

대상 내보내기 작업 ID는 아래와 같이 id 속성에 있습니다.

5단계: 임시 활성화 작업 실행 activation-job

Adobe Experience Platform은(는) 예약된 세분화 작업을 24시간마다 한 번씩 실행합니다. 임시 활성화 API는 최신 세분화 결과를 기반으로 실행됩니다.

임시 활성화 작업을 실행하기 전에 대상에 대해 예약된 대상 내보내기 작업이 완료되었는지 확인하십시오. 활성화 흐름의 상태를 모니터링하는 방법에 대한 자세한 내용은 대상 데이터 흐름 모니터링을 참조하십시오. 예를 들어 활성화 데이터 흐름에서 처리 중 상태가 표시되면 임시 활성화 작업을 실행하여 전체 파일을 내보내기 전에 완료될 때까지 기다리십시오.

대상자 내보내기 작업이 완료되면 활성화를 트리거할 수 있습니다.

요청 request

세그먼테이션이 아닌 서비스 대상(예: 외부 또는 사용자 지정 업로드 대상)의 경우 외부 대상 ID가 아니라 요청에서 Experience Platform이 생성한 대상 ID를 지정해야 합니다. 대상 UI에서 대상 세부 사항 페이지를 열면 대상 요약 패널의 맨 위에 ID#(으)로 표시된 시스템 생성 ID와 UUID를 찾을 수 있습니다.

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

속성

설명

• destinationId1
• destinationId2

대상자를 활성화할 대상 인스턴스의 ID입니다. 대상 > 찾아보기 탭으로 이동한 다음 원하는 대상 행을 클릭하여 오른쪽 레일에서 대상 ID를 표시하면 Experience Platform UI에서 이러한 ID를 가져올 수 있습니다. 자세한 내용은 대상 작업 영역 설명서를 참조하세요.

• segmentId1
• segmentId2
• segmentId3

선택한 대상에 활성화할 대상의 ID입니다. 임시 API를 사용하여 Experience Platform 생성 대상과 외부(사용자 지정 업로드) 대상을 내보낼 수 있습니다. 외부 대상을 활성화할 때 대상 ID 대신 시스템 생성 ID를 사용하십시오. 대상 UI의 대상 요약 보기에서 시스템 생성 ID를 찾을 수 있습니다.
{width="100" modal="regular"}
{width="100" modal="regular"}

내보내기 ID가 있는 요청 request-export-ids

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

응답 response

성공적인 응답은 HTTP 상태 200을 반환합니다.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

API 오류 처리 api-error-handling

Destination SDK API 엔드포인트는 일반적인 Experience Platform API 오류 메시지 원칙을 따릅니다. Experience Platform 문제 해결 안내서에서 API 상태 코드 및 요청 헤더 오류를 참조하십시오.

Ad-hoc 활성화 API와 관련된 API 오류 코드 및 메시지 specific-error-messages

임시 활성화 API를 사용하는 경우 이 API 끝점과 관련된 오류 메시지가 표시될 수 있습니다. 표가 표시될 때 이를 처리하는 방법을 이해하려면 표를 검토하십시오.

(Beta) 임시 활성화 실행 트리거 streaming-destinations

임시 활성화 API v4를 사용하여 스트리밍 또는 API 기반 대상에 대한 대상의 온디맨드 전체 멤버십 새로 고침, 지금 활성화​를 트리거합니다.

많은 스트리밍 및 API 기반 대상이 Adobe Experience Platform에서 받은 대상 멤버십에 TTL(time-to-live)을 적용합니다. 해당 TTL이 대상 측에서 만료되면 이전에 자격을 부여한 프로필은 Experience Platform에서 자격을 유지한 경우에도 비활성 상태로 처리됩니다. v4 애드혹 활성화 실행을 트리거하여 다음에 예약된 새로 고침을 기다리지 않고 기존 스트리밍 활성화 파이프라인을 통해 현재 모든 자격을 갖춘 프로필을 다시 보냅니다.

Experience Platform UI에서 이 새로 고침을 트리거할 수도 있습니다. 스트리밍 대상에 대해 지금 활성화를 읽어 보십시오.

스트리밍 보호 streaming-guardrails

스트리밍 대상에 대한 임시 활성화는 다음 제한을 적용합니다.

스트리밍 요청 streaming-request

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

스트리밍 응답 streaming-response

성공적인 응답은 HTTP 상태 202(허용됨)를 반환하고 요청된 대상자당 하나의 스트리밍 작업을 만듭니다.

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

지난 24시간 내에 이 데이터 흐름에 대해 동일한 대상이 이미 트리거된 경우 HTTP 409와 다시 시도할 수 있을 때까지의 시간(초)을 나타내는 Retry-After 헤더로 요청이 거부됩니다.

관련 정보 related-information