Руководство по работе с API #

Подробности работы API, ограничения и решение типичных проблем.

Процесс загрузки #

Шаг 1: Получение ссылки #

POST /api/v1/datasets/initiate/

Запрос:

{
  "experiment_id": "homepage_test"
}

Ответ:

{
  "upload_url": "https://fra1.digitaloceanspaces.com/...",
  "bucket": "ab-labz-datasets",
  "key": "org/1/experiments/homepage_test/latest.csv",
  "experiment_id": "homepage_test",
  "expires_in": 900
}

Шаг 2: Загрузка файла #

PUT {upload_url}

Используйте полученный upload_url для прямой загрузки файла в облачное хранилище:

with open('dataset.csv', 'rb') as f:
    requests.put(upload_url, data=f, headers={'Content-Type': 'text/csv'})

Шаг 3: Анализ в UI #

После загрузки перейдите в Подготовка данных → Получить по API, введите experiment_id и нажмите Загрузить.

Ограничения #

Идентификатор эксперимента #

Требования к experiment_id:

• Максимальная длина: 128 символов
• Допустимые символы: A-Z, a-z, 0-9, ., _, -
• Не допускается: пробелы, /, кириллица, спецсимволы

Примеры:

✅ homepage_test, test-2025, experiment.v2
❌ homepage test, test/experiment, тест_эксперимент

Размер файла #

• Формат: только CSV
• Ограничения: файлы >200 МБ автоматически удаляются системой в течение 6 часов
• Проверка: размер проверяется при попытке анализа в UI

Время жизни ссылки #

• Presigned URL: действителен 15 минут
• Загружайте файл сразу после получения ссылки
• При истечении ссылки получите новую через /initiate

Структура хранения #

Файлы сохраняются по пути:

org/{org_id}/experiments/{experiment_id}/latest.csv

• {org_id} - ID вашей организации (определяется автоматически по API ключу)
• {experiment_id} - ID эксперимента из запроса
• latest.csv - фиксированное имя файла

Версионирование #

Не поддерживается. Каждая новая загрузка перезаписывает предыдущий файл.

Если нужна история версий, используйте разные experiment_id:

from datetime import datetime

# Добавляем дату к experiment_id
date = datetime.now().strftime('%Y%m%d')
experiment_id = f'homepage_test_{date}'  # homepage_test_20251215

Требования к данным #

Формат файла #

• Формат: CSV (UTF-8)
• Разделитель: запятая или точка с запятой

Обязательные колонки #

• user_id - идентификатор пользователя
• variant - вариант эксперимента (A/B/C)
• date - дата события (формат: YYYY-MM-DD)

Метрики #

Минимум одна метрика:

• Conversion - бинарные метрики (0/1)
• Numeric - числовые метрики (revenue, время и т.д.)

Пример:

user_id,variant,date,conversion,revenue
user_001,A,2025-12-01,1,150.50
user_002,B,2025-12-01,0,0
user_003,A,2025-12-02,1,200.00

Решение проблем #

400 Bad Request - Invalid experiment_id #

Причина: Недопустимые символы или длина >128

Решение:

import re

def validate_experiment_id(exp_id: str) -> bool:
    return len(exp_id) <= 128 and bool(re.match(r'^[A-Za-z0-9._-]+$', exp_id))

401 Unauthorized #

Причина: Неверный API ключ или неправильный формат заголовка

Решение:

# ✅ Правильно
headers = {'Authorization': f'Bearer {API_KEY}'}

# ❌ Неправильно
headers = {'Authorization': API_KEY}  # Нет 'Bearer '

Проверьте статус ключа в Информация → API ключи.

403 Forbidden (при PUT) #

Причина: Presigned URL истёк (>15 минут)

Решение: Получите новую ссылку через /initiate и повторите загрузку

try:
    requests.put(upload_url, data=file)
except requests.HTTPError as e:
    if e.response.status_code == 403:
        # Получить новую ссылку
        response = requests.post(...)
        new_url = response.json()['upload_url']
        requests.put(new_url, data=file)

404 Not Found (в UI при анализе) #

Причина: Датасет с указанным experiment_id не найден в хранилище

Решение: Убедитесь что PUT запрос завершился успешно (200 OK)

response = requests.put(upload_url, data=file)
response.raise_for_status()  # Выбросит исключение при ошибке
print(f"Status: {response.status_code}")  # Должно быть 200

400 File too large (в UI при анализе) #

Причина: Файл превышает 200 МБ

Решение:

• Уменьшите размер датасета
• Удалите ненужные столбцы
• Разделите на несколько файлов с разными experiment_id

Логирование #

Рекомендуем логировать загрузки для мониторинга:

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

def upload_dataset(file_path, experiment_id):
    logging.info(f"Starting upload: {experiment_id}")
    try:
        # ... загрузка ...
        logging.info(f"Upload successful: {experiment_id}")
    except Exception as e:
        logging.error(f"Upload failed: {experiment_id}, error: {e}")
        raise