내보내기 API

내보내기 API를 사용하면 프로젝트의 이벤트 데이터를 내보낼 수 있습니다.

지역

기본 URL은 프로젝트의 데이터 상주 위치에 따라 달라집니다. EU 프로젝트의 경우 예제에 있는 기본 URL을 이 표의 EU 기본 URL로 바꿉니다.

REST 요청의 경우 프로젝트의 데이터 상주 위치에 기본 URL을 사용하십시오. 다른 API에 대해서는 API 호스트 및 지역을 참조하십시오.

고려 사항

  • 날짜 범위는 Amplitude 서버(server_upload_time)에서 이벤트 데이터의 업로드 시간을 사용합니다. 내보내기 API는 UTC로 표시된 이벤트 타임스탬프를 반환합니다. Amplitude 서버가 데이터를 수신한 후 2시간 내에 데이터를 내보낼 수 있습니다. 예를 들어 오후 8시와 9시 사이에 전송된 데이터는 오후 9시에 로드되기 시작하며 오후 11시에 Export API를 통해 사용할 수 있게 됩니다. 플랫폼 보고는 지연되지 않습니다. 내보내기만 지연이 있습니다.
  • 내보내기 API는 뷰가 데이터를 소유하지 않기 때문에 프로젝트 간 뷰를 지원하지 않습니다. 뷰의 모든 데이터를 내보내려면 데이터를 수집한 기본 프로젝트에서 내보내기 API를 호출하십시오.
  • 크기 제한은 4GB입니다. 내보내기가 4GB를 초과하는 경우 요청은 400 응답을 반환합니다. 더 작은 시간 범위를 선택합니다. 한 시간의 데이터가 4GB를 초과하는 경우 Amazon S3 내보내기를 사용하십시오.
  • 하루 종일을 내보내려면 T00 ~ T23 를 사용하십시오. 예를 들어 GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220101T23'.
  • 한 번에 쿼리할 수 있는 최대 기간은 365일입니다.

요청

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

HTTP Basic 인증을 사용하여 인증합니다. 프로젝트의 API 키를 사용자 이름으로 사용하고 비밀 키를 암호로 사용합니다. 원시 HTTP 요청의 경우, Authorization: Basic 뒤의 문자열 api_key:secret_key을(를) base64로 인코딩하십시오. cURL의 -u 옵션은 자격 증명을 대신 인코딩합니다.

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

쿼리 매개 변수

속도 제한

Export API는 대시보드 REST API 쿼리와 별도의 제한을 사용합니다. 기본 제한은 동일한 프로젝트 API 키를 사용하는 요청에 적용됩니다:

프로젝트 또는 조직 재정의는 이러한 기본값을 변경할 수 있습니다. 제한을 초과하면 HTTP 429이(가) 반환됩니다. 이 오류는 초과된 제한을 rate 또는 concurrent(으)로 식별합니다. 자격 증명을 공유하는 작업자를 조정하여 동일한 요청 예산을 공유하도록 하십시오.

데이터 가용성 및 일관성

start 및 end 모두 지정된 시간을 포함하며 UTC를 사용합니다. 예를 들어, start=20220201T05&end=20220201T05은(는) 1시간을 내보냅니다. 연속 요청의 경우 시간 중복을 방지하려면 이전 범위의 end로부터 1시간 후에 다음 범위를 시작하십시오.

내보내기 범위는 event_time이(가) 아닌 server_upload_time을(를) 기준으로 이벤트를 선택합니다. 이전 이벤트 타임스탬프가 있는 늦은 이벤트는 Amplitude가 업로드한 시간에 속합니다. 내보내기 체크포인트를 유지 관리할 때 upload-time ranges를 사용하십시오.

1시간을 완료된 것으로 간주하기 전에 고려 사항에 설명된 내보내기 지연을 허용합니다. 최근 1시간에 대한 404은(는) 해당 요청에 내보내기 파일이 아직 존재하지 않음을 의미하며, Amplitude가 이벤트를 받지 못했다는 것을 확정하는 것은 아닙니다. 가용성 지연 시간이 지난 후 해당 시간의 데이터를 다시 시도하십시오.

별도의 내보내기 요청을 단일 스냅샷으로 취급하거나 재시도에서 동일한 아카이브 바이트를 반환한다고 가정하지 마십시오. 체크포인트를 진행하기 전에 전체 ZIP 다운로드를 확인하십시오. 겹치는 범위를 다시 시도하는 경우 내보내기 요청이 이전 다운로드를 제거한다고 가정하지 않고 목적지에서 이벤트를 중복 제거하십시오.

응답

응답은 JSON 파일의 ZIP 아카이브입니다. 데이터 볼륨에 따라 아카이브에 시간당 여러 파일이 포함될 수 있습니다. 요청된 시간 범위에 데이터가 포함되어 있지 않은 경우 API는 404 응답을 반환합니다.

Amplitude는 2014년 11월 12일 이전의 이벤트를 시간별이 아니라 날별로 그룹화합니다.

응답 스키마

각 파일에는 한 줄에 하나의 이벤트 JSON 객체가 포함되어 있으며, 스키마는 다음과 같습니다.

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,
}

상태 코드

처리 재시도

HTTP 상태를 사용하여 오류를 처리하는 방법을 결정합니다. 오류 본문은 다를 수 있으므로 모든 실패가 JSON 또는 고정 메시지를 반환한다고 가정하지 마십시오.

429 네트워크 장애 및 일시적 5xx 응답의 경우 지터와 제한된 재시도 횟수를 사용하는 지수적 백오프를 사용합니다. 응답에 Retry-After이(가) 포함된 경우 이를 준수하십시오. 그렇지 않으면 클라이언트의 backoff 정책을 사용하십시오. 429 오류를 검사하여 동시성 제한과 시간당 비율 제한을 구별합니다. 즉시 재시도해도 고갈된 시간당 예산이 해결되지 않습니다. 요청을 수정할 때까지 인증 또는 유효성 검사 실패를 재시도하지 마십시오.

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서