Self-serve 데이터 업로드 요청 및 상태 조회하기

Authorization

에어브릿지 API의 보안 인증은 HTTP Request Header에 있는 Authorization Key에 API 토큰을 넣는 형식을 따르고 있습니다. 에어브릿지는 매번 API가 호출될 시 해당 토큰의 진실성 여부를 체크합니다.

호출의 예시는 아래와 같습니다.

curl ${API_ENDPOINT} -H "Authorization: AIRBRIDGE-API-KEY {API-TOKEN}"

API KEY는 대시보드 내 [Settings > Tokens]에서 확인할 수 있습니다.

Endpoint

Self-serve 데이터 업로드 요청 및 요청 상태 조회를 위해서는 아래 Endpoint를 사용합니다.

https://api.airbridge.io/custom-data-upload/v1.0/self-serve/requests

Self-serve 데이터 업로드 요청하기

Self-serve 데이터를 CSV 포맷으로 업로드 요청하는 API로, Request Header 내 'Content-Type' 은 multipart/form-data 를 사용합니다.

Content-Type: multipart/form-data; charset=utf-8

Request Example

curl --location --request POST 'https://api.airbridge.io/custom-data-upload/v1.0/self-serve/requests/' \
--header 'Authorization: AIRBRIDGE-API-KEY ${YOUR_API_KEY}' \
--form 'file=@"self-serve.csv"'

Response Example

{
	"requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
	"status": "uploaded",
	"prevStatus": null,
	"reason": null,
	"createdAt": "2022-08-09T08:59:15",
	"updatedAt": "2022-08-09T08:59:15"
}

Name	Description	Example
requestId	업로드 요청에 대한 고유 ID로, 요청마다 새로운 ID가 부여됩니다. 업로드 요청 상태 조회 시 해당 ID가 사용됩니다.	08844672-62d8-4da8-9d48-e14961651e0c
status	업로드 요청에 대한 진행 상태값입니다.	ingested
prevStatus	현재 status 이전의 상태값입니다.	validated
reason	status가 'failed'로 업로드 실패 이유에 대한 값입니다.	{"date": ["invalid date"]}
createdAt	요청이 생성된 날짜 및 시간입니다.	2022-08-09T08:59:15
updatedAt	업데이트가 진행된 날짜 및 시간입니다.	2022-08-09T08:59:15

CSV 파일 포맷 및 스키마

CSV 파일 내 컬럼명 및 컬럼값

Category	Column Name	Type	Description	Required
Group by	date	string	업로드 데이터가 기록된 날짜 * 'YYYY-MM-DD' 포맷의 데이터만 허용됩니다. * 과거 92일 이전의 날짜와 업로드 요청 시점보다 미래의 날짜는 업로드가 불가합니다. E.g. 2022-08-25	Required
Group by	channel	string	업로드 데이터에 대한 채널값 * 기존리포트에서 확인하실 수 있는 채널명과 대소문자까지 동일하게 입력하면 리포트에서 같은 채널로 Group by를 사용하실 수 있습니다.	Required
Group by	event_category	string	업로드 데이터의 카테고리 명칭 리포트에서 메트릭명으로도 사용됩니다	Required
Metric	event_value	double	업로드 데이터의 값	Required
Group by	campaign	string	업로드 데이터에 대한 캠페인값	Optional
Group by	ad_group	string	업로드 데이터에 대한 광고 그룹값	Optional
Group by	ad_creative	string	업로드 데이터에 대한 광고 소재값	Optional
Group by	content	string	업로드 데이터에 대한 광고 콘텐츠값	Optional
Group by	event_source	string	업로드 데이터에 대한 Source값 * app, web, tracking_link, sms_link 값만 가능(소문자 주의)	Optional
Group by	os_name	string	업로드 데이터에 대한 OS 이름값 E.g. Android, iOS	Optional
Group by	term	string	업로드 데이터에 대한 키워드값	Optional
Group by	country	string	업로드 데이터에 대한 2자리 소문자 국가값 E.g. kr, us, gb, fr	Optional
Group by	currency	string	ISO 4217에 따른 3자리 대문자 Currency 코드 E.g. KRW, USD	Optional
Group by	sub_publisher	string	업로드 데이터에 대한 하위 퍼블리셔값	Optional
Group by	sub_sub_publisher_1	string	업로드 데이터에 대한 하하위 퍼블리셔1값	Optional
Group by	sub_sub_publisher_2	string	업로드 데이터에 대한 하하위 퍼블리셔2값	Optional
Group by	sub_sub_publisher_3	string	업로드 데이터에 대한 하하위 퍼블리셔3값	Optional
Group by	is_first_event_per_device_id	boolean	true 또는 false 문자열 (소문자 주의)	Optional
Group by	is_first_event_per_user_id	boolean	true 또는 false 문자열 (소문자 주의)	Optional

