ユーザープロフィールAPI

ユーザープロフィールAPIはAmplitudeのユーザープロフィールを提供します。これにはユーザープロパティ、計算されたユーザープロパティ、ユーザーが属するコホートのコホートIDのリスト、推奨事項が含まれます。

EU地域では利用できません

このAPIは、AmplitudeのEUデータ処理リージョンのお客様には対応していません。

認証

このAPIは、プロジェクトのAPIキーと秘密鍵を使用して基本認証を使用します。base64エンコードされた認証情報を、{api-key}:{secret-key}のようにリクエストヘッダーに渡します。api-keyをユーザー名に、secret-keyをパスワードに置き換えてください。

ほとんどのHTTPクライアントは、認証情報をエンコードします。 ヘッダーを自分で作成する場合は、2つのキーをコロンで結合し、末尾に改行を入れずにbase64でエンコードします。末尾の改行がシークレットキーの一部となり、リクエストはHTTP 401レスポンスで失敗します。

考慮事項

サーバーサイドAPI

Amplitudeでは、User Profile APIをサーバーサイドでのみ使用することを推奨しています。 クライアントから API を呼び出すと、プロジェクトの秘密鍵が公開される可能性があります。

デフォルトのエクスペリエンス

  • is_control=trueによるデフォルトのユーザーエクスペリエンスが提供されないと、Amplitudeではパフォーマンスを測定できません。
  • エラーが発生した場合に備えてデフォルトの体験を提供します。
  • Amplitudeが利用できず、「500」のレスポンスが返ってくる場合は、リトライするか、デフォルトのエクスペリエンスを提供することができます。

認証エラー

  • 認証情報は正しいものの、ユーザーIDの形式が正しくない場合、またはユーザーIDが別のプロジェクトからのもの場合、APIは次のエラーを返します:{"error":"User id and device id not seen before"}
  • APIキーまたはシークレットキーが間違っている場合、APIはHTTP 401レスポンスを返します。 Invalid credentials
  • デコードされた認証情報にコロン区切り文字が含まれていない場合、またはいずれかの認証情報が空の場合、APIはHTTP 401レスポンスを返します。 Invalid Authorization header
  • 認証情報が有効なbase64でない場合、APIはHTTP 401レスポンスを返します。 Invalid base64 in Authorization header
  • リクエストにAuthorizationヘッダーがない場合、APIはHTTP 401レスポンスを返します。

設定エラー

  • エンドポイントまたはパスが間違っている場合、APIは空のエラー(HTTP 404)レスポンスを返します。
  • セキュアでないHTTPリクエストを送信した場合、APIはHTML本文を使用してHTTPSエンドポイント(HTTP 301)にリダイレクトします。Locationヘッダーには正しいプロトコルとURLが含まれています。

スロットリングエラー

  • Amplitudeを利用している組織では、すべてのエンドポイントでのAPIリクエストが1分あたり600件までと制限されています。この制限を超える場合は、サポートにユースケースと必要な制限についてお問い合わせください。
    • {"error":"Number of requests per minute exceeds system limit. Contact Support if you need this limit raised"}
  • バッチレコメンデーションユースケースの場合、リクエストをこの制限内に収めるためにレート制限を設定します。

リクエストパラメータ

レコメンデーションを取得する

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' \
-u '{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
  }
}

複数の推奨事項を取得する

ユーザーに対する複数の推奨事項を取得します。 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' \
-u '{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' \
-u '{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,000 万人以下に制限しています。

curl --location --request GET 'https://profile-api.amplitude.com/v1/userprofile?user_id=USER_ID&get_cohort_ids=true' \
-u '{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' \
-u '{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によって1つ以上の計算を取得します。 オーディエンス内のコンピューテーションに移動し、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' \
-u '{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)のいずれかを指定できます。

オーディエンスWebアプリの「予測」に移動し、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'
-u '{api-key}:{secret-key}'

これは役に立ちましたか?

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.

このページでは