Amplitude HTTP API 데이터 내보내기

Amplitude HTTP API 데이터 내보내기

Amplitude의 Export API는 프로젝트의 raw 이벤트 데이터를 내보낼 수 있게 해 주는 HTTP API예요. 저장된 이벤트를 시간 범위로 조회해 압축된 JSON 파일 묶음으로 받아올 수 있어요. 서버에서 직접 호출하는 REST 방식이라 분석·백업·워크플로우 연동에 활용하기 좋아요.

출처: 문서

본문

Regions(리전)

Base URL은 프로젝트의 데이터 리전(데이터 상주 위치)에 따라 달라져요. 기본 Base URL을 사용하다가, 프로젝트가 Amplitude EU 데이터 센터를 쓰는 경우에만 아래 표의 EU Base URL을 사용하면 돼요.

요청은 기본값 https://amplitude.com, EU의 경우 https://analytics.eu.amplitude.com로 보내요. https://analytics.amplitude.com 호스트는 Analytics 웹 앱(브라우저 UI)이니까, REST 요청에는 표의 호스트를 사용하고 analytics.amplitude.com은 쓰지 마세요.

Considerations(고려 사항)

• 날짜 범위는 이벤트 데이터가 Amplitude 서버에 업로드된 시각(server_upload_time)을 기준으로 해요. Export API는 UTC 타임스탬프로 이벤트를 반환하고, 서버가 데이터를 받은 뒤 2시간 이내에 내보낼 수 있어요. 예를 들어 오후 8~9시 사이에 보낸 데이터는 오후 9시부터 적재되기 시작해서 오후 11시부터 Export API로 확인할 수 있어요. 플랫폼 리포팅에는 지연이 없고, 내보내기만 지연돼요.
• Export API는 cross-project view를 지원하지 않아요. view는 자체 데이터를 소유하지 않기 때문이에요. view의 모든 데이터를 내보내려면 해당 데이터를 수집한 원본 프로젝트들에 대해 Export API를 호출하세요.
• 크기 제한은 4GB예요. 4GB를 넘으면 요청이 400 응답을 반환하니까, 더 작은 시간 범위로 내보내세요. 한 시간 치 데이터가 4GB를 넘을 경우에는 Amazon S3 export를 사용하세요.
• 하루 전체를 내보내려면 T00부터 T23까지를 사용하세요. 예: GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220101T23'
• 한 번에 조회할 수 있는 최대 기간은 365일이에요.

Request(요청)

GET https://amplitude.com/api/2/export

cURL

curl --location --request GET 'https://amplitude.com/api/2/export?start=<starttime>&end=<endtime>' \
-u '{api_key}:{secret_key}'

HTTP

GET /api/2/export?start=<starttime>&end=<endtime> HTTP/1.1
Host: amplitude.com
Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Example: Get data for a period (기간 데이터 가져오기)

2022년 1월 1일 자정부터 2022년 1월 27일 자정까지의 activity 데이터를 내보내는 예시예요.

cURL

curl --location --request GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220127T00' \
--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'

HTTP

GET /api/2/export?start=20220101T00&end=20220127T00 HTTP/1.1
Host: amplitude.com
Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo

Query parameters(쿼리 파라미터)

Response(응답)

응답은 JSON 파일들의 압축(zip) 아카이브예요. 데이터 양에 따라 한 시간에 여러 파일이 생길 수 있어요. 요청한 시간 범위에 데이터가 없으면 API는 404 응답을 반환해요.

Note:

2014년 11월 12일 이전의 이벤트는 시간 단위가 아니라 일(day) 단위로 그룹화돼요.

Response schema(응답 스키마)

각 파일의 한 줄마다 이벤트 JSON 객체 하나가 포함되며, 스키마는 다음과 같아요.

{
 "server_received_time": UTC ISO-8601 formatted timestamp,
 "app": int,
 "device_carrier": string,
 "city": string,
 "user_id": string,
 "uuid": UUID,
 "event_time": UTC ISO-8601 formatted timestamp,
 "platform": string,
 "os_version": string,
 "amplitude_id": long,
 "processed_time": UTC ISO-8601 formatted timestamp,
 "version_name": string,
 "ip_address": string,
 "paying": boolean,
 "dma": string,
 "group_properties": dict,
 "user_properties": dict,
 "client_upload_time": UTC ISO-8601 formatted timestamp,
 "$insert_id": string,
 "event_type": string,
 "library": string,
 "amplitude_attribution_ids": string,
 "device_type": string,
 "start_version": string,
 "location_lng": float,
 "server_upload_time": UTC ISO-8601 formatted timestamp,
 "event_id": int,
 "location_lat": float,
 "os_name": string,
 "groups": dict,
 "event_properties": dict,
 "data": dict,
 "device_id": string,
 "language": string,
 "country": string,
 "region": string,
 "session_id": long,
 "device_family": string,
 "sample_rate": null,
 "client_event_time": UTC ISO-8601 formatted timestamp,
}

Status codes(상태 코드)

더 알아보기 (Learn more)

• 공식 문서