🚧
대소문자 주의
Type이 string인 칼럼의 데이터들은 대소문자를 구분하여 인식합니다.

Airbridge에서 측정한 모바일 OS Name은 각각 'Android', 'iOS'로 기록하고 있지만 직접 업로드한 데이터의 OS Name을 'android', 'ios'로 입력한 경우 대시보드 내 별개의 Row로 분리됩니다. 따라서 Group by 결과를 위해서 ‘Android’, 'iOS’로 기록해주셔야 합니다.

Sample CSV File

CSV File 다운로드

업로드 진행 상태 조회하기

Self-serve 데이터 업로드 요청에 대한 진행 상태를 조회할 수 있는 API입니다. Self-serve 데이터 업로드 요청 API를 통해 발급받은 requestId를 Path Parameter로 입력하여 해당 요청 건에 대한 진행 상태를 조회합니다.

Request Example

curl "https://api.airbridge.io/custom-data-upload/v1.0/self-serve/requests/${requestId}" \
-H 'Authorization: AIRBRIDGE-API-KEY ${API_TOKEN}'

Name	Description	Example
requestId	업로드 요청에 대한 고유 ID로, 매 요청마다 새로운 ID가 부여됩니다. 업로드 요청 상태 조회 시 해당 ID가 사용됩니다.	08844672-62d8-4da8-9d48-e14961651e0c

Response Example

// 성공 시 Response
{
  "requestId": "08844672-62d8-4da8-9d48-e14961651e0c",
  "status": "succeeded",
  "prevStatus": "ingested",
  "reason": null,
  "createdAt": "2022-08-09T08:59:15",
  "updatedAt": "2022-08-09T08:59:59"
}

// 실패 시 Response
{
    "requestId": "846b78f9-1b6f-4ede-a253-619ca68fcebf",
    "status": "failed",
    "prevStatus": "uploaded",
    "reason": "{\"date\": [\"invalid date\"]}",
    "createdAt": "2022-08-24T11:54:18",
    "updatedAt": "2022-08-24T11:54:17"
}

Name	Description	Example
requestId	업로드 요청에 대한 고유 ID로, 매 요청마다 새로운 ID가 부여됩니다. 업로드 요청 상태 조회 시 해당 ID가 사용됩니다.	08844672-62d8-4da8-9d48-e14961651e0c
status	업로드 요청에 대한 진행 상태값입니다.	ingested
prevStatus	현재 status 이전의 상태값입니다.	validated
reason	status가 'failed'로 업로드 실패 이유에 대한 값입니다.	{"date": ["invalid date"]}
createdAt	요청이 생성된 날짜 및 시간입니다.	2022-08-09T08:59:15
updatedAt	업데이트가 진행된 날짜 및 시간입니다.	2022-08-09T08:59:15

Status

업로드 요청된 파일은 아래와 같은 프로세스로 진행되며, 각 상태값의 의미는 다음과 같습니다.

진행 프로세스: uploaded → validated → ingested → succeeded

Status	Description
uploaded	API를 통해 업로드가 완료된 상태
validated	업로드한 파일의 Validation이 완료된 상태
ingested	업로드한 파일을 DW에 반영한 상태로, 곧 이어서 Indexing이 시작될 예정
succeeded	업로드한 파일이 Indexing까지 완료된 상태로, Succeeded 상태 후 10분 이내에 대시보드 리포트에서 확인 가능
failed	업로드한 파일의 처리가 실패한 상태로, Response 중 'reason' 값을 참고하여 올바른 파일로 재업로드 필요

데이터 Overwrite 및 삭제

데이터 Ovewrite

Self-serve 데이터 업로드 시 'date', 'channel', 'event_category' 3개 필드값을 기준으로 기존에 동일한 조합이 있는 경우 기존 데이터를 신규 데이터로 Overwrite합니다.

[예시 시나리오1]

1. 2022-08-03: date, channel, campaign, ad_group 레벨의 데이터 업로드

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	80000

2. 2022-08-04: date, channel, campaign 레벨의 데이터 업로드

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	150000

3. 최종 반영: 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'event_category' 3개 필드값을 기준으로 8월 3일에 업로드한 동일 데이터가 있기 때문에 해당 데이터 대신 최종적으로 8월 4일 업로드 데이터만 남게됩니다. (ad group 값은 null)

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	150000

[예시 시나리오2]

1. 2022-08-03: date, channel, campaign 레벨의 데이터 업로드

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	100000

2. 2022-08-04: date, channel, campaign, ad_group 레벨의 데이터 업로드

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	150000

3. 최종 반영: 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'event_category' 3개 필드값을 기준으로 8월 3일에 업로드한 동일 데이터가 있기 때문에 해당 데이터 대신 최종적으로 8월 4일 업로드 데이터만 남게됩니다.(ad_group 값도 추가 업데이트됨)

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	150000

[예시 시나리오3]

1. 2022-08-03: date, channel, campaign, ad_group 레벨의 데이터 업로드

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	promotion_campaign	2030_female	self_event	10000
2022-08-01	owned_website	retargeting_campaign	2030_female	self_event	100000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event2	80000

2. 2022-08-04: date, channel, campaign, ad_group 레벨의 데이터 업로드

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	90000
2022-08-01	owned_website	ua_campaign	2030_female	self_event	120000

3. 최종 반영: 8월 4일 업로드 데이터 처리 시 'date', 'channel', 'event_category' 3개 필드값을 기준으로 8월 3일에 업로드 데이터 중 동일 데이터는 8월 4일의 데이터로 대체되며, 나머지 데이터는 그대로 남게됩니다.

date	channel	campaign	ad_group	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event2	80000
2022-08-01	owned_website	retargeting_campaign	2030_male	self_event	90000
2022-08-01	owned_website	ua_campaign	2030_female	self_event	120000

데이터 아카이브

기존에 업로드한 메트릭을 리포트에서 보이지 않게 하고 싶으신 경우 담당 CSM을 통해 요청해주세요.

유의 사항

현재 Self-serve 데이터 업로드 요청 및 상태 조회 API는 오너, 사내마케터 권한 계정의 API Token으로만 사용 가능합니다.
CSV 파일 내 컬럼명은 정해진 소문자 값만 허용됩니다.
CSV 파일 내 모든 Row에서 Required 칼럼은 값이 필수로 존재해야 합니다.
- Required 칼럼은 공백을 허용하지 않습니다. event_value도 공백이 아닌 0으로 입력하여 업로드해야 합니다.
CSV 파일 내 칼럼 순서는 업로드 기능에 영향을 미치지 않습니다.
channel, campaign 등 Group by에 사용되는 칼럼을 리포트상에서 표시되는 명칭과 동이랗게 업로드하실 경우, Group by 적용시 동일하게 적용됩니다.
- 업로드된 Group by 값은 대시보드에서 조회 시 Case-sensitive하게 처리되므로, Airbridge에서 측정한 데이터 및 다
  른 데이터와 함께 조회하기 위해서는 데이터 업로드 시 대소문자에 유의합니다. (channel, currency, country, os_name
  등)예를 들어 Airbridge에서 측정한 모바일 OS Name은 각각 'Android', 'iOS'로 기록하고 있지만 직접 업로드한 데이터의
  OS Name을 'android', 'ios'로 입력한 경우 대시보드 내 별개의 Row로 분리됩니다.
한번의 요청으로 업로드하는 CSV 파일의 최대 크기는 1MB입니다. 만약 1MB 이상 크기의 CSV 파일 업로드가 필요한 경우 gzip
압축을 한 뒤 업로드하거나, 여러 번의 API 호출로 나눠서 업로드 해주세요.
string 타입의 칼럼값은 256글자 이하로 제한됩니다.
칼럼명 및 칼럼값 앞뒤로 공백이 없도록 유의합니다.
event_category에는 영어와 숫자를 사용할 수 있스니다.
event_category에 , " \ 는 사용할 수 없습니다
등록된 메트릭은 Actuals Report와 Trends Reports에서 메트릭 선택 시 하단 Self-serve Metric 하위에서 업로드한
event_category 명으로 사용할 수 있습니다.
Upload 시 등록된 새로운 데이터는 (ex. campaign에 self_serve_test_campaign) Filter 사용시 선택옵션에 나타나지 않지만 freeform으로 등록해서 사용할 수 있습니다.

하나의 CSV 파일 내에 Group by와 event_category가 모두 동일한 Row들이 존재할 경우, 해당 데이터는 리포트에서 동일한 Row들이 합쳐진 값으로 표시됩니다.
업로드 데이터

date	channel	campaign	event_category	event_Value
2022-08-01	owned_website	retargeting_campaign	self_event	150000
2022-08-01	owned_website	retargeting_campaign	self_event	100000
2022-08-01	owned_website	retargeting_campaign	self_event	10000

리포트 표시

date	channel	campaign	event_category	event_value
2022-08-01	owned_website	retargeting_campaign	self_event	251000

Authorization

Endpoint

Self-serve 데이터 업로드 요청하기

Request Example

Response Example

CSV 파일 포맷 및 스키마

CSV 파일 내 컬럼명 및 컬럼값

🚧대소문자 주의

Sample CSV File

업로드 진행 상태 조회하기

Request Example

Response Example

Status

데이터 Overwrite 및 삭제

데이터 Ovewrite

[예시 시나리오1]

[예시 시나리오2]

[예시 시나리오3]

데이터 아카이브

유의 사항

🚧
대소문자 주의