バッチイベントアップロードAPI

地域

ベースURLは、プロジェクトのデータのレジデンシーによって異なります。このページ内のすべての例では、プロジェクトがAmplitudeのEUデータセンターを利用している場合を除き、デフォルトのベースURLを使用してください。EUデータセンターを利用している場合は、この表に記載されているEU用のベースURLを使用してください。

このAPIでは、イベント取り込みのホストとしてapi2.amplitude.com（デフォルト）またはapi.eu.amplitude.com（EU）が使用されます。他のAmplitude APIでは、別のホスト名（api.amplitude.com、core.amplitude.com、data-api.amplitude.com、experiment.amplitude.comなど）が使用されます。https://analytics.amplitude.comのホスト名は、アナリティクスWebアプリ（ブラウザーUI）であり、取り込みのエンドポイントではありません。

制限と考慮事項

• JSONシリアル化ペイロードのサイズは20MBを超えてはなりません。
• デバイスIDとユーザーIDは、5文字以上の文字列である必要があります。イベントの ID が短すぎると、その ID 値はイベントから削除されます。 イベントにユーザーまたはデバイス ID がない場合、API は 400 エラーでアップロードを拒否することがあります。 optionsプロパティを使用してIDの最小長を変更できます。
• 各 API キーは、個々のデバイス ID またはユーザー ID に対して、毎秒最大 1,000 件のイベントを送信できます。 このレートを超えると、API はアップロードを拒否し、429 レスポンスを返します。 詳細については、レスポンスの概要を参照してください。

リクエスト

バッチイベントアップロード API リクエストは HTTP API とは 2 つの点で異なります。

• コンテンツタイプは application/json である必要があります。
• eventsペイロードのキーはevents複数形であり、event単数形ではありません。

# You can also use wget
curl -X POST https://api2.amplitude.com/batch \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*'

ボディ

これらのプロパティはリクエストの本文に属します。

{
  "api_key": "my_amplitude_api_key",
  "events": [
    {
      "user_id": "datamonster@gmail.com",
      "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
      "event_type": "watch_tutorial",
      "time": 1396381378123,
      "event_properties": {
        "load_time": 0.8371,
        "source": "notification",
        "dates": ["monday", "tuesday"]
      },
      "user_properties": {
        "age": 25,
        "gender": "female",
        "interests": ["chess", "football", "music"]
      },
      "groups": {
        "team_id": "1",
        "company_name": ["Amplitude", "DataMonster"]
      },
      "app_version": "2.1.3",
      "platform": "iOS",
      "os_name": "Android",
      "os_version": "4.2.2",
      "device_brand": "Verizon",
      "device_manufacturer": "Apple",
      "device_model": "iPhone 9,1",
      "carrier": "Verizon",
      "country": "United States",
      "region": "California",
      "city": "San Francisco",
      "dma": "San Francisco-Oakland-San Jose, CA",
      "language": "English",
      "price": 4.99,
      "quantity": 3,
      "revenue": -1.99,
      "productId": "Google Pay Store Product Id",
      "revenueType": "Refund",
      "location_lat": 37.77,
      "location_lng": -122.39,
      "ip": "127.0.0.1",
      "idfa": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "idfv": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "adid": "AEBE52E7-03EE-455A-B3C4-E57283966239",
      "android_id": "BCCE52E7-03EE-321A-B3D4-E57123966239",
      "event_id": 23,
      "session_id": 1396381378123,
      "insert_id": "5f0adeff-6668-4427-8d02-57d803a2b841"
    }
  ]
}

イベント

これらのプロパティはeventsオブジェクトに属しています。

• user_id
  • 説明：
    • 必須です。 文字列です。 ユーザが指定した読み取り可能なID。5文字以上の長さが必要です。
    • device_id が指定されていない場合は必須です。
• device_id
  • 説明：必須です。文字列です。 デバイス固有の識別子（iOSのベンダー識別子など）。user_idがある場合を除き、必須。イベントとともにdevice_idが送信されていない場合、user_idのハッシュ化された値に設定されます。
• event_type
  • 説明：
    • 必須です。 文字列です。 イベントの一意の識別子です。
    • $identifyおよび$groupidentifyは、識別およびグループ識別のために事前に定義されていることに注意してください。これら 2 つの操作の詳細については、user_properties および group_propertiesの説明を参照してください。
• time
  • 説明: オプションです。 Long型。エポックからのイベントのタイムスタンプ（ミリ秒単位）。 イベントと一緒に時刻が送信されない場合、その時刻はリクエストのアップロード時刻に設定されます。
• event_properties
  • 説明: オプションです。 オブジェクト。イベントとともに送信されるプロパティを表すキーと値のペアの辞書。 プロパティ値は配列に格納できます。 日付値は文字列値に変換されます。 オブジェクトの深さは40レイヤーを超えることはできません。
• user_properties
  • 説明: オプションです。 オブジェクト。ユーザーに関連付けられたデータを表すキーと値のペアの辞書。 プロパティ値は配列に格納できます。 日付値は文字列値に変換されます。 ユーザープロパティ操作 ($set、$setOnce、$add、$append、$unset) は、event_type が $identify の場合にサポートされます。オブジェクトの深さは40レイヤーを超えることはできません。
