ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

実験API

プラン: Free、Premium、Ultimate
提供形態: GitLab.com

このAPIを使用してA/B実験を操作します。このAPIは内部使用のみを目的としています。匿名ユーザーや認証されていないユーザーとは使用できません。匿名ユーザーが関わる実験の場合は、代わりにglex_forceクエリパラメータを使用してください。

前提条件:

GitLabチームメンバーである必要があります。

すべての実験をリスト表示

GitLabインスタンス上のすべての実験をリスト表示します。各実験には、enabledステータスがあり、その実験がグローバルに有効になっているか、特定のコンテキストでのみ有効になっているかを示します。

各実験は、実験が宣言するコンテキストキーを含むcontext配列も公開します。user、namespaceネームスペース、project、またはactorです。バリアントの割り当てを強制、読み取り、またはクリアする際に、これらのキーを渡します。actorキーの場合、GitLabがユーザーからアクターを解決するため、context[user]パラメータを渡します。コンテキストキーを宣言しない実験の場合、配列は空です。

GET /experiments

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments"

レスポンス例:

[
  {
    "key": "code_quality_walkthrough",
    "context": ["user"],
    "definition": {
      "name": "code_quality_walkthrough",
      "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58900",
      "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/327229",
      "milestone": "13.12",
      "type": "experiment",
      "group": "group::activation",
      "default_enabled": false
    },
    "current_status": {
      "state": "conditional",
      "gates": [
        {
          "key": "boolean",
          "value": false
        },
        {
          "key": "percentage_of_actors",
          "value": 25
        }
      ]
    }
  },
  {
    "key": "ci_runner_templates",
    "context": ["user", "namespace"],
    "definition": {
      "name": "ci_runner_templates",
      "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58357",
      "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/326725",
      "milestone": "14.0",
      "type": "experiment",
      "group": "group::activation",
      "default_enabled": false
    },
    "current_status": {
      "state": "off",
      "gates": [
        {
          "key": "boolean",
          "value": false
        }
      ]
    }
  }
]

キャッシュされた割り当てを削除

キャッシュストアから、実験のすべてのキャッシュされたバリアントの割り当てを削除します。このエンドポイントを使用して、コードベースからコードが削除されても、キャッシュされた割り当てが残っている完了した実験をクリーンアップします。

DELETE /experiments/:name/cache

サポートされている属性:

属性	タイプ	必須	説明
`name`	文字列	はい	クリアする実験のキャッシュキー。

成功すると、204 No Contentを返します。

指定された名前にキャッシュされた割り当てが存在しない場合でも、リクエストは204 No Contentを返します。名前が実験ではないキャッシュキーを参照している場合、リクエストは400 Bad Requestを返します。リクエストが認証されていない場合、リクエストは401 Unauthorizedを返します。ユーザーがGitLabチームメンバーではない場合、リクエストは403 Forbiddenを返します。

nameの値は、キャッシュキーとして直接使用されます。このエンドポイントは、現在定義されている実験に属していない場合でも、一致するすべてのキャッシュエントリをクリアします。この動作は、コードが削除された孤立した実験のクリーンアップをサポートします。このエンドポイントを呼び出す前に、名前を確認してください。

リクエスト例:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/code_quality_walkthrough/cache"

実験の割り当て

これらのエンドポイントを使用して、GLEX Redisキャッシュ内の実験バリアントの割り当てを強制および読み取ります。これは、リクエスト/レスポンスサイクル外で実行され、glex_forceクエリパラメータが利用できないバックエンド専用の実験に役立ちます。

実験は、app/experiments内の実験クラスでcontext_keysを宣言する必要があります。詳細については、バリアントの割り当てを強制するを参照してください。

バリアントの割り当てを強制する

指定されたコンテキストの実験キャッシュにバリアントの割り当てを書き込みます。

POST /experiments/:experiment_name/assignments

パラメータは以下のとおりです:

属性	タイプ	必須	説明
`experiment_name`	文字列	はい	実験の名前。
`variant`	文字列	はい	割り当てるバリアント名（例: `control`、`candidate`）。
`context[user]`	文字列	いいえ	コンテキストのユーザー名。
`context[namespace]`	文字列	いいえ	コンテキストのネームスペースのフルパス。
`context[project]`	文字列	いいえ	コンテキストのプロジェクトのフルパス。

contextパラメータを省略した場合、APIは認証済みユーザーを使用します。

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/my_experiment/assignments" \
  --data "variant=candidate" \
  --data "context[user]=sidney-jones"

レスポンス例:

{
  "experiment": "my_experiment",
  "variant": "candidate",
  "context_key": "my_experiment:a1b2c3d4e5f6"
}

現在の割り当てを取得する

指定された実験およびコンテキストに対して、現在キャッシュされているバリアントの割り当てを読み取ります。

GET /experiments/:experiment_name/assignments

パラメータは以下のとおりです:

属性	タイプ	必須	説明
`experiment_name`	文字列	はい	実験の名前。
`context[user]`	文字列	いいえ	コンテキストのユーザー名。
`context[namespace]`	文字列	いいえ	コンテキストのネームスペースのフルパス。
`context[project]`	文字列	いいえ	コンテキストのプロジェクトのフルパス。

context[user]パラメータを省略した場合、APIは認証済みユーザーを使用します。

実験がそのcontext_keysでactorを宣言している場合、アクターはcontext[user]から解決されます。個別のcontext[actor]パラメータはありません。

実験では、例えばcontext_keys :user, :namespaceのように複数のコンテキストキーを宣言できます。その場合、宣言されたすべてのキーを渡してください。yalnızca user ve actorキーが認証済みユーザーにフォールバックします。namespaceネームスペースとprojectは常に明示的に渡す必要があります。

userコンテキストを持つ実験のリクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/my_experiment/assignments?context[user]=sidney-jones"

namespaceコンテキストを持つ実験のリクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/my_experiment/assignments?context[namespace]=my-group"

context_keys :user, :namespaceを宣言する実験のリクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/my_experiment/assignments?context[user]=sidney-jones&context[namespace]=my-group"

レスポンス例:

{
  "experiment": "my_experiment",
  "variant": "candidate",
  "context_key": "my_experiment:a1b2c3d4e5f6",
  "cached": true
}

バリアントの割り当てをクリアする

指定されたコンテキストの実験キャッシュから強制されたバリアントの割り当てを削除し、アクターを通常のロールアウトの割り当てに戻します。

DELETE /experiments/:experiment_name/assignments

パラメータは以下のとおりです:

属性	タイプ	必須	説明
`experiment_name`	文字列	はい	実験の名前。
`context[user]`	文字列	いいえ	コンテキストのユーザー名。
`context[namespace]`	文字列	いいえ	コンテキストのネームスペースのフルパス。
`context[project]`	文字列	いいえ	コンテキストのプロジェクトのフルパス。

コンテキストの解決は、現在の割り当てを取得すると一致します。context[user]を省略した場合、APIは認証済みユーザーを使用し、実験がactorを宣言している場合、アクターはcontext[user]から解決されます。

成功すると、204 No Contentを返します。

この操作はべき等です。キャッシュされた割り当てがないコンテキストをクリアしても、204 No Contentが返されます。

リクエスト例:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/my_experiment/assignments?context[user]=sidney-jones"