HTTP V2 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)입니다.

고려 사항

HTTP V2 API를 사용할 때는 다음 사항에 유의하십시오.

업로드 제한

무료 요금제 고객의 경우:

업로드를 초당 100개의 배치 및 초당 1,000개의 이벤트로 제한하십시오. 이벤트를 일괄 처리하여 업로드할 수 있지만, Amplitude는 배치당 이벤트를 10개 이하로 전송할 것을 권장합니다. Amplitude는 초당 100개 미만의 배치를 예상하며, 초당 1000개의 이벤트 제한도 여전히 적용됩니다.

그로쓰 및 엔터프라이즈 요금제를 사용하는 고객의 경우:

요청 크기를 1MB 미만으로 유지하고 요청당 이벤트 수를 2000개 미만으로 유지하십시오. 이 크기 제한을 초과하면 413 오류가 발생합니다.

볼륨이 많고 확장이 필요한 경우, device_id또는 user_id을(를) 기준으로 작업을 분할하십시오. 파티셔닝은 특정 device_id 또는 user_id 전송자에 대한 전송률 조절이 시스템의 모든 전송자에게 영향을 주지 않도록 보장합니다. 프록시 서비스를 사용하여 이벤트를 Amplitude로 전송하는 경우, 스팸 클라이언트가 시스템의 작업 파티션 속도를 저하시키지 않도록 조절 기능을 클라이언트에게 전달해야 합니다.

각 프로젝트는 HTTP API 및 HTTP V2 엔드포인트에 대해 초당 50,000개 이벤트의 처리량 제한이 있습니다. 비교를 위해 SDK 엔드포인트는 프로젝트당 초당 최대 150,000개의 이벤트를 지원합니다.

파트너 통합을 위한 정보

Amplitude와 이벤트 수집 연동을 수행하고 있는 경우, 연동에 할당된 파트너 ID를 이벤트 페이로드에 전송하십시오.

연동의 파트너 ID 및 페이로드 예제를 확인하려면 이벤트 수집 연동 생성을 참조하십시오.

기기 ID가 모두 0인 경우: 광고 추적 제한 활성화

iOS 10부터 Apple은 사용자가 광고 추적 제한을 활성화한 경우 광고주 식별자(IDFA)를 모두 0으로 바꿉니다. 모든 이벤트에는 기기 ID가 필요하므로, Amplitude는 모든 숫자가 0인 기기 ID를 삭제하고 요청에 대해 오류를 반환합니다.

IDFA를 장치 ID로 전달하는 경우 먼저 IDFA 값을 확인하십시오. IDFA가 모두 0인 경우 IDFV(공급업체 식별자)와 같은 장치 ID에 다른 값을 전달하십시오.

Windows OS

Windows 운영 체제를 사용하는 경우 모든 단일 따옴표를 이스케이프 큰따옴표로 바꿔야 할 수도 있습니다.

문자열 문자 제한

user_id, 이벤트 또는 사용자 속성 값과 같은 모든 문자열 값의 문자열 수는 1024자로 제한됩니다.

날짜 값 설정

Amplitude는 날짜를 문자열로 비교하므로 ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용하십시오. 이 형식을 사용하면 날짜 비교를 수행할 수 있습니다(예: '2016-01-31' > '2016-01-01'). 비교는 이 형식의 날짜 시간 값에도 적용됩니다(예: '2017-08-07T10:09:08' > '2017-08-07T01:07:00').

시간 값 설정

각 이벤트의 매개 변수를 time에포크 날짜 이후 밀리초 단위로 전송합니다. 순서 무관 형식(ISO 형식 등)은 400 잘못된 요청 응답을 초래합니다.

이벤트 중복 제거

Amplitude는 중복 이벤트 전송 방지를 위해 각 이벤트에 insert_id을(를) 전송할 것을 강력히 권장합니다. Amplitude는 지난 7일 첫 사용 후 각 앱에서 동일한 device_id 상에서 동일한 insert_id와 함께 전송된 후속 이벤트(이벤트에 device_id 값이 있는 경우)를 무시합니다.

장치 ID 및 사용자 ID 최소 길이

장치 ID 및 사용자 ID는 5자 이상의 문자열이어야 합니다. 최소 길이는 잠재적인 계측 문제를 방지합니다. 이벤트에 너무 짧은 장치 ID 또는 사용자 ID가 포함되어 있는 경우 Amplitude는 해당 이벤트에서 ID 값을 제거합니다.

요청과 함께 min_id_length 옵션을 전달하여 기본 최소 길이인 5자를 재정의하십시오.