• groups
  • 説明: オプションです。 オブジェクト。アカウント アドオンを購入したお客様のみが利用できます。 このフィールドは、ユーザーのグループを表すキーと値のペアの辞書をイベントレベルのグループとしてイベントに追加します。 最大 5 つの固有のグループタイプと合計 10 のグループを追跡できることに注意してください。Amplitudeは、このしきい値を超えるグループを追跡しません。
• group_properties
  • 説明: オプションです。 オブジェクト。アカウント アドオンを購入したお客様のみが利用できます。 event_typeが $groupidentifyである場合、このフィールドは、groupsフィールドにリストされているグループに関連付けられたプロパティを表すキーと値のペアの辞書です。このフィールドは、他のイベントタイプでは無視されます。グループプロパティの操作（、、$add、$set``$append、$setOnce``$unset）もサポートされています。
• $skip_user_properties_sync
  • 説明: オプションです。 ブール値trueのユーザープロパティが同期されていない場合。デフォルトはfalseです。
• app_version
  • 説明: オプションです。 文字列です。 アプリケーションの現在のバージョンです。
• platform
  • 説明: オプションです。 文字列です。 デバイスのプラットフォーム。
• os_name
  • 説明: オプションです。 文字列です。 ユーザーが使用しているモバイルオペレーティングシステムまたはブラウザの名前です。
• os_version
  • 説明: オプションです。 文字列です。 ユーザーが使用しているモバイルオペレーティングシステムまたはブラウザのバージョン。
• device_brand
  • 説明: オプションです。 文字列です。 ユーザーが使用しているデバイスのブランドです。
• device_manufacturer
  • 説明: オプションです。 文字列です。 ユーザーが使用しているデバイスの製造元です。
• device_model
  • 説明: オプションです。 文字列です。 ユーザーが使用しているデバイスのモデル。
• carrier
  • 説明: オプションです。 文字列です。 ユーザーが使用している通信事業者です。
• country
  • 説明: オプションです。 文字列です。 ユーザーの現在の国名。
• region
  • 説明: オプションです。 文字列です。 ユーザーの現在の地域。
• city
  • 説明: オプションです。 文字列です。 ユーザーの現在の都市。
• dma
  • 説明: オプションです。 文字列です。 ユーザーの現在の指定市場エリア。
• language
  • 説明: オプションです。 文字列です。 ユーザーが設定した言語です。
• price
  • 説明: オプションです。 浮動小数点数。購入されたアイテムの価格。 収益フィールドが送信されていない場合、収益データに必要です。 払い戻しには負の値を使用できます。
• quantity
  • 説明: オプションです。 整数です。 購入されたアイテムの数量。 指定されていない場合、デフォルトは 1 です。
• revenue
  • 説明: オプションです。 浮動小数点数Revenue = (price * quantity)。3つのフィールド（価格、数量、収益）をすべて送信した場合、Amplitudeは(price * quantity)収益値として使用します。 負の値を使用して払い戻しを識別できます。
• productId
  • 説明: オプションです。 文字列です。 購入されたアイテムの識別子です。 このフィールドを使用して価格と数量、または収益を送信する必要があります。
• revenueType
  • 説明: オプションです。 文字列です。 購入されたアイテムの収益のタイプ。 このフィールドを使用して価格と数量、または収益を送信する必要があります。
• currency
  • 説明: オプションです。 文字列です。 購入されたアイテムの通貨。3文字の大文字のISO 4217コードで指定されます（例：USD、EUR）。
• location_lat
  • 説明: オプションです。 浮動小数点数。ユーザーの現在の緯度です。
• location_lng
  • 説明: オプションです。 浮動小数点数。ユーザーの現在の経度です。
• ip
  • 説明: オプションです。 文字列です。 ユーザーのIPアドレスです。アップロード要求でIPアドレスを使用する際は$remoteを使用します。Amplitudeでは、IPアドレスを使用してユーザーの所在地（都市、国、地域、DMA）をリバースルックアップします。Amplitudeは、イベントがAmplitudeサーバーに到達した後に、イベントからロケーションとIPアドレスを削除することができます。 これの設定を依頼するために、Amplitude サポートにリクエストを送信することができます。
• idfa
  • 説明: オプションです。 文字列。（iOS）広告主の識別子です。
• idfv
  • 説明: オプションです。 文字列。（iOS）ベンダーの識別子です。
• adid
  • 説明: オプションです。 文字列です。 （Android）Google Playサービスの広告ID
• android_id
  • 説明: オプションです。 文字列です。 （Android）Android ID（広告IDではありません）
• event_id
  • 説明: オプションです。 整数です。 同じタイムスタンプを持つイベントを互いに区別するための増分カウンタuser_id。 Amplitude は、特にイベントが同時に発生することが予想される場合に、時間の経過とともに増加する event_id を送信することを推奨します。
• session_id
  • 説明: オプションです。 Long型。エポックからのセッションの開始時刻（ミリ秒単位）（Unix タイムスタンプ）。イベントを特定のシステムに関連付けるために必要です。「-1」のは、session_id``session_idの指定がないのと同じ状態です。
• insert_id
  • 説明: オプションです。 文字列です。 イベントの一意の識別子です。 Amplitudeは、過去7日以内に確認されたinsert_idとともに送信された後続のイベントに対して重複排除を行います。Amplitudeでは、UUIDを生成するか、device_id、user_id、event_type、event_idおよび時刻を組み合わせて使用することをお勧めします。
• plan
  • 説明: オプションです。 オブジェクト。トラッキングプランのプロパティAmplitudeはブランチ、ソース、バージョンのプロパティのみを受け入れます。
• plan.branch
  • 説明: オプションです。 文字列です。 トラッキング計画のブランチ名。 たとえば、「main」などです。
• plan.source
  • 説明: オプションです。 文字列です。 トラッキング計画のソース。例: 「ウェブ」
• plan.version
  • 説明: オプションです。 文字列です。 トラッキング計画のバージョン。たとえば、「1」、「15」などです。

オプション

これらのプロパティはoptionsオブジェクトに属しています。

レスポンス

成功の概要

{
  "code": 200,
  "events_ingested": 50,
  "payload_size_bytes": 50,
  "server_upload_time": 1396381378123
}

InvalidRequestError

{
  "code": 400,
  "error": "Request missing required field",
  "missing_field": "api_key",
  "events_with_invalid_fields": {
    "time": [3, 4, 7]
  },
  "events_with_missing_fields": {
    "event_type": [3, 4, 7]
  }
}

SilencedDeviceID

{
  "code": 400,
  "eps_threshold": 100,
  "error": "Events silenced for device_id",
  "exceeded_daily_quota_devices": {},
  "silenced_devices": ["silenced_device_id_1", "silenced_device_id_2"],
  "silenced_events": [5, 6],
  "throttled_devices": {
    "throttled_device_id_1": 0,
    "throttled_device_id_2": 100
  },
  "throttled_events": [3, 4]
}

PayloadTooLargeError

{
  "code": 413,
  "error": "Payload too large"
}

TooManyRequestsForDeviceError

{
  "code": 429,
  "error": "Too many requests for some devices and users",
  "eps_threshold": 1000,
  "throttled_devices": {
    "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 4000
  },
  "throttled_users": {
    "datamonster@amplitude.com": 4000
  },
  "exceeded_daily_quota_users": {
    "datanom@amplitude.com": 500200
  },
  "exceeded_daily_quota_devices": {
    "A1A1A000-F01A-4BD9-95C6-8E5357DF265D": 500900
  },
  "throttled_events": [3, 4, 7]
}

コード 429 の説明

Amplitudeがステータス429のリクエストを拒否した場合、そのリクエストに含まれるデバイスまたはユーザーは制限を受けました。 エラー応答には詳細情報が含まれているため、応答をログに記録することで、どのユーザまたはデバイスがスロットリングを引き起こしたかを調査できます。

device_idと user_idはスロットリングをトリガーする属性であるため、これらの属性のいずれかに対して作業を分割することで、スロットリングを特定の作業パーティションに分離できます。 スロットリングされていないパーティションでも、処理を進めることができます。

EPDS と EPUS

Amplitudeは、プロジェクトの各deviceIDと各userIDのイベント発生率を測定します。Amplitudeは、これらのレートをそれぞれ_デバイス秒あたりのイベント数_ (EPDS)および_ユーザー秒あたりのイベント数_ (EPUS)と呼びます。両方の値は、30 秒間にわたって平均されます。

一般的に、アプリは EPDS または EPUS 自体を測定すべきではありません。 できるだけ早くAmplitudeにリクエストを送信してください。 429を受信したら、しばらく待ってから（たとえば15秒間）、そのリクエストを再送信してください。

1日の制限

毎秒の制限に加えて、毎日の制限によってスパムや悪用を防止できます。この制限を超えることは困難です。 ユーザーまたはデバイスがシステムにスパムを送信しているとAmplitudeが判断した後、イベントは1日の制限に向けてカウントされ始めます。 プロジェクトが上限に達すると、Amplitudeは24時間ごとに1日あたり50万件のイベントをアップロードすることを制限します。 24時間のローリング期間は、1時間間隔で適用されます。1日の制限は、各デバイスIDおよびプロジェクトの各user_id項目に適用されます。

1日の制限値は、EPDSやEPUSとは独立しています。ユーザーまたはデバイスがプロジェクトの1日あたりのイベント数制限50万件に達すると、AmplitudeはユーザーまたはデバイスIDを含むバッチを拒否します。 このような場合、リクエストは、ボディを示すexceeded_daily_quota_usersか、exceeded_daily_quota_devicesデバイスIDとユーザーIDのリストを含む429応答を返します。過去24時間以内にユーザーまたはデバイスに対してアップロードされたイベント数が50万件未満の場合、バッチを再試行してください。