このページでは

ユーザープロフィールAPI

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

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

考慮事項

サーバーサイド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は「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を利用している組織では、すべてのエンドポイントでのAPIリクエストが1分あたり600件までと制限されています。この制限を超える場合は、サポートにユースケースと必要な制限についてお問い合わせください。
    • {"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_recstrue の場合に必須です。 複数のレコメンデーションをフェッチするには、rec_idsをコンマで区切ります。
rec_typeオプション。デフォルトの実験対照設定を上書きします。rec_type=model モデル化された推奨事項を返します。rec_type=random ランダムな推奨事項を返します。
get_amp_propsオプション。このユーザーのユーザープロパティの完全なセットを返します。計算値を含みません。 デフォルトはfalseです。
get_cohort_idsオプション。このユーザーが属しており、トラッキング用に設定されているコホート ID のリストを返します。 コホートメンバーシップはデフォルトでは追跡されません。 デフォルトはfalseです。 このAPIは、Profile APIと同期されたコホートのみを返します。
get_computationsオプション。このユーザーに対して有効な計算のリストを返します。 デフォルトはfalseです。
comp_idオプション。このユーザーに対して有効化されている可能性のある単一のコンピューテーションを返します。コンピューテーションが存在しない場合はnull値を返します。get_computationsが「true」の場合、コンピューテーションがアーカイブまたは削除されない限り、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,000 万人以下に制限しています。

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によって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' \
--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% を特定できます。

オーディエンス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'
--header 'Authorization: Api-Key <SECRET KEY>'

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