エクスポート API
Export APIを使用すると、プロジェクトのイベントデータをエクスポートできます。
地域
ベースURLは、プロジェクトのデータのレジデンシーによって異なります。EUプロジェクトの場合、例内のデフォルトのベースURLを、この表のEU用のベースURLに置き換えます。
RESTリクエストの場合は、プロジェクトのデータレジデンシーに対応するベースURLを使用してください。その他のAPIについては、APIホストとリージョンを参照してください。
| データのレジデンシー | ベースURL |
|---|---|
| デフォルト | https://amplitude.com |
| 欧州連合 | https://analytics.eu.amplitude.com |
考慮事項
- 日付範囲には、Amplitudeサーバ上でのイベントデータのアップロード時刻が使用されます(
server_upload_time)。Export APIは、UTCでタイムスタンプが付いたイベントを返します。Amplitudeサーバーがデータを受信してから2時間以内にデータをエクスポートできます。 たとえば、午後8時から9時の間に送信されたデータは、午後9時にロードを開始し、午後11時にExport API経由で利用可能になります。 プラットフォーム上のレポート作成には遅延はありません。 エクスポートのみに遅延があります。 - エクスポート API はプロジェクト横断ビューをサポートしていません。これは、ビューがデータを所有していないためです。 ビュー内のすべてのデータをエクスポートするには、データを取り込んだ基盤となるプロジェクトでExportAPIを呼び出します。
- サイズ制限は4GBです。 エクスポートが4GBを超える場合、リクエストは
400レスポンスを返します。より小さい時間範囲を選択してください。 1時間のデータ量が4GBを超える場合は、Amazon S3エクスポートを使用します。 - 1日分のデータをエクスポートするには、
T00からT23を使用します。例:GET 'https://amplitude.com/api/2/export?start=20220101T00&end=20220101T23'。 - 一度にクエリを実行できる期間の上限は365日です。
リクエスト
GET https://amplitude.com/api/2/export
HTTPベーシック認証を使用して認証します。ユーザー名としてプロジェクトの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}'
クエリパラメータ
| 名前 | 必須 | 概要 |
|---|---|---|
start | はい | データシリーズに含まれる最初の時間です。形式はYYYYMMDDTHHです。例:20220201T05。 |
end | はい | データシリーズに含まれる最後の時間です。形式はYYYYMMDDTHHです。例:20220201T05。 |
レート制限
Export APIには、Dashboard REST APIのクエリとは別の制限が適用されます。デフォルトの制限は、同じプロジェクトAPIキーを使用したリクエストに適用されます。
| 制限 | デフォルト |
|---|---|
| 同時実行リクエスト | 4 |
| 1時間あたりのリクエスト数 | 360 |
プロジェクトまたは組織の上書きにより、これらのデフォルト値を変更できます。 制限を超えると、HTTP 429が返されます。このエラーは、超過した制限をrateまたはconcurrentとして識別します。認証情報を共有している作業者同士で調整を行い、同じリクエスト予算を共有するようにしてください。
データの可用性と一貫性
startとendの両方ともに指定された時間が含まれており、UTC時間を使用します。たとえば、start=20220201T05&end=20220201T05は1時間をエクスポートします。連続するリクエストの場合は、時間の重複を避けるため、前の範囲のendから1時間後に次の範囲を開始します。
エクスポート範囲は、event_timeではなく、server_upload_timeによってイベントを選択します。イベントのタイムスタンプが以前の時刻になっている遅延イベントは、Amplitudeがアップロードした時間帯に属します。エクスポートチェックポイントを保守する場合は、upload-time rangesを使用してください。
ある1時間分のデータを完了と見なす前に、考慮事項で説明しているエクスポートの遅延を考慮に入れてください。直近の時間に対して404が返された場合、そのリクエストに対するエクスポートファイルがまだ存在しないことを意味します。Amplitudeがイベントを受信しないことを確定するものではありません。可用性遅延の経過後、該当する時間を再試行してください。
個別のエクスポートリクエストを単一のスナップショットとして扱ったり、再試行で同じアーカイブバイトが返されると考えたりしないでください。チェックポイントを進める前に、ZIPダウンロード全体を検証してください。 重複する範囲を再試行する場合は、エクスポートリクエストで以前のダウンロードが重複排除されると想定するのではなく、送信先でイベントの重複排除を適用してください。
レスポンス
レスポンスは、JSONファイルのZIPアーカイブです。 データ量によっては、アーカイブには1時間に複数のファイルが含まれている場合があります。 APIは、リクエストされた時間範囲にデータが含まれていない場合、空の404レスポンスを返します。
Amplitudeは、2014年11月12日以前のイベントを時間単位ではなく日単位でグループ化します。
レスポンススキーマ
各ファイルには、1 行に 1 つのイベント 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,
}
ステータスコード
| コード | 意味 | 何をすべきか |
|---|---|---|
200 | リクエストは成功し、ZIPアーカイブが返されます。 | 処理する前に、完全なアーカイブをダウンロードして検証してください。 |
400 | 必要なパラメータが欠落している、日付の形式が無効である、またはエクスポートがドキュメントに記載されている4GBのサイズ制限を超えている可能性があります。 | リクエストを修正してください。サイズエラーの場合は、範囲を短縮してください。 1時間がこの制限を超えている場合は、Amazon S3送信先を使用してください。 |
401 | ベーシック認証ヘッダーが欠落しているか、形式が正しくありません。 | 有効なBasic認証ヘッダーを送信してください。 |
403 | APIキーまたはシークレットキーが無効であるか、AmplitudeがAPIキーをブロックしました。 | 認証情報とプロジェクト地域を確認します。 再試行する前に、ブロックされたキー(blocked-key)アクセスを解決してください。 |
404 | リクエストされた範囲のエクスポートファイルが存在しません。 | プロジェクトとUTCのアップロード時間範囲を確認します。 最近のデータについては、エクスポートが利用可能になるのを待ち、再試行してください。 |
429 | リクエストはレートまたは同時実行性の制限を超えています。 | 同時実行数またはリクエスト頻度を減らし、バックオフを使用して再試行してください。 |
504 | エクスポートがタイムアウトしました。 | より小さい範囲で再試行してください。 大規模なエクスポートの場合は、Amazon S3の送信先を使用してください。 |
再試行処理
HTTPステータスを使用して、障害の処理方法を決定します。 エラーボディは異なる場合があります。すべての失敗が JSON または固定メッセージを返すとは限りません。
429、ネットワーク障害、および一時的な5xxレスポンスの場合は、ジッターを加えた指数バックオフを使い、リトライカウント数に上限を設けます。レスポンスにRetry-Afterが含まれている場合は、それに従ってください。それ以外の場合は、クライアントのバックオフポリシーを使用します。 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.