Выгрузка данных из лид-форм VK Рекламы в Google Таблицы

Инструкция по выгрузке данных из лид-форм VK Рекламы и загрузки их в Google Таблицу (API VK, Python, Colab) для нового VK Ads. Будет полезна абсолютно всем – и таргетологам, и владельцам сообществ VK, и SMM-специалистам, и контент-мейкерам.

Чем мы будем пользоваться?

Несмотря на то, что выгрузка данных по лид-формам осуществляется с помощью языка программирования Python, API VK Рекламы, Google Таблиц и компьютера с интернетом, никакие дополнительные программы на свой компьютер устанавливать не нужно.

Все действия мы будем выполнять в любимом браузере (Chrome, Opera, Yandex, Safari, Edge или любой другой). Главное – это подключение к интернету, поскольку без него мы не сможем обращаться к API и выгружать данные по лид-формам.

А как же быть с Python? Чтобы иметь возможность выгружать данные, необходимо использовать API. API ВКонтакте — это интерфейс, который позволяет получать информацию из базы данных vk.com с помощью специальных запросов. А чтобы эти запросы отправлять и получать от VK ответ, необходимо использовать Python и специальное программное обеспечение (ПО). Такое ПО называют интегрированной средой разработки (IDE). Наиболее популярным Python IDE является PyCharm.

Многие специалисты в своей работе так же используют блокнот Jupyter Notebook, который можно установить с помощью дистрибутива Anaconda, включающий набор популярных библиотек для работы с данными. Еще есть Visual Studio Code и много других продуктов. Выбор тех или иных программ зависит исключительно от ваших предпочтений в изучении или от тех инструментов, которые используются в вашей компании.

Вот чтобы не усложнять и избавить себя от излишних сложностей, я предлагаю использовать другой сервис - Google Colab.

Colaboratory (или просто Colab) — это бесплатный продукт Google. Он позволяет любому человеку писать и выполнять код Python прямо в браузере, без установки каких-либо программ и без дополнительной настройки на компьютере. Для наших задач этого будет достаточно.

Таким образом, для работы вам понадобится:

• браузер;
• интернет;
• доступы к рекламным кабинетам VK Рекламы (где есть лид-формы);
• официальная документация VK;
• программа в Colab на Python;
• учетная запись в Gmail;
• проект в Google Cloud;
• файл Google Таблиц, куда вы будете выгружать данные по лид-формам.

Введение

Материал написан с минимальным количеством сложных терминов, определений, без лишних действий, но с большим количеством скриншотов и подробными описаниями.

Все шаги, представленные в данном руководстве, сможет повторить любой человек самостоятельно – начинающий специалист, профессионал и даже тот, кто никогда не работал с языком программирования Python, не знает что такое API, никогда лично не заходил в рекламный кабинет VK Рекламы и не работал с лид-формами. Инструкция будет полезна абсолютно всем – и таргетологам, и владельцам сообществ VK, и SMM-специалистам, и контент-мейкерам.

Давайте приступим. Итак, доступ к API VK Рекламы могут получить агентства и прямые рекламодатели - юридические и физические лица. В качестве примера я буду демонстрировать выгрузку данных из лид-форм VK Рекламы для отдельных рекламных кабинетов, для которых есть доступ.

Внимание: вам необходимо выполнить следующие шаги в заданной последовательности.

1. запросить доступ к API в рекламном кабинете VK;
2. скопировать мою программу Colab к себе;
3. получить токен доступа;
4. получить список лид-форм;
5. получить список лидов из лид-форм;
6. создать проект в Google Cloud;
7. активировать API Google Sheets и Google Drive;
8. получить сервисный аккаунт и ключ JSON;
9. загрузить ключ JSON на Google Диск;
10. подключиться в программе к Google Диску;
11. загрузить список лидов из лид-форм VK Рекламы в Google Таблицы.

Шаги по обновлению токена или удалению всех токенов пользователя при достижении вами лимитов не являются обязательными для выполнения. Все зависит только от вашей конкретной ситуации. Хоть руководство и описывает подробно все этапы выгрузки данных из лид-форм в Google Таблицы и ошибки, с которыми я столкнулась в процессе разработки этого решения, всегда найдутся индивидуальные случаи. Я не гарантирую полноту приводимых сведений.

Примечание: если ваша задача отличается от того, что представлено в этой инструкции, тогда вам нужно будет доработать мою программу самостоятельно под ваш проект.

Запросить доступ к API

Для получения доступа перейдите в свой личный кабинет VK Рекламы (откуда вы планируете выгружать данные по лид-формам) по ссылке.

Проверьте, что вы заполнили реквизиты:

• для агентств и рекламодателей юрлиц - в разделе Бюджет. Реквизиты должны быть проверены модерацией;
• для рекламодателей физлиц - в разделе Настройки.

Затем перейдите в раздел Настройки - Доступ к API и нажмите Запросить доступ к API.

Заполните ФИО и контакты сотрудника, который отвечает за использование API. Указывайте реальные данные - они нужны для оперативной связи, если возникнут проблемы. Если вы будете работать с API, то укажите свои данные.

Нажмите Запросить доступ. Вы увидите ваш client_id и кнопку для получения client_secret. Нажмите на нее. Эти данные нужны, чтобы получить токен доступа.

Скопируйте и сохраните client_secret. В целях безопасности получить его можно только в течение 10 минут.

После этого вам необходимо получить токен доступа. Для аутентификации и авторизации в API используется протокол OAuth2, из спецификации которого реализовано две стандартные схемы (flow): Client Credentials Grant и Authorization Code Grant, и одна нестандартная – Agency Client Credentials Grant.

• Client Credentials Grant используется для работы с данными собственного аккаунта через API;
• Agency Client Credentials Grant используется для работы с данными собственных клиентов агентств/менеджеров;
• Authorization Code Grant используется для получения доступа к данным сторонних аккаунтов VK Ads.

Копирование программы в Colab

Откройте пример моей программы. Скачать ее вы сможете на образовательной платформе edu.osipenkov.ru, в разделе Материалы.

СКАЧАТЬ ПРОГРАММУ

 

Cкопируйте ее к себе на Google Диск с помощью команды Файл - Сохранить копию на Диске, предварительно авторизовавшись под своей учетной записью в Gmail:

После этого вам откроется копия программы, в которую вы сможете вносить свои изменения и запускать ее от своего имени. Доступ к этой программе будет только у вас. Вы можете переименовать программу, задав любое удобное имя, а также сохранить ссылку на программу в закладках браузера.

Шаг №1. Получение токена доступа

Для получения токена доступа мы будем использовать схему Client Credentials Grant. Чтобы его получить, нужно послать запрос вида:

Теперь уже в своей программе измените данные в переменных client_id и client_secret на свои значения, взятые из интерфейса рекламного кабинета VK, добавив их в первую ячейку #Шаг №1 – получение и сохранение токена доступа для работы с API ВКонтакте. Не удаляйте апострофы ʼ  ʼ, они должны быть!

Запустите первый шаг программы, нажав на иконку play рядом с этой ячейкой:

Этот код отправит запрос на API VK для получения токена, используя предоставленные вами client_id и client_secret. В случае успешного выполнения ответ будет выглядеть следующим образом:

В Colab это выглядит так (одна строка – полный ответ, другая – только токен доступа):

Пример:

, где:

• access_token – токен доступа, с которым вы будете работать в дальнейшем. Он используется для авторизации запросов к API ВКонтакте и позволяет приложениям выполнять действия от имени пользователя или приложения и получать доступ к ресурсам. Его необходимо обязательно сохранить;
• token_type – тип токен. В данном случае указано Bearer, что означает, что для доступа к API используется метод Bearer Token Authorization. Это стандартный способ передачи токена в заголовках HTTP-запросов;
• scope - массив, содержащий разрешения (права доступа), которые были предоставлены приложению пользователем. Права доступа определяют, какие действия может произвести API-клиент с данными предоставившего доступ аккаунта;
• expires_in - время жизни токена в секундах. В данном случае 86400 означает, что токен будет действителен в течение 24 часов (т.е. 86400 секунд). По истечении этого времени токен станет недействительным, и для получения новых данных потребуется заново авторизовать пользователя;
• refresh_token - специальный токен, который можно использовать для получения нового access_token без повторной аутентификации пользователя. Обычно refresh_token имеет более долгий срок действия по сравнению с access_token и позволяет продлить сессии без вмешательства пользователя.

Срок действия access-токена

Каждый полученный токен доступа по умолчанию является действительным в течение суток. На это указывает свойство expires_in в ответе на запрос токена доступа. Ограниченный срок жизни позволяет более надежно защитить значение access_token. Даже завладев значением одного access_token, злоумышленник не сможет выполнить запросы с ним по истечении срока действия или после первого обновления токена.

Поскольку токен имеет ограничение по времени, то его периодически необходимо обновлять. Например, когда вы увидите такую ошибку:

{"code": "invalid_token", "message": "Unknown access token"}

Обновление токена

Код для обновления токена в программе представлен в ячейке под названием #Обновление токена доступа.

Не забудьте заменить данные в соответствующих переменных client_id и client_secret на свои, а в refresh_token подставить значение, полученное на шаге 1, когда вы впервые получали токен доступа для API ВКонтакте:

Нижеприведенный текст взят из официальной документации VK:

Важно учитывать, что обновление токена не создает новый экземпляр: меняется значение access_token, старое значение ключа перестает работать. Это может привести к проблемам при работе с API в несколько потоков: два потока могут одновременно обнаружить, что токен истек и отправить запрос на обновление. Запрос, пришедший первым, обновит токен и начнёт его использовать, в то время как второй поток обновит токен еще раз, и первый поток будет пытаться использовать уже несуществующий токен.

Одним из вариантов решения этой проблемы является перехват ошибки о несуществующем токене в первом потоке и получение токена заново из общего для потоков хранилища — например, базы данных, куда каждый поток записывает токен после обновления. Нужно также учесть, что запись в хранилище тоже может быть конкурентной и использовать, например, блокировки.

Другим вариантом решения этой проблемы может быть включение опции обновления refresh_token при каждом обновлении access_token. Тогда первый поток обновит и access_token, и refresh_token, а во втором нужно обработать ошибку о неизвестном refresh_token и перечитать access_token из хранилища. Но при обновления refresh_token нужно обязательно хранить его самое последнее значение, иначе вы больше не сможете обновить access_token, и придется выписывать новый. Эту опцию OAuth-клиента сейчас можно включить только по запросу в службу поддержки.

Еще один вариант: превентивное обновление всех истекающих токенов. Он заключается в том, что нужно регулярно проверять нет ли у вас токенов, истекающих, например, в ближайшие пол часа, и обновлять их в фоновом процессе. Но если совмещать его с обновлением в режиме реального времени в рабочих процессах, то всё равно придется обрабатывать ошибки из-за возможных конфликтов.

Поскольку наша программа по выгрузке лидов из лид-форм будет запускаться вручную, в полуавтоматическом режиме, вы сами сможете контролировать обновление токена доступа.

Внимание: обновление токена доступа необходимо только в том случае, если срок текущего токена доступа закончился. Поэтому пропустите эту инструкцию и вернитесь к ней только когда это будет нужно.

Удаление всех токенов доступа

Для каждой связки client_id - user действуют лимиты: одновременно может существовать не более 5 токенов, вне зависимости от статуса токена. Если один и тот же аккаунт подключен к двум различным приложениям, то каждое из приложений сможет выписать по 5 токенов для данного аккаунта. Лимит фиксирован и не может быть увеличен ни в каких случаях.

Не вечные токены автоматически удаляются по истечении месяца неактивности (указано в поле expires_in). По достижении лимита в ответ на попытку получить новый токен будет возвращена ошибка с HTTP-кодом 403. Во избежание подобных ошибок необходимо корректно обновлять выписанные токены и не создавать их копии.

Но что, если вы вдруг несколько раз запустили первую ячейку программы и вам теперь отображается ошибка такого вида:

Ошибка: 403 {"error":"token_limit_exceeded","error_description":"Active access token limit reached. Please contact ads_api@vk.team and provide your client id in the message.","user_id":14905558}

В этом случае вам необходимо удалить созданные токены для конкретного пользователя (себя). Для этого используется запрос вида:

, где username – это логин пользователя, для которого необходимо удалить токены. Если параметр username не передан, то будут удалены токены аккаунта, для которого был выдан доступ к API.

Поскольку мы сами работаем с API и выдаем токен доступа для себя, то параметр username указывать не нужно. Просто перейдите в программе в самый конец, до ячейки # Удаление всех токенов. Измените данные в переменных client_id и client_secret на свои значения, взятые из интерфейса рекламного кабинета VK.

Запустите ячейку программы. К сожалению, я не знаю, почему ответ приходит с ошибкой 204, но сами токены он удаляет. Поэтому если вы видите надпись Ошибка 204 после выполнения данного фрагмента кода, то все хорошо, и вы можете вернуться в начало программы и перевыпустить токен доступа.

Шаг №2. Получение списка лид-форм

Получив токен доступа, перейдите к следующей ячейке программы и запустите ее. Результат запроса - список лид-форм вашего рекламного кабинета со следующим набором данных:

• id формы;
• название формы;
• количество лидов.

При желании вы можете изменить результаты вывода, добавив дополнительные данные о лид-формах. Но для этого нужно скорректировать сам запрос, а также изучить официальную документацию VK.

Шаг №3. Получение лидов из форм

Запустив код в следующей ячейке, вы получите список лидов и ответ VK в виде словаря (dict):

Словарь (dict) представляет собой структуру данных (которая ещё называется ассоциативный массив), предназначенную для хранения произвольных объектов с доступом по ключу. Данные в словаре хранятся в формате ключ – значение.

Поскольку результаты в таком виде для нас не совсем подходят, то нам необходимо преобразовать их в понятный для последующей загрузки в Google Таблицы формат. Я предлагаю использовать всеми известный датафрейм (DataFrame).

DataFrame — это двумерная структура данных, которая является основным объектом библиотеки pandas в Python. Он похож на таблицу в базе данных или лист в Excel и предназначен для удобной работы с данными.

Шаг №3.1. Получение лидов из форм в DataFrame (+ корректировка даты заявки)

На этом шаге мы получим список всех лидов из всех форм рекламного кабинета VK, включая дату заявки пользователя (когда он заполнил лид-форму и отправил ее нам). Однако дата в VK отдается в формате ISO 8601 и виде:

Чтобы преобразовать дату в удобочитаемый формат (ДД-ММ-ГГГГ ЧЧ:ММ:СС), воспользуемся дополнительной библиотекой python-dateutil, которая уже входит в список предустановленных библиотек Python. Поэтому дополнительно устанавливать ее не нужно, а нужно только подключить. Как и библиотеку pandas.

При запуске этого фрагмента кода вы получите итоговый результат в виде датафрейма со всеми лидами из всех лид-форм вашего рекламного кабинета VK.

Набор данных, которые выгружаются, следующие:

• form_id – идентификатор формы;
• form_name - название формы;
• created_at – дата заявки в формате ДД-ММ-ГГГГ ЧЧ:ММ:СС;
• first_name – имя пользователя из лид-формы;
• phone – телефон пользователя из лид-формы.

Результат – данные в датафрейме, с которыми в дальнейшем вы сможете легко работать:

После того, как вы получили список лидов из ваших лид-форм, пришло время загрузить полученные данные в Google Таблицу.

Создание проекта в Google Cloud

Для того, чтобы автоматически можно было отправлять данные из лид-форм VK в Google Таблицы, нам необходимо создать проект в Google Cloud. А для этого вам нужен аккаунт Google (обычная учетная почта на Gmail). Если у вас еще нет аккаунта на Gmail.com, создайте его.

После создания аккаунта (или использования текущего) перейдите по адресу console.cloud.google.com и создайте свой первый проект в Google Cloud. Если вы впервые используете облачные службы Google, тогда вас попросят добавить страну (Country) и дать согласие с условиями предоставления услуг Google Cloud Platform. Подтвердите свои действия с помощью Agree and Continue.

Не переживайте за использование Google Cloud в России. Никаких проблем с открытием облачных решений быть не должно, создание проектов осталось возможным, а привязка банковской карты и платежных данных является необязательным условием, никакие расходы не требуются. Страну можно выбрать ближайшую или любую другую, так как Russia из списка убрали еще в 2022 году.

Платежный аккаунт для использования Google Таблиц не нужен.

В левом верхнем углу нажмите на Select A project и создайте новый проект — New Project.

Появится окно создания проекта. Задайте название вашему проекту в поле Project name (например vk-leadform, или оставьте по умолчанию) и нажмите кнопку Create:

Через несколько секунд в Google Cloud будет создан ваш новый проект, а на панели управления в правом верхнем углу отобразится соответствующее уведомление.

Сразу выберите свой проект, нажав на SELECT PROJECT.

Активация API Google Sheets и Google Drive

После создания проекта в Google Cloud выберите его из списка, чтобы он стал активен в рабочей панели.

В строке поиска сверху введите Google Drive API:

Нажмите на кнопку Enable (Включить).

Статус Enabled свидетельствует об успешной активации Google Drive API.

Проделайте тоже самое для Google Sheets API. Найдите его в поиске:

А затем активируйте его:

Получение сервисного аккаунта

Учетная запись службы (service account) — это особый тип учетной записи Google, предназначенный для представления пользователя, не являющегося человеком, которому необходимо пройти аутентификацию и авторизоваться для доступа к данным в API Google.

Чтобы создать сервисный аккаунт, перейдите в раздел API & Services — Credentials.

На открывшейся странице нажмите на Create Credentials — Service account.

В окне создания сервисного аккаунта введите имя (Service account name). Идентификатор (Service account ID) будет вписан автоматически. Например, имя сервисного аккаунта vk-leadform:

Нажмите на кнопку Create and Continue:

В открывшемся окне назначьте роль этой учетной записи, чтобы у нее было разрешение на выполнение определенных действий с ресурсами вашего проекта в Google Cloud. Например, задайте роль Owner:

Нажмите Continue:

В конце нажмите Done.

Созданный сервисный аккаунт должен отобразиться на странице Credentials.

Нажмите на ваш сервисный аккаунт, чтобы перейти в его настройки. Откройте вкладку KEYS, затем ADD KEY и Create new key.

В открывшемся окне оставьте переключатель в положении Key type — JSON и нажмите Create.

Приватный ключ в формате JSON будет создан автоматически и сразу загрузится на ваш компьютер.

Обязательно сохраните его. Он вам понадобится чуть позже в самой программе в Colab.

Вернитесь на страницу Service Accounts и скопируйте Email сервисного аккаунта:

В настройках доступа к Google Таблице, в которую вы будете загружать данные по вашим лид-формам VK, добавьте этот Email с правами доступа Редактор:

Нажмите кнопку Отправить. На этом предварительные настройки для загрузки данных в Google Таблицы завершены.

Загрузка ключа JSON на Google Диск

Когда вы будете запускать ячейки моей программы для загрузки данных в Google Таблицы, вам понадобятся данные от сервисного аккаунта Google. А для этого необходимо загрузить ваш приватный JSON ключ на Google Диск.

Это нужно сделать для того, чтобы после перезапуска среды выполнения (завершения сеанса и закрытия вкладки браузера/проекта) Google не удалял ваш файл с приватным ключом из Colab, и вам не приходилось загружать его каждый раз повторно. Для этого мы подключаемся к Диску и загружаем в него этот файл, а потом в проекте прописываем путь к этому файлу.

Сделать это очень просто. Перейдите в Google Drive по ссылке drive.google.com и загрузите в него ваш приватный ключ:

Приватный ключ вы получили на предыдущем шаге, он сохранился у вас на компьютере. Перед загрузкой обязательно проверьте, чтобы в имени файла не было никаких пробелов. Если они присутствуют, замените их на нижнее подчеркивание _ или тире –

Шаг №4. Подключение к Google Диск

Вернитесь в программу Colab и перейдите на шаг №4. Подключаемые в ячейке модули позволяют работать с Google Диском, а также импортировать ваши файлы из Google Drive в проект Colab, чтобы потом к ним можно было обращаться в программе.

Поскольку на предыдущем шаге вы загрузили свой приватный JSON ключ на Google Диск, просто запустите ячейку программы. Вам откроется новое окно, в котором Google попросит вам подключиться к Диску. Сделайте это:

Выбрав свою учетную запись Gmail, предоставьте приложению Google Drive все необходимые разрешения:

В завершение нажмите кнопку Разрешить. После этого код успешно будет выполнен, все всплывающие окна закроются, а в вашем проекте в Colab, если вы нажмете на иконку папки в левом углу страницы, отобразиться папка drive, в которой будут размещены все файлы с вашего Диска, в том числе и загруженный ранее приватный ключ:

Найдите в списке ваш приватный ключ и нажмите на него правой кнопкой мыши. Выберите пункт Скопировать путь:

Вставьте этот путь в ячейку # Шаг №5. Запись данных о лидах в Google Таблицу в переменную SERVICE_ACCOUNT_FILE. Путь должен быть вида '/content/drive/MyDrive/ваш_приватный_ключ.json'

Теперь вы сможете запускать программу каждый раз без каких-либо проблем и не переживать за отсутствие ключа в случае ее перезапуска. Ключ всегда будет подключен к программе и работать.

Шаг №5. Загрузка лидов в Google Таблицу

Последний шаг – это загрузить список лидов из лид-форм VK в Google Таблицу. Перед запуском ячейки обязательно укажите в переменной SPREADSHEET_ID идентификатор вашей таблицы и в переменную RANGE_NAME название листа (или диапазон), на который нужно будет поместить все данные.

Идентификатор Google Таблицы отображается в адресной строке браузера самой таблицы:

А название листа – это название вкладки Google Таблицы:

Поскольку в этой программе продемонстрирована выгрузка данных по идентификатору формы, названию формы, дате создания заявки, имени пользователя и его телефону, то и в последней ячейке загрузки присутствуют именно эти заголовки колонок. При желании вы можете изменить результаты вывода, добавив дополнительные данные о лид-формах. Но для этого нужно скорректировать сам запрос.

Все, что осталось сделать – это запустить последний фрагмент программы. Если вы все сделали правильно, то под ячейкой должны увидеть результат обновления ячеек с данными:

А в самой Google Таблице – список лидов из всех лид-форм с заданным набором данных:

По сути, на этом все! Так как мы работаем в браузере, используя Colab, то и выгрузка данных в Google Sheets выполняется в полуавтоматическом режиме, через прокликивание соответствующих ячеек. Просто заходите раз в день (например, с утра) и запускайте эту программу, обновляя список лидов за предыдущий день. Пропускайте первый шаг с получением токена и переходите сразу к # Шаг №2. Получение списка лид-форм, иначе токен доступа будет постоянно перевыпускаться, и вы скоро упретесь в лимит и ошибку.

К старым данным всегда будут добавляться новые, актуальные сведения. А если быть точнее, то код программы просто удаляет все данные о лидах и на их место загружает обновленный список.

Если у вас множество разных рекламных кабинетов, то данное решение очень удобно и полезно, поскольку позволяет увидеть всю картину по количество обращений целиком, из всех лид-форм и рекламных кабинетов.

Как загружать данные по лидам из лид-форм из нескольких рекламных кабинетов?

Я могу предложить вам два варианта:

1. использовать для каждого рекламного кабинета свою программу. То есть 1 рекламный кабинет = 1 программа Colab со своей ссылкой. Тогда вы не запутаетесь во множестве ячеек -> в каждой программе будут данные только от одного кабинета VK Рекламы. Вы просто добавите client_secret и client_id и будете следовать одной и той же инструкции. А загрузку данных будете осуществлять в одну Google Таблицу, но просто на разные листы. 1 лист – 1 рекламный кабинет. А потом все лиды можно будет свести в одну таблицу (на одном листе) с помощью функций и формул Google Таблиц. Например, используя ВПР.
2. использовать одну программу Colab для всех рекламных кабинетов, просто копируя ячейки программы для каждого рекламного кабинета VK ниже (друг под другом), а также изменяя данные client_secret и client_id. При такой реализации нужно быть очень аккуратным, так как велика вероятность неверного сценария выполнения программы. Например, когда запуск программы для одного рекламного кабинета будет перезаписывать данные для другого рекламного кабинета. Этот вариант для более продвинутых пользователей, кто ориентируется в коде и не боится вносить корректировки.

Как выгрузить список лидов с другим набором полей, например, с email?

Все зависит от ваших лид-форм и какой набор полей вы используете в рекламе. Эту инструкцию я создавала на основе своего проекта, поэтому выгружала название формы, дату заявки, имя и телефон. Но у вас могут быть и другие поля, которые вы захотите передать. В этом случае вы можете изменить в основных шагах программы сам запрос, ориентируясь на официальную документацию VK:

• https://ads.vk.com/doc/api/resource/LeadForms
• https://ads.vk.com/doc/api/object/LeadForm