배치 이벤트 업로드 API

지역

기본 URL은 프로젝트의 데이터 상주 위치에 따라 달라집니다. 이 페이지의 모든 예제에서 프로젝트가 Amplitude의 EU 데이터 센터를 사용하지 않는 한 기본 URL을 사용하십시오. 이 경우 이 표의 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 호스트 이름은 수집 엔드포인트가 아닌 분석 웹 앱(브라우저 UI)입니다.

제한 사항 및 고려 사항

• JSON 직렬화된 페이로드의 크기는 20MB를 초과해서는 안 됩니다.
• 장치 ID 및 사용자 ID는 5자 이상의 문자열이어야 합니다. 이벤트의 ID가 너무 짧으면 해당 ID 값이 이벤트에서 삭제됩니다. 이벤트에 사용자 또는 장치 ID가 없는 경우 API는 400 오류와 함께 업로드를 거부할 수 있습니다. options속성을 사용하여 최소 ID 길이를 변경할 수 있습니다.
• 각 API 키는 전체 개별 기기 ID 또는 사용자 ID에 대해 초당 최대 1,000개의 이벤트를 전송할 수 있습니다. 이 속도를 초과하면 API는 업로드를 거부하고 429 응답을 반환합니다. 자세한 내용은 응답 요약을 참조하십시오.

요청

배치 이벤트 업로드 API 요청은 HTTP API와 두 가지 면에서 다릅니다.

• 콘텐츠 유형은 application/json이어야 합니다.
• events페이로드에 대한 키는 단수가 event아닌 events 복수입니다.

# 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이(가) 없는 경우 필수입니다. 이벤트와 함께 전송되지 않은 경우 이는 user_id의 해시된 버전으로 설정됩니다device_id.
• event_type
  • 설명:
    • 필수입니다. 문자열입니다. 이벤트의 고유 식별자입니다.
    • $identify및 $groupidentify는 식별 및 그룹 식별을 위해 미리 정의되어 있습니다. 이 두 작업에 대한 자세한 내용은 user_properties및 group_properties에 대한 설명을 참조하십시오.
• time
  • 설명: 선택 사항입니다. 길이입니다. 에포크 이후 발생한 이벤트의 타임스탬프(밀리초)입니다. 이벤트와 함께 시간이 전송되지 않은 경우 해당 시간은 요청 업로드 시간으로 설정됩니다.
• 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)세 필드(가격, 수량 및 수익)를 모두 전송하면 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
  • 설명: 선택 사항입니다. 길이입니다. 에포크(Unix 타임스탬프) 이후 세션의 시작 시간(밀리초)으로, 이벤트를 특정 시스템과 연결시키는 데 필요합니다. A 값이 -1이면 지정되지 않은 것과 동일합니다session_id``session_id.
• insert_id
  • 설명: 선택 사항입니다. 문자열입니다. 이벤트의 고유 식별자입니다. Amplitude는 지난 7일 동안 insert_idseen과 함께 전송된 후속 이벤트의 중복을 제거합니다. Amplitude는 UUID를 생성하거나 , user_id, event_type``event_id, 및 시간을 device_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(events per device second)와 EPUS(events per user second)라고 칭합니다. 두 값 모두 30초 동안 평균을 산출합니다.

일반적으로 앱은 EPDS 또는 EPUS 자체를 측정해서는 안 됩니다. 가능한 한 빨리 Amplitude에 요청을 전송하십시오. 429 메시지를 받으면 해당 요청을 다시 전송하기 전에 잠시 기다리십시오(예: 15초).

일일 한도

초당 제한 외에도 일일 제한도 설정되어 스팸과 악용을 방지합니다. 이 한계를 초과하기는 어렵습니다. Amplitude는 사용자나 장치가 시스템을 스팸하고 있다고 판단한 후 이벤트를 일일 제한으로 계산하기 시작합니다. 프로젝트가 한도에 도달하면 Amplitude는 24시간 이동 기간당 업로드되는 이벤트에 대해 500,000개의 일일 제한을 적용합니다. 24시간 롤링 기간은 1시간 간격으로 적용됩니다. 일일 제한은 프로젝트의 각 deviceID 및 각 user_id에 대해 적용됩니다.

일일 제한은 EPDS 및 EPUS와 독립적입니다. 사용자 또는 장치가 프로젝트의 일일 이벤트 수 제한인 500,000개에 도달하면 Amplitude는 사용자 또는 장치 ID가 포함된 배치를 거부합니다. 이러한 경우 요청은 exceeded_daily_quota_users또는 exceeded_daily_quota_devicesdeviceID 및 userID 목록이 포함된 본문과 함께 429 응답을 반환합니다. 이전 24시간 동안 사용자 또는 장치에 대해 업로드된 이벤트 수가 50만 개 미만인 경우 배치를 다시 시도하십시오.