API 식별

Identify API를 사용하여 특정 장치 ID에 대한 사용자 ID를 설정하거나 이벤트를 전송하지 않고 특정 사용자의 사용자 속성을 업데이트할 수 있습니다. Amplitude 기본 사용자 속성 및 사용자가 정의한 사용자 속성을 변경할 수 있습니다.

지역

기본 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)입니다.

고려 사항

속도 제한

Amplitude는 개별 사용자(Amplitude ID별)가 사용자 속성을 시간당 1800회 이상 업데이트하는 경우 속도를 제한합니다. 이 제한은 사용자 속성 동기화에 적용되며 이벤트 수집에는 적용되지 않습니다. Amplitude는 계속해서 이벤트를 수집하지만 해당 사용자에 대한 사용자 속성 업데이트를 삭제할 수 있습니다.

  • 아직 추적하지 않은 사용자 속성을 업데이트할 수 있습니다. 속성 값은 사용자의 다음 이벤트가 발생할 때까지 플랫폼에 적용되거나 표시되지 않습니다. 자세한 내용은 사용자 속성 적용을 참조하십시오.
  • 업데이트는 소급되지 않으며 향후 이벤트에만 적용됩니다.
  • Amplitude는 초당 이벤트 수 임계값을 초과하는 device_ids 또는 user_ids 요청을 조절합니다. 요청이 제한되면 HTTP 상태 코드 429가 반환됩니다. 해당 요청에 포함된 어떤 장치든 이벤트 전송을 15초 동안 일시 중지한 후 다시 시도하십시오. 상태 코드 429를 더 이상 받지 않을 때까지 계속 재시도하십시오. 동일한 user_id이(가) 여러 장치에서 동시에 이벤트를 전송하는 경우, Amplitude는 모든 장치를 조절합니다. Amplitude의 HTTP V2 API의 모든 조절 및 상태 코드 지침은 Identify API에 적용됩니다.
  • Amplitude는 날짜를 문자열로 비교하므로 ISO 8601 형식(YYYY-MM-DDTHH:mm:ss)을 사용하십시오. 이 형식을 사용하면 웹 앱에서 날짜 비교를 수행할 수 있습니다. 예를 들어, '2016-01-31' > '2016-01-01'. 이 형식은 '2017-08-07T10:09:08' > '2017-08-07T01:07:00'와(과) 같은 날짜/시간 값에도 적용됩니다.
  • 업데이트는 이벤트로 간주되지 않기 때문에 Redshift에 나타나지 않습니다.
  • Identify API 호출은 이벤트로 계산되지 않으므로 '활성 사용자' 또는 '신규 사용자' 정의에 영향을 미치지 않으며, Amplitude의 월별 이벤트 수에도 추가되지 않습니다.
  • 기존 값에서 user_id필드를 변경하면 Amplitude는 새 사용자를 생성합니다. user_id의 현재 값이 null인 경우 Amplitude는 새로운 Amplitude 사용자를 생성하지 않습니다.

요청

POST https://api2.amplitude.com/identify

bash
curl --location --request POST 'https://api2.amplitude.com/identify' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_key=<API-KEY>' \
--data-urlencode 'identification=[{"user_id":"value", "user_properties":{"propertyNameToUpdate":"newValue"}}]'

필수 매개 변수

이러한 매개변수는 GET 요청의 쿼리 매개변수로, 또는 POST 요청의 본문 매개변수로 전송하십시오. 본문은 form-data또는 x-www-form-urlencoded이어야 합니다.

식별 매개변수 키

user_properties 지원되는 작업

user_properties 필드에서는 다음 작업을 지원합니다.

사용자 속성 작업을 최상위 사용자 속성과 혼용할 수 없습니다. 대신, 최상위 레벨 속성을 $set 작업 내에 포함시킵니다. 이러한 연산자 중 하나를 사용할 경우 사전에는 사용자 속성 연산자만 포함될 수 있습니다. 예를 들어 동일한 요청에 {"$append":{"interests":"Music"}, "subscription type":"paid"}을(를) 전송할 수 없습니다.

대신 다음을 수행하십시오.

json
{
  "$set": {
    "cohort": "Test A"
  },
  "$setOnce": {
    "startDate": "2015-10-01"
  },
  "$add": {
    "friendCount": 3
  },
  "$append": {
    "interests": "Music"
  },
  "$prepend": {
    "sports": "Tennis"
  },
  "$unset": {
    "oldProperty": "-"
  }
}

$unset을(를) 사용하여 사용자 속성을 지웁니다

더 이상 필요하지 않은 사용자 속성을 지우려면 해당 $unset 작업을 포함하는 Identify 호출을 전송합니다. 지울 각 속성의 값을 "-"로 설정합니다.

bash
curl --location --request POST 'https://api2.amplitude.com/identify' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_key=<API-KEY>' \
--data-urlencode 'identification=[{"user_id":"value", "user_properties":{"$unset":{"oldProperty":"-"}}}]'

하나의 요청에서 여러 속성을 설정해제하려면 $unset객체에 여러 키를 나열하십시오.

$unset은(는) 사용자의 현재 프로필에서 속성을 지우므로 사용자가 이후에 전송하는 이벤트에 해당 속성이 나타나지 않습니다. Amplitude가 이미 수집한 이벤트의 속성 값을 변경하거나 삭제하지 않습니다. 과거 이벤트는 Amplitude가 해당 이벤트를 수신했을 때 가지고 있던 값을 유지합니다. 다른 Identify API 업데이트와 마찬가지로 $unset는 소급되지 않습니다. 자세한 내용은 고려 사항을 참조하십시오.

개인정보 보호 컴플라이언스를 위해 사용자의 데이터를 삭제하려면 사용자 개인정보 보호 API를 사용하십시오.

상태 코드

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

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.

이 페이지에서