이벤트에 user_id 또는 device_id 값이 없는 경우, Amplitude는 400 상태로 이벤트를 거부할 수 있습니다.

언어 필드

요청의 language 필드에 태그가 포함되어 있는 경우, Amplitude는 태그를 사용자 친화적인 언어 이름으로 변경합니다. 예를 들어, 요청에 "language": "en-US"이(가) 포함되어 있는 경우 Amplitude는 값을 저장하기 전에 이를 "language": "English"(으)로 변경합니다.

언어 태그는 대소문자를 구분하지 않습니다.

요청

POST https://api2.amplitude.com/2/httpapi

헤더

Amplitude HTTP V2 API로 데이터를 전송하려면 application/json헤더를 Content-Type(으)로 설정하십시오.

바디 매개변수

이벤트 배열 키

이러한 키를 JSON 이벤트 객체에 전송할 수 있습니다. user_id 또는 device_id 중 하나가 필수이며 event_type은(는) 필수입니다.

옵션

응답

Amplitude는 재시도 논리를 구현하고 이벤트에 insert_id(동일한 이벤트의 중복 제거에 사용됨) 항목을 전송할 것을 권장합니다. 재시도 논리 및 insert_id은(는) API를 사용할 수 없거나 요청이 실패한 경우 손실되거나 중복된 이벤트를 방지합니다.

200

200 OK: 실시간 이벤트 업로드에 성공했습니다. 200 OK 응답을 받지 못한 경우, 요청을 다시 시도하십시오.

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

400

400 잘못된 요청입니다. 400은 올바르지 않은 업로드 요청임을 나타냅니다. 자세한 내용은 응답을 확인하십시오.

잘못된 요청에 대한 가능한 이유:

• 요청 본문이 올바른 JSON이 아닙니다. 반환된 error은(는) "잘못된 JSON 요청 본문"입니다.
• 요청 본문에 필수 필드가 없습니다. error반환된 메시지는 "요청이 필수 필드를 누락했습니다"이며, 누락된 필드를 나타냅니다.
• 이벤트 객체에 잘못된 필드가 있습니다. events_with_invalid_fields필드 이름을 오류를 반환하는 첫 번째 이벤트의 인덱스에 매핑합니다.
• 일부 장치는 무음으로 작동합니다.

속성(잘못되었거나 누락된 JSON)

속성(SilencedDeviceID)

403(금지됨)

403 금지됨. Amplitude의 웹 애플리케이션 방화벽(WAF)이 요청을 차단했습니다.

응답에 대한 가능한 이유:

• 요청에 Amplitude 보안 필터와 일치하는 헤더, 본문 또는 URI 첫 사용 후 잘못된 값이 포함되어 있습니다.
• 요청은 Amplitude가 요청을 수락할 수 없는 제재 지역에서 발송되었습니다.

{
  "code": 403,
  "error": "Forbidden"
}

속성

413(페이로드가 너무 큽니다.)

413 페이로드가 너무 큽니다. 페이로드 크기가 너무 큽니다(요청 크기가 1MB를 초과함). 이벤트 배열 페이로드를 여러 요청으로 분할하고 다시 시도하십시오.

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

속성

429(요청 수가 너무 많음)

429 요청이 너무 많습니다. 사용자 또는 장치에 대한 요청이 너무 많습니다. Amplitude는 최근 시간 동안 평균으로 측정된 초당 30개의 이벤트를 초과하는 사용자 및 장치에 대한 요청을 조절합니다. 해당 사용자 또는 장치에 대한 이벤트 전송을 30초 동안 일시 중지한 후 다시 시도하십시오. 더 이상 429 응답을 받지 않을 때까지 계속 재시도하십시오.

{
  "code": 429,
  "error": "Too many requests for some devices and users",
  "eps_threshold": 30,
  "throttled_devices": {
    "C8F9E604-F01A-4BD9-95C6-8E5357DF265D": 31
  },
  "throttled_users": {
    "datamonster@amplitude.com": 32
  },
  "throttled_events": [3, 4, 7]
}

속성

서버 오류 500, 502, 504

500, 502 및 504 서버 오류입니다. Amplitude가 요청을 처리하는 동안 오류가 발생했습니다. Amplitude가 이 응답을 가진 요청을 수락하지 않았을 수 있습니다. 요청을 재시도하면 재시도로 인해 이벤트가 중복될 수 있습니다. 중복을 방지하려면 요청에 insert_id를 보내십시오.

503 서비스 사용 불가능

503 서비스를 사용할 수 없습니다. 내부 Amplitude 문제로 인해 요청이 실패했습니다. 503응답을 사용하여 요청을 다시 시도해도 이벤트가 중복될 위험이 없습니다.