実験結果を Notion にエクスポートする

Automation API を使用して実験とその結果を取得し、それらを Notion のページプロパティに変換して、単一の Python スクリプトを使用してレコードを Notion データベースにアップサートします。

ゴール

このチュートリアルでは、kameleoon_to_notion.py スクリプトの動作をステップごとに説明します。Kameleoon の実験 ID と Notion のデータベース ID を指定すると、スクリプトは実験のメタデータと統計結果を取得し、最も成果の良いバリエーションを判断して、データを Notion の Experiments データベースにマッピングし、レコードを Notion に書き戻します。同じ実験に対してスクリプトを再実行すると、重複を作成する代わりに既存のページを更新します。ステップ 1〜5 は、Airtable エクスポートのチュートリアルと同じリクエストとポーリングのフローを再利用します。変わるのは書き込み先のみです。

Notion の API にはネイティブなアップサート機能がありません。スクリプトは、データベースのデータソースに対して実験名と一致するタイトルを持つページを問い合わせ、見つかった場合はそのページを更新し、見つからない場合は新しいページを作成することで、アップサートをエミュレートします。本チュートリアルは、各データベースを 1 つ以上のデータソースを中心に整理する Notion API バージョン 2025-09-03 を対象としています。

要件

Kameleoon API の認証情報。 Automation API にはアクセストークンが必要です。スクリプトは client_credentials グラントを使用して、client_id と client_secret からプログラムでアクセストークンを取得します。アクセストークンを取得するを参照してください。
Notion の内部インテグレーショントークン。 notion.so/my-integrations でインテグレーションを作成し、そのトークンをコピーします。
Experiments スキーマを持つ Notion データベース。次のプロパティが必要です: Experiment Name（title）、Status（select）、Start date（date）、End date（date）、Notes（rich text）、Actual（number）、Probability（select）、Result（select）。
Notion のデータベース ID。 データベースをフルページとして開きます（ID は URL 内の ?v= ビューパラメータの前にある 32 文字の文字列です）。
Python 3.9 以上、requests ライブラリを含む（pip install requests）。

データベースをインテグレーションと共有してください。共有しないと、すべてのリクエストが object_not_found を返します。データベースを開き、••• → Connections → Add connections に進んで、インテグレーションを選択します。

すべての認証情報は環境変数に保存してください。スクリプトにシークレットをハードコードしないでください。

export KAMELEOON_CLIENT_ID="..."
export KAMELEOON_CLIENT_SECRET="..."
export NOTION_TOKEN="..."

このチュートリアルでは、例として実験 Product Page Redesign（ID 188308）を使用します。オリジナルバリエーションに加えて、Redesign 1（ID 828220）と Redesign 2（ID 828221）の 2 つのバリエーションがあります。

1. Automation API で認証する

エンドポイント: トークンエンドポイントに POST リクエストを送信して、アクセストークンを取得します。

POST https://api.kameleoon.com/oauth/token

フィールド	型	説明
grant_type	String	`client_credentials` に設定します。
client_id	String	Automation API のクライアント ID。
client_secret	String	Automation API のクライアントシークレット。

例:

def kameleoon_token(client_id, client_secret):
    resp = requests.post(
        "https://api.kameleoon.com/oauth/token",
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret,
        },
    )
    resp.raise_for_status()
    return resp.json()["access_token"]

レスポンス:

{ "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." }

返された access_token は、以降のすべての Automation API リクエストで Bearer トークンとして送信されます。アクセストークンはデフォルトで 2 時間有効です。

2. 実験を取得する

エンドポイント: Get an experiment エンドポイントに GET リクエストを送信して、実験のメタデータを取得します。

GET https://api.kameleoon.com/experiments/{experimentId}

フィールド	型	説明
experimentId	Integer	必須のパスパラメータ。取得する実験の ID。

例:

def get_experiment(token, experiment_id):
    resp = requests.get(
        f"https://api.kameleoon.com/experiments/{experiment_id}",
        headers={"Authorization": f"Bearer {token}"},
    )
    resp.raise_for_status()
    return resp.json()

レスポンス（一部省略）:

{
  "id": 188308,
  "name": "Product Page Redesign",
  "status": "STOPPED",
  "dateStarted": "2025-01-15T09:00:00Z",
  "dateEnded": "2025-02-12T18:00:00Z",
  "description": "Testing two redesigns of the product page.",
  "mainGoalId": 279599,
  "variations": [828220, 828221]
}

スクリプトは、Notion のページ用に name、status、dateStarted、dateEnded、description を読み取り、次のステップで結果リクエストの範囲を絞り込むために mainGoalId を読み取ります。

API はデフォルトで mainGoalId を返すため、これを読み取るために optionalFields パラメータは必要ありません。Automation API は status フィールドの固定された列挙値を公開しておらず、トークンは今後変わる可能性があります。ステップ 7 では status を大文字・小文字を区別せずにマッチングするため、アカウント間の大文字・小文字の違いによってマッピングが破綻することはありません。

3. 実験の結果をリクエストする

エンドポイント: Request experiment’s results エンドポイントに POST リクエストを送信して、結果レポートの生成をトリガーします。

POST https://api.kameleoon.com/experiments/{experimentId}/results

フィールド	型	説明
experimentId	Integer	必須のパスパラメータ。
goalsIds	Array	レポートを指定したゴール ID に限定します。スクリプトは実験の `mainGoalId` を渡します。
referenceVariationId	String	比較の基準として使用するバリエーション。`"0"` はオリジナルページを使用します。
visitorData	Boolean	訪問ベースのデータには `false`、訪問者ベースのデータには `true` を指定します。
sequentialTesting	Boolean	ベイズ成功確率の代わりに、信頼区間に逐次検定を使用する場合は `true` に設定します。いずれか一方の手法のみを有効にしてください。
bayesian	Boolean	レポートにベイズ成功確率を含める場合は `true` に設定します。スクリプトはこの値を読み取って Probability プロパティに設定します。
conversionType	String	`ALL_CONVERSION` または `CONVERTED_VISITS`。

例:

def request_results(token, experiment_id, goal_id):
    body = {
        "visitorData": False,
        "sequentialTesting": False,
        "bayesian": True,
        "referenceVariationId": "0",
        "conversionType": "ALL_CONVERSION",
        "goalsIds": [goal_id] if goal_id else None,
    }
    resp = requests.post(
        f"https://api.kameleoon.com/experiments/{experiment_id}/results",
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Accept": "*/*",
        },
        json=body,
    )
    resp.raise_for_status()
    return resp.json()["dataCode"]

レスポンス:

{ "dataCode": "14443931880924098266207585267983330260134079899081739889989435434342588016765" }

Kameleoon はレポートを非同期で生成します。エンドポイントは dataCode を返し、次のステップではこれを使用して結果をポーリングします。

このスクリプトには bayesian: true が必要で、sequentialTesting: false を設定します。bayesian と sequentialTesting は有意性を算出するための代替手法であり、このチュートリアルはベイズ成功確率をレポートします。ベイズ推定を有効にすると、レポートの reliability の値にベイズ成功確率（あるバリエーションが参照バリエーションに勝る確率）が反映され、スクリプトはこの値を Probability プロパティにマッピングします。アカウントが別のデフォルトの統計手法を使用している場合は、Kameleoon アプリ内の同じレポートと照らして値を確認してください。

4. 結果をポーリングする

エンドポイント: Poll results エンドポイントに GET リクエストを送信し、レポートが準備できるまで取得を繰り返します。

GET https://api.kameleoon.com/results?dataCode={dataCode}

フィールド	型	説明
dataCode	String	前のステップで返された必須のクエリパラメータ。

レスポンスの status は、レポートが計算されている間は WAITING、データが利用可能になると READY、失敗時は ERROR または TIMEOUT になります。ステータスが ERROR または TIMEOUT の場合、レスポンスにはトップレベルの errorDescription が含まれます。スクリプトは、ステータスが READY になるまで一定の間隔でポーリングします。例:

def poll_results(token, data_code, max_attempts=30, delay=2.0):
    for _ in range(max_attempts):
        resp = requests.get(
            "https://api.kameleoon.com/results",
            headers={"Authorization": f"Bearer {token}"},
            params={"dataCode": data_code},
        )
        resp.raise_for_status()
        payload = resp.json()
        status = payload.get("status")
        if status == "READY":
            return payload["data"]
        if status in ("ERROR", "TIMEOUT"):
            raise RuntimeError(payload.get("errorDescription") or status)
        time.sleep(delay)  # status == "WAITING"
    raise TimeoutError("Timed out waiting for results.")

レスポンス（一部省略）:

{
  "status": "READY",
  "data": {
    "variationData": {
      "_reference": { "breakdownData": { "_reference": { "generalData": {
        "goalsData": { "279599": { "conversionRate": 0.0149 } } } } } },
      "828220": { "breakdownData": { "_reference": { "generalData": {
        "goalsData": { "279599": {
          "reliability": 100.0,
          "improvementRate": 211.48,
          "conversionRate": 0.0466
        } } } } } },
      "828221": { "breakdownData": { "_reference": { "generalData": {
        "goalsData": { "279599": {
          "reliability": 100.0,
          "improvementRate": -43.33,
          "conversionRate": 0.0085
        } } } } } }
    }
  }
}

5. 最も成果の良いバリエーションを選択する

結果には、variationData の下にバリエーションごとに 1 つのエントリと、オリジナルページ用の _reference の行が含まれます。各バリエーションについて、リクエストしたゴールの指標は breakdownData._reference.generalData.goalsData[goalId] の下にあります。スクリプトは _reference エントリをスキップし、各バリエーションの improvementRate と reliability（ベイズ成功確率）を読み取り、改善率が最も高いバリエーションを最も成果の良いものとして選択します。あるバリエーションの goalsData に要求したゴール ID が含まれていない場合、スクリプトは存在するゴールにフォールバックします。ステップ 3 で goalsIds によりリクエストを単一のゴールに絞り込んでいるため、このフォールバックには通常ほかに選択できるゴールがありません。後でマッピングされる Result プロパティには、そのバリエーションが十分に高い成功確率と正の上昇率を達成し、正真正銘の勝利と見なせるかどうかが記録されます。例:

def pick_best_variation(result_data, goal_id):
    best, best_improvement = {}, float("-inf")
    for variation_id, vdata in result_data["variationData"].items():
        if variation_id == "_reference":
            continue
        general = vdata["breakdownData"]["_reference"]["generalData"]
        goals_data = general.get("goalsData", {})
        if not goals_data:
            continue
        key = str(goal_id) if str(goal_id) in goals_data else next(iter(goals_data))
        metrics = goals_data[key]
        improvement = metrics.get("improvementRate")
        if improvement is not None and improvement > best_improvement:
            best_improvement = improvement
            best = {
                "variation_id": variation_id,
                "improvement_rate": improvement,
                "bayesian_probability": metrics.get("reliability"),
            }
    return best

この例では、両方のバリエーションが 100% のベイズ成功確率に達していますが、Redesign 1（828220）は +211.48% の改善を示しているのに対し、Redesign 2 は -43.33% です。したがって、Redesign 1 が最も成果の良いバリエーションであり、95% を超える確率と正の上昇率を伴う正真正銘の勝者です。

6. Notion のデータソースを解決する

バージョン 2025-09-03 以降、Notion データベースは 1 つ以上のデータソースを格納するコンテナとなり、ページの書き込みとクエリはデータベース ID ではなくデータソース ID を対象とします。この 2 つの ID は相互に置き換えることができません。 エンドポイント: Retrieve a database エンドポイントに GET リクエストを送信して、データベースを取得し、そのデータソースを確認します。

GET https://api.notion.com/v1/databases/{databaseId}

Notion へのすべてのリクエストは、インテグレーショントークンを Bearer トークンとして、また Notion-Version ヘッダーとともに送信します。例:

NOTION_VERSION = "2025-09-03"


def notion_headers(token):
    return {
        "Authorization": f"Bearer {token}",
        "Notion-Version": NOTION_VERSION,
        "Content-Type": "application/json",
    }


def get_data_source_id(token, database_id):
    resp = requests.get(
        f"https://api.notion.com/v1/databases/{database_id}",
        headers=notion_headers(token),
    )
    resp.raise_for_status()
    data_sources = resp.json().get("data_sources", [])
    if not data_sources:
        raise RuntimeError("The database has no data sources.")
    return data_sources[0]["id"]

レスポンス（一部省略）:

{
  "object": "database",
  "id": "255104cd-477e-808c-b279-d39ab803a7d2",
  "data_sources": [
    { "id": "bc1211ca-e3f1-4939-ae34-5260b16f627c", "name": "Experiments" }
  ]
}

スクリプトは最初のデータソースを使用します。データベースに複数のデータソースが存在する場合は、Experiments のプロパティと一致するスキーマを持つものを選択してください。

7. データを Notion プロパティにマッピングする

スクリプトは、実験のメタデータと最も成果の良いバリエーションの指標を、Notion のプロパティ値に変換します。各プロパティタイプには、それぞれ固有の JSON 形式があります。

Notion プロパティ	型	ソース	変換
Experiment Name	Title	`experiment.name`	そのまま使用。アップサートのキーとして使用します。
Status	Select	`experiment.status`	大文字・小文字を区別せずにマッピングします: `active → Running`、`draft`/`planned → Implementing`、`stopped`/`diverted → Completed`、`paused → Defunct`。
Start date	Date	`experiment.dateStarted`	日時を ISO 形式の日付（`YYYY-MM-DD`）に切り詰めたもの。
End date	Date	`experiment.dateEnded`	日時を ISO 形式の日付に切り詰めたもの。
Notes	Rich text	`experiment.description`	そのまま使用。
Actual	Number	最も成果の良いバリエーションの `improvementRate`	そのまま使用（測定された上昇率、%）。
Probability	Select	最も成果の良いバリエーションのベイズ成功確率	区分: `≥95` → `80% - High`、`≥80` → `50% - Medium`、それ以外は `20% - Low`。
Result	Select	ベイズ成功確率 + `improvementRate`	確率が `95` 以上かつ上昇率が正 → `Success`。`95` 以上かつ上昇率が負 → `Failure`。それ以外は `Inconclusive`。

スクリプトは空の値を省略するため、更新時に既存のプロパティ値が空欄で上書きされることはありません。Notion は不足している select の選択肢を自動的に作成しますが、プロパティ自体は正しい型でデータソースのスキーマにあらかじめ存在している必要があります。例:

STATUS_MAP = {
    "ACTIVE": "Running",
    "DRAFT": "Implementing",
    "PLANNED": "Implementing",
    "PAUSED": "Defunct",
    "STOPPED": "Completed",
    "DIVERTED": "Completed",
}


def map_status(status):
    return STATUS_MAP.get((status or "").upper())


def to_iso_date(value):
    return value[:10] if value else None


def bayesian_to_probability(probability):
    if probability is None:
        return None
    if probability >= 95:
        return "80% - High"
    if probability >= 80:
        return "50% - Medium"
    return "20% - Low"


def derive_result(probability, improvement):
    if probability is None or improvement is None:
        return "Inconclusive"
    if probability >= 95 and improvement > 0:
        return "Success"
    if probability >= 95 and improvement < 0:
        return "Failure"
    return "Inconclusive"


def build_notion_properties(experiment, best):
    probability = best.get("bayesian_probability")
    improvement = best.get("improvement_rate")
    props = {}

    name = experiment.get("name")
    if name:
        props["Experiment Name"] = {"title": [{"text": {"content": name}}]}

    status = map_status(experiment.get("status"))
    if status:
        props["Status"] = {"select": {"name": status}}

    start = to_iso_date(experiment.get("dateStarted"))
    if start:
        props["Start date"] = {"date": {"start": start}}

    end = to_iso_date(experiment.get("dateEnded"))
    if end:
        props["End date"] = {"date": {"start": end}}

    notes = experiment.get("description")
    if notes:
        props["Notes"] = {"rich_text": [{"text": {"content": notes}}]}

    if improvement is not None:
        props["Actual"] = {"number": improvement}

    bucket = bayesian_to_probability(probability)
    if bucket:
        props["Probability"] = {"select": {"name": bucket}}

    result = derive_result(probability, improvement)
    if result:
        props["Result"] = {"select": {"name": result}}

    return props

Notion では、データソースごとに 1 つの title プロパティしか許可されません。スクリプトは Experiment Name という名前のプロパティをキーにしてアップサートを行います。title プロパティの名前が異なる場合は、こことステップ 8 のクエリフィルタの両方でその名前に変更してください。

8. ページを Notion にアップサートする

Notion にはアップサート用のエンドポイントがないため、スクリプトはデータソースに対して Experiment Name が一致するページを問い合わせ、見つかった場合はそのページを更新し、見つからない場合は新しいページを作成します。 検索: Query a data source エンドポイントを使用して、タイトルフィルタでデータソースに問い合わせます。

POST https://api.notion.com/v1/data_sources/{dataSourceId}/query

作成: Create a page エンドポイントを使用して、データソースを親とするページを追加します。

POST https://api.notion.com/v1/pages

更新: Update page properties エンドポイントを使用して、一致したページのプロパティを上書きします。

PATCH https://api.notion.com/v1/pages/{pageId}

例:

def find_page(token, data_source_id, name):
    resp = requests.post(
        f"https://api.notion.com/v1/data_sources/{data_source_id}/query",
        headers=notion_headers(token),
        json={
            "filter": {"property": "Experiment Name", "title": {"equals": name}},
            "page_size": 1,
        },
    )
    resp.raise_for_status()
    results = resp.json().get("results", [])
    return results[0]["id"] if results else None


def upsert_page(token, data_source_id, properties):
    title = properties.get("Experiment Name", {}).get("title")
    name = title[0]["text"]["content"] if title else None

    page_id = find_page(token, data_source_id, name) if name else None
    if page_id:
        resp = requests.patch(
            f"https://api.notion.com/v1/pages/{page_id}",
            headers=notion_headers(token),
            json={"properties": properties},
        )
        action = "Updated"
    else:
        resp = requests.post(
            "https://api.notion.com/v1/pages",
            headers=notion_headers(token),
            json={
                "parent": {"type": "data_source_id", "data_source_id": data_source_id},
                "properties": properties,
            },
        )
        action = "Created"
    resp.raise_for_status()
    return resp.json(), action

レスポンス（一部省略）:

{
  "object": "page",
  "id": "1a2b3c4d-5e6f-7081-9abc-def012345678",
  "properties": {
    "Experiment Name": { "title": [{ "plain_text": "Product Page Redesign" }] },
    "Status": { "select": { "name": "Completed" } },
    "Start date": { "date": { "start": "2025-01-15" } },
    "End date": { "date": { "start": "2025-02-12" } },
    "Actual": { "number": 211.48 },
    "Probability": { "select": { "name": "80% - High" } },
    "Result": { "select": { "name": "Success" } }
  }
}

9. スクリプトを実行する

実験 ID と Notion のデータベース ID を引数として渡します:

python kameleoon_to_notion.py \
  --experiment-id 188308 \
  --database-id 255104cd477e808cb279d39ab803a7d2

スクリプトは、認証、取得した実験、最も成果の良いバリエーション、解決されたデータソース、マッピングされたプロパティ、そして Notion のページを作成したか更新したかという各ステップを出力します。

カスタマイズに関する注意事項

ステータスマッピング は STATUS_MAP 定数にあり、API が返すステータストークンをキーとし、大文字・小文字を区別せずにマッチングします。Status の選択肢が Running / Implementing / Completed / Defunct と異なる場合はターゲットの値を調整し、単一の GET /experiments/{experimentId} でアカウントが返すトークンを確認してください。
Probability は測定されたベイズ成功確率からマッピングされ、結果リクエストで bayesian: true が必要です。Probability プロパティが実験前の見積もりを手動で入力するものである場合は、build_notion_properties から Probability のブロックを削除してください。
ゴールの選択 には実験の mainGoalId を使用します。別のゴールについてレポートするには、そのゴール ID を request_results と pick_best_variation に渡してください。
アップサートキー。 タイトルの照合は厳密に一致させるため、Experiment Name の大文字・小文字や空白の違いは、既存のページを更新する代わりに新しいページを作成してしまいます。検索してから書き込むフローはアトミックではないため、同じ実験に対して 2 つのエクスポートを同時に実行しないでください。
API バージョン。 スクリプトは Notion-Version: 2025-09-03 に固定されています。後でデータベースに 2 つ目のデータソースを追加した場合は、get_data_source_id を更新して名前で正しいものを選択するようにしてください。
レート制限。 Automation API は 10 秒あたり最大 50 リクエスト、1 時間あたり最大 1,000 リクエストまで許可しており、Notion API の平均は 1 秒あたり約 3 リクエストです。多数の実験をまとめて処理する場合は、トークンをキャッシュし、スロットリングを追加してください。

​ゴール

​要件

​1. Automation API で認証する

​2. 実験を取得する

​3. 実験の結果をリクエストする

​4. 結果をポーリングする

​5. 最も成果の良いバリエーションを選択する

​6. Notion のデータソースを解決する

​7. データを Notion プロパティにマッピングする

​8. ページを Notion にアップサートする

​9. スクリプトを実行する

​カスタマイズに関する注意事項

ゴール

要件

1. Automation API で認証する

2. 実験を取得する

3. 実験の結果をリクエストする

4. 結果をポーリングする

5. 最も成果の良いバリエーションを選択する

6. Notion のデータソースを解決する

7. データを Notion プロパティにマッピングする

8. ページを Notion にアップサートする

9. スクリプトを実行する

カスタマイズに関する注意事項