이 페이지에서

사용자 프로필 API

EU 지역에서는 사용할 수 없음

이 API는 Amplitude의 EU 데이터 처리 지역에 거주하는 고객에게는 지원되지 않습니다.

고려 사항

서버 측 API

Amplitude는 사용자 프로필 API를 서버 측에서만 사용할 것을 권장합니다. 클라이언트에서 API를 호출하면 프로젝트의 비밀 키가 노출될 수 있습니다.

기본 경험

  • is_control=true을(를) 사용하는 사용자에게 기본 사용자 환경을 제공하지 않는 경우, Amplitude는 성능을 측정할 수 없습니다.
  • 오류가 발생할 경우 기본 환경을 제공합니다.
  • Amplitude를 사용할 수 없고 500 응답을 반환하는 경우 다시 시도하거나 기본 경험을 제공할 수 있습니다.

인증 오류

  • 암호 키는 올바르지만 사용자 ID의 형식이 잘못되었거나 사용자 ID가 다른 프로젝트의 경우 API는 {"error":"User id and device id not seen before"} 오류로 반환합니다.
  • 비밀 키가 잘못된 경우 API는 HTTP 401 응답을 반환합니다. Invalid Api-Key
  • 인증 헤더가 누락되었거나 형식이 잘못된 경우 API는 HTTP 401 응답을 반환합니다. Missing Api-Key in Authorization header

구성 오류

  • 엔드포인트 또는 경로가 잘못된 경우 API는 빈 오류(HTTP 404) 응답을 반환합니다.
  • 안전하지 않은 HTTP 요청을 전송하면 API는 HTML 본문과 함께 HTTPS 엔드포인트(HTTP 301)로 리디렉션합니다. Location 헤더에는 올바른 프로토콜과 URL이 포함되어 있습니다.

임계치 조절 오류

  • Amplitude 조직은 모든 엔드포인트에서 분당 600건의 API 요청 제한을 갖습니다. 이 제한을 초과할 경우 지원 부서에 사용 사례와 필요한 제한을 설명하십시오.
    • {"error":"Number of requests per minute exceeds system limit. Contact Support if you need this limit raised"}
  • 배치 추천 사용 사례의 경우 요청을 이 한도 첫 사용 후 유지하도록 속도를 제한합니다.

요청 매개 변수

매개 변수설명
user_id[^1]선택 사항이지만 device_id이(가) 설정되어 있는 경우 필수입니다. 질의할 사용자 ID(외부 데이터베이스 ID)입니다.
device_id[^1]선택 사항이지만 user_id이(가) 설정되어 있는 경우 필수입니다. 쿼리할 장치 ID(익명 ID)입니다.
get_recs선택 사항입니다. 이 사용자에 대한 추천 결과를 반환합니다. 기본값은 false입니다.
rec_id선택 사항입니다. 검색할 개인화 추천입니다. get_recs이 참인 경우 필수입니다. 쉼표로 rec_ids을(를) 구분하여 여러 개인화 추천을 가져오세요.
rec_type선택 사항입니다. 기본 실험 통제 설정을 재정의합니다. rec_type=model은(는) 모델링된 개인화 추천을 반환하고 rec_type=random은(는) 임의의 개인화 추천을 반환합니다.
get_amp_props선택 사항입니다. 커스텀 계산을 포함하지 않고 이 사용자에 대한 전체 사용자 속성 세트를 반환합니다. 기본값은 false입니다.
get_cohort_ids선택 사항입니다. 이 사용자가 속해 있고 추적을 위해 구성된 코호트 ID 목록을 반환합니다. 코호트 멤버십은 기본적으로 추적되지 않습니다. 기본값은 false입니다. API는 프로필 API와 동기화된 코호트만 반환합니다.
get_computations선택 사항입니다. 이 사용자에 대해 활성화된 커스텀 계산 목록을 반환합니다. 기본값은 false입니다.
comp_id선택 사항입니다. 이 사용자에 대해 활성화될 수 있는 단일 계산을 반환합니다. 연산이 존재하지 않는 경우 null 값을 반환합니다. get_computations 값이 참인 경우, API는 연산이 보관되거나 삭제되지 않는 한 이 값을 포함한 모든 값을 가져옵니다.

추천 받기

ID별로 단일 추천을 검색합니다. Amplitude는 요청당 50개의 항목을 반환할 것을 권장합니다. 최대 항목은 100개입니다. Amplitude 추천 페이지에서 이 값을 업데이트하십시오.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId' \
--header 'Authorization: Api-Key <SECRET KEY>'

응답

json
{
  "userData":{
    "recommendations":[
      {
        "rec_id":"98765",
        "child_rec_id":"98765",
        "items":[
          "cookie",
          "cracker",
          "chocolate milk",
          "donut",
          "croissant"
        ],
        "is_control":false,
        "recommendation_source":"model",
        "last_updated":1608670720
      }
    ],
    "user_id":"12345",
    "device_id":"ffff-ffff-ffff-ffff",
    "amp_props":null,
    "cohort_ids":null
  }
}
응답 매개변수설명
rec_id요청된 추천 ID입니다.
child_rec_idAmplitude가 모델 성능을 개선하기 위해 내부 실험의 일부로 사용할 수 있는 보다 자세한 추천 ID입니다. 일반적으로 rec_id와 동일합니다.
items이 사용자에 대한 개인화 추천 목록입니다.
is_control이 사용자가 제어 그룹에 속해 있는 경우 true입니다.
recommendation_source이 추천을 생성하는 데 사용된 모델의 이름입니다.
last_updated이 추천이 마지막으로 생성되고 동기화된 시점의 타임스탬프입니다.

여러 개인화 추천 확인

한 사용자에 대한 여러 개인화 추천을 검색합니다. Amplitude는 요청당 50개의 항목을 반환할 것을 권장합니다. 최대 항목은 100개입니다. Amplitude 추천 페이지에서 이 값을 업데이트하십시오.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_recs=true&rec_id=testRecId,testRecID2' \
--header 'Authorization: Api-Key <SECRET KEY>'

응답

json
{
  "userData": {
    "recommendations": [
      {
        "rec_id": "testRecId",
        "child_rec_id": "testRecId",
        "items": [
          "cookie",
          "cracker",
          "chocolate milk",
          "donut",
          "croissant"
        ],
        "is_control": false,
        "recommendation_source": "model",
        "last_updated": 1608670720
      },
            {
        "rec_id": "testRecId2",
        "child_rec_id": "testRecId2",
        "items": [
          "bulgogi",
          "bibimbap",
          "kimchi",
          "croffles",
          "samgyeopsal"
        ],
        "is_control": false,
        "recommendation_source": "model2",
        "last_updated": 1608670658
      }
    ],
    "user_id": "12345",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": null
  }
}

사용자 속성 가져오기

사용자의 속성을 검색합니다.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_amp_props=true' \
--header 'Authorization: Api-Key <SECRET KEY>'

응답

json
{
  "userData": {
    "recommendations": null,
    "user_id": "12345",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "library": "http/1.0",
      "first_used": "2020-01-13",
      "last_used": "2021-03-24",
      "number_property": 12,
      "boolean_property": true
    },
    "cohort_ids": null
  }
}

코호트 ID 받기

사용자의 코호트 ID를 검색합니다. get cohort IDs을(를) 사용하기 전에 사용자 프로필 API를 사용하여 코호트를 동기화하십시오.

프로필 API 제한

Amplitude는 프로필 API와의 코호트 데이터 동기화를 1천만 명 이하의 사용자로 제한합니다.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_cohort_ids=true' \
--header 'Authorization: Api-Key <SECRET KEY>'

응답

json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": null,
    "cohort_ids": ["cohort1", "cohort3", "cohort7"]
  }
}

모든 커스텀 계산 가져오기

커스텀 계산은 이벤트 또는 이벤트 속성을 계산된 사용자 속성으로 변환하여 사용자를 세분화하는 데 사용할 수 있습니다. 계산된 속성을 분석을 위해 전체 Amplitude 차트에서 구성 가능한 필터로 사용하거나, 이를 외부 목적지와 동기화하여 개인화 도구로 사용할 수 있습니다.

사용자에 대한 모든 커스텀 계산을 검색합니다.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?get_computations=true&user_id=USER_ID' \
--header 'Authorization: Api-Key <SECRET KEY>'

json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-1": "5000000.0",
      "computed-prop-2": "3"
    },
    "cohort_ids": null
  }
}

ID별 연산 가져오기

ID별로 하나 이상의 커스텀 계산을 검색합니다. Audiences의 연산으로 이동하여 URL 끝에 있는 ID를 찾아 복사합니다. 예를 들어 t14bqib는 https://app.amplitude.com/audiences/org_name_00000/computations/t14bqib/의 ID입니다.

여러 계산 가져오기

쉼표(,)로 comp_id을(를) 구분하여 comp_id 여러 개를 가져옵니다. 예를 들어: comp_id=id1,id2. 여러 comp_id ID에 대한 응답이 amp_props 필드에 있습니다.

ID별로 사용자에 대한 연산을 검색합니다.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_computations=true&comp_id=COMP_ID' \
--header 'Authorization: Api-Key <SECRET KEY>'

json
{
  "userData": {
    "recommendations": null,
    "user_id": "testUser",
    "device_id": "ffff-ffff-ffff-ffff",
    "amp_props": {
      "computed-prop-2": "3"
    },
    "cohort_ids": null
  }
}

단일 또는 다중 예측 성향 확보

Amplitude Activation에서 예측을 생성할 때 예측 점수를 프로필 API와 동기화할 수 있습니다. 예측 성향은 사용자가 예측된 행동을 수행할 확률입니다.

사용자의 예측 성향을 가져오려면 prediction_id와 propensity_type을(를) 포함하는 요청을 전송하십시오. 성향 유형은 원시 점수(score) 또는 백분위수(pct) 중 하나일 수 있습니다.

성향 유형설명
score원시 성향 점수입니다.
pct다른 사용자와 비교한 사용자의 백분위수입니다. 작업을 수행할 가능성이 가장 높은 상위 20%를 식별하는 등 사용자의 순위를 매기는 데 유용합니다.

Audiences 웹 앱에서 예측으로 이동한 후 URL 끝에 있는 ID를 복사하여 prediction_id을(를) 찾으십시오. 이 ID는 다음 예제에 0x10x나와 있습니다.

recommend.amplitude.com/0000/predictions/0x10x

여러 계산 가져오기

쉼표(,)로 prediction_id을(를) 구분하여 prediction_id 여러 개를 가져옵니다. 예를 들어: prediction_id=id1,id2. 여러 prediction_id ID에 대한 응답은 propensities 필드에 있습니다.

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_propensity=true&prediction_id=PREDICTION_ID&propensity_type=PROPENSITY_TYPE'
--header 'Authorization: Api-Key <SECRET KEY>'

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