Лист Параметры
Лист Параметры выполняет две основные задачи: настройка выгрузок и ручной запуск выгрузок.
Функции
Функция - это гугл-скрипт, который делает выгрузку конкретных данных.
Функции реализуют методы API. Для детального понимания того, что делает функция, нужно обратиться к описанию метода API, указанного в описании функции.
Например: В разделе WB (на листе Параметры) первой идет функция getListNomenclature. В ее описании указан метод Контент → Просмотр → Список номенклатур (НМ). Открываем старую документацию API WB, в меню сверху открываем Контент, в меню слева открываем Просмотр и выбираем метод Список номенклатур (НМ).
В новой документации API WB Контент расположен под заголовком Работа с товарами, далее - Номенклатуры и затем Список номенклатур.
Далее в разделе Ответы получаем структуру выгружаемых данных.
Поскольку ВБ постоянно делает огромное количество изменений, описание функций может не вполне соответствовать текущему расположению описаний методов. Если что-то не удается найти, свяжитесь с нами и вместе мы обязательно найдем метод и поправим описание реализующей его функции.
Одни функции реализуют только один метод, другие - сразу несколько связанных методов.
Параметры
Параметры - это настройки функций. Например, настройка периода за который выгружать данные.
Установленные по умолчанию настройки подходят для большинства случаев, поэтому разбираться в них нужно только при необходимости.
Функции реализуют адаптированную версию методов API. Поэтому параметры функций отличаются от параметров методов API.
Объясним это на примере функции getOzonAnalyticsDataFree, реализующей метод Озон → Аналитические отчёты → Данные аналитики.
Открываем описание метода в документации API Озон. Параметры метода включают даты начала и конца периода, группировку, фильтры, размер страницы (количество строк в ответе), метрики, отступ и сортировку.
Разберем адаптацию перечисленных параметров для применения пользователями (менеджерами и селлерами).
Как правило, для аналитики используется скользящее окно времени - предыдущий день, последние 7 или 30 дней. Чтобы избавить пользователя от высчитывания дат параметр функции использует не саму дату, а количество дней до нее. Это значит, что для метода API дату нужно указывать в формате ДД.ММ.ГГГГ, а для функции - просто число. Например число 1 в параметре функции означает "один день назад от текущего". То есть период последних семи дней исключая текущий: первый параметр → 8, второй → 1. Семь дней включая текущий: первый параметр → 7, второй → 0 (сегодня, вчера, позавчера и еще 4 дня).
Как правило, группировки по sku и дням достаточно. Из этих данных можно посчитать все остальные группировки. Поэтому третьим параметром по умолчанию указаны именно эти группировки.
Поскольку данные выгружаются для хранения, а цели аналитики могут меняться, фильтры не имеют практического смысла и в функции не используются. По этой же причине выгружаются все возможные метрики. Отдельно выгружаются бесплатные метрики (getOzonAnalyticsDataFree), платные разбиты на две части по причине ограничения ВБ (getOzonAnalyticsDataPaid1 и getOzonAnalyticsDataPaid2).
Размер страницы выбирается максимальный, так как гугл-сервера обеспечены хорошим каналом связи.
При выгрузке для хранения сортировка не имеет смысла, так как данные в любом случае будут обрабатываться. То есть сортировка не задается.
Отступ вычисляется автоматически без участия пользователя.
Таким образом, из 8 параметров метода практическое значение для пользователя имеют только начальная и конечная даты.
Второй пример. Функции getOzonDeliveriesStart и getOzonDeliveriesNext работают совместно. Об этом сказано в описании функций: первая выгружает в служебный лист чекера список доставок и затем вторая функция частями выгружает по этому списку информацию. В первом параметре указывается за сколько предыдущих дней выгружать доставки. При ежедневной выгрузке данных нет смысла каждый день выгружать данные за год. Но, принимая во внимание технические риски пропуска данных за 1 - 2 дня (API ВБ иногда сбоит), ежедневная выгрузка данных за 3 крайних дня является хорошим решением.
Выполнение гугл-скриптов ограничивается временем 6 минут. Если список доставок очень большой, для его обработки может не хватить 6 минут. Поэтому список делится на части и обрабатывается частями так, чтобы обработка каждой части с запасом укладывалась в 6 минут. Скорость обработки может меняться по разным причинам, поэтому его размер во втором параметре можно корректировать в зависимости от текущих условий.
Изменение и применение параметров
Изменение параметров происходит автоматически. Однако, поскольку гугл-скрипты иногда зависают, особое внимание уделено подтверждению изменения параметров. Это нужно, чтобы исключить ситуацию, когда на листе Параметры данные изменены, но изменения не приняты гугл-скриптом.
Подтверждением применения параметров является сообщение Параметры применены:
Гугл-скрипт применения параметров может выполняться 3 - 4 минуты, что вызывает неудобство ожидания в случае зависания гугл-скрипта. Поэтому есть дополнительное быстрое сообщение, которое служит для подтверждения срабатывания гугл-скрипта. Быстрое сообщение выводит информацию об измененном параметре в правом нижнем углу:
Появление быстрого сообщения говорит о том, что гугл-скрипт применения параметров успешно запустился и нужно подождать его завершения сообщением о применении параметров.
Если быстрое сообщение отсутствует, значит гугл-скрипт применения параметров не запустился автоматически. В этом случае его нужно запустить вручную нажатием кнопки Применить, расположенной во второй строке листа Параметры:
Организация данных
Данные в чекере организованы системно.
Данные одного раздела API выгружаются в один датасет. Например, данные из раздела API ВБ Статистика выгружаются в датасет wb_api_statistics, из раздела Тарифы в датасет wb_api_tariffs и т.д.
Названия соответствующих функциям датасетов указаны в колонке Датасет на листе Параметры.
Названия датасетов ВБ соответствуют названиям разделов старой документации API. Чекер не будет приводить названия датасетов в соответствие с новыми обстоятельствами, так как это нанесет ущерб процессам пользователей чекера.
Названия таблиц, как правило, соответствуют названиям методов API. Например, данные метода API Мой Склад → Ассортимент выгружаются в таблицу Ассортимент, из метода Озон → Финансовые отчёты → Список транзакций в таблицу Список транзакций. Возможны неполные соответствия. Названия соответствующих функциям таблиц указаны в колонке Таблица BigQuery на листе Параметры.
Названия таблиц
Данные выгружаются в таблицы. Названия таблиц формируются автоматически.
Названия таблиц состоят из постоянной части, даты и названия кабинета, указанного на листе Ключи API.
Постоянные части названий таблиц приведены в колонке Таблица на листе Параметры.
Постоянная часть, дата и кабинет разделены символом подчеркивания.
Пример названия таблицы: Приемки_2024-09-25_ИвановИП.
Даты в названиях
В названиях таблиц обычно указана дата. Как правило, это ближняя дата периода времени.
Например, метод Озон → Финансовые отчёты → Список транзакций выгружается 30.09.2024 за 4 дня. Ближняя дата периода - 30.09.2024, дальняя дата периода - 26.09.2024. В названии таблицы будет ближняя дата: Список транзакций_2024-09-30_ИвановИП.
Таким образом, выгрузка на каждую дату создает отдельную таблицу выгруженных данных.
Если выгрузка не зависит от даты, в названии может быть текущая дата или даты не будет.
Например, выгрузка метода Озон → Финансовые отчёты → Суммы транзакций не зависит от дат напрямую, так как выгружает информацию в соответствии с id транзакции. В названии таблицы будет текущая дата, то есть дата выгрузки данных.
Структуры данных
В некоторых случаях структура выгружаемых данных может быть дополнена или изменена.
Дополнение структуры используется в случаях, когда выгружаемые данные не содержат данных запроса.
Например, выгрузка метода Озон → Финансовые отчёты → Суммы транзакций выгружает данные для запрашиваемого posting_number, но в возвращаемых данных posting_number отсутствует. Поэтому полученные данные дополняются posting_number.
Изменение структуры данных используется в том случае, когда выгружаемые данные оптимизированы не для непосредственного использования в построении аналитических таблиц, а для передачи данных.
Например, метод Озон → Аналитические отчёты → Данные аналитики выгружает данные в виде массива массивов. Это компактная форма удобна для передачи. Для хранения данных и для построения таблиц эта форма неудобна. Поэтому чекер разворачивает выгружаемый массив массивов в таблицу реляционной БД.
Подробности изложены в Примечания к выгрузкам.
Режим сохранения данных
Режим сохранения данных определяет результат повторной выгрузки. Если одну и ту же функцию с одним и тем же набором параметров запустить два раза подряд, то в режиме замещения сохраняемых данных результат будет отличаться от режима добавления сохраняемых данных.
В режиме замещения при повторной выгрузке данные заместят ранее полученные данные. В режиме замещения таблица с первично полученными данными удаляется и вновь полученные данные сохраняются в таблицу с тем же названием.
В режиме добавления при повторной выгрузке данные добавятся к ранее полученным данным. В режиме добавления таблица с первично полученными данными не удаляется и вновь полученные данные добавляются в таблицу с уже существующими данными. Если данные повторной выгрузки совпадают с уже имеющимися, то в таблице будет два набора одинаковых строк. При третьем повторе выгрузки данные будут затраиваться и т.д.
Режим сохранения данных определяется тем, укладывается или нет продолжительность выгрузки в стандартную гугл-сессию 6 минут.
Если выгрузка гарантированно успевает завершиться за 6 минут, действует режим замещения.
Когда 6 минут недостаточно для завершения, промежуточные результаты сохраняются на лист чекера и затем частями выгружаются оттуда каждые 5 минут. При выгрузке первой части создается таблица для сохранения данных, при выгрузке следующих частей данные добавляются к сохраненным ранее.