API를 통해 신규 메트릭 데이터를 직접 업로드하고 업로드 상태를 조회할 수 있는 API입니다.
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/requestsSelf-serve 데이터 업로드 요청하기
Self-serve 데이터를 CSV 포맷으로 업로드 요청하는 API로, Request Header 내 'Content-Type' 은 multipart/form-data 를 사용합니다.
Content-Type: multipart/form-data; charset=utf-8Request 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"][\"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 | 업로드 데이터가 기록된 날짜
| Required |
Group by | channel | string | 업로드 데이터에 대한 채널값
| 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값
| Optional |
Group by | os_name | string | 업로드 데이터에 대한 OS 이름값 | Optional |
Group by | term | string | 업로드 데이터에 대한 키워드값 | Optional |
Group by | country | string | 업로드 데이터에 대한 2자리 소문자 국가값 | Optional |
Group by | currency | string | ISO 4217에 따른 3자리 대문자 Currency 코드 | 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
업로드 진행 상태 조회하기
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"][\"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로 분리됩니다.
- 업로드된 Group by 값은 대시보드에서 조회 시 Case-sensitive하게 처리되므로, Airbridge에서 측정한 데이터 및 다
- 한번의 요청으로 업로드하는 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 |