====== Экспорт данных из ADVANTA в Google-таблицы ====== Google предоставляет множество сервисов для совместной работы с документами распространённых офисных форматов. В их числе - **Google Sheets**, облачный редактор электронных таблиц, аналогичный Excel. В некоторых ситуациях требуется переносить данные о проектах, сформированных в ADVANTA, в таблицы Google Sheets. Если передавать данные требуется регулярно, можно автоматизировать этот процесс. Для этого можно написать приложение, которое будет получать данные из ADVANTA через ее API и записывать их в электронную таблицу через API системы Google Sheets. Шаги, которые надо выполнить для автоматизации передачи информации из ADVANTA в таблицы Google Sheets: - Зарегистрировать «сервисный аккаунт» в системе «Google Cloud Console» для вызова к API. - Настроить доступ к файлу электронной таблицы в Google Sheets для связанной с «сервисным аккаунтом» учётной записи. Также ниже рассмотрены примеры двух максимально простых приложений на C#, которые получают данные из ADVANTA и записывают их в таблицы Google. На основе этих примеров Вы можете создавать собственные приложения для решения задач по автоматизации передачи данных из ADVANTA в облачные сервисы Google. ===== Общие сведения об API сервисов Google ===== Доступ к API-функциям облачных сервисов Google настраивается в системе [[https://console.cloud.google.com|Google Cloud Console]] - это веб-сервис для разработчиков и системных администраторов организаций. Требуется создать в [[https://console.cloud.google.com|Google Cloud Console]] «проект» и подключить в него библиотеки API нужных сервисов Google. При вызове API программа должна проходить авторизацию в «проекте». Есть несколько способов её организовать в зависимости от того, каким именно образом программа будет использоваться: - Если предполагается создание приложения с визуальным интерфейсом, в котором пользователи будут работать через персональные учётные записи Google, следует настроить доступ к «проекту» через протокол **OAuth**. При вызове API из такого приложения, будет открываться веб-страница авторизации Google, где пользователь должен ввести свои логин и пароль вручную. - Для приложений, работающих в автоматическом режиме, требуется создать специальную учётную запись Google – **«сервисный аккаунт»**. Ключ доступа к такой учётной записи экспортируется в файл и включается в код программы. Непосредственный вызов API Google может быть выполнен либо с помощью библиотек, либо напрямую, через REST API. В первом случае код намного проще, но библиотеки надо устанавливать в проект в среде разработки. ===== Получение доступа к API через Google Cloud Console ===== Для вызова API-функций Google-таблиц требуется выполнить шаги: - Создать в сервисе [[https://console.cloud.google.com|Google Cloud Console]] новый проект. - Подключить к этому проекту библиотеку API-функций «Google Sheets». - Создать сервисный аккаунт – специальную учётную запись, которую можно использовать лишь для идентификации приложений. - Создать ключ доступа к сервисному аккаунту - файл формата ''JSON'', который содержит данные для автоматической авторизации приложения. ==== Создание «проекта» в Google Cloud Console ==== Перейти на сайт [[https://console.cloud.google.com|Google Cloud Console]]. При первом входе система автоматически создаст новый «проект» с названием «My First Project». {{ :product:api:integration_examples:gcc1.png?500 |}} ==== Подключение к «проекту» библиотеки API Google Sheets ==== Для подключения к созданному проекту библиотеки API-функций Google Sheets необходимо перейти в раздел «APIs & Services» по кнопке под названием проекта. {{ :product:api:integration_examples:gcc2.png?500 |}} Затем необходимо открыть список библиотек кнопкой «Enable APIs and services». {{ :product:api:integration_examples:gcc3.png?500 |}} В поле поиска ввести «Sheets», нажать **Enter** и выбрать найденную библиотеку «Google Sheets API». Включить библиотеку кнопкой **Enable**. {{ :product:api:integration_examples:gcc4.png?500 |}} Библиотека появится в проекте, на странице «Enabled APIs & services». {{ :product:api:integration_examples:gcc5.png?500 |}} ==== Создание сервисного аккаунта Google для доступа к API «проекта» ==== Для создания сервисного аккаунта Google необходимо в разделе «Credentials» вызвать меню «Create credentials > Service account». {{ :product:api:integration_examples:gcc6.png?600 |}} Далее на странице «Create service account» ввести название аккаунта в поле «Service account name» и описание в поле «Service account description». Система автоматически заполнит поле «Service account ID». Для продолжения настройки нажать «Create and continue». {{ :product:api:integration_examples:gcc7.png?600 |}} На странице «Grant this service account access to project» в выпадающем списке «Role» выбрать роль «Basic / Editor». {{ :product:api:integration_examples:gcc8.png?600 |}} Для перехода к следующему шагу нажать **Continue**. В разделе «Grant users access to this service account» ничего вводить не нужно. Нажать **Done**, чтобы завершить создание сервисного аккаунта. Сервисный аккаунт будет создан и появится в поле «Service account». Адрес электронной почты этого сервисного аккаунта нужно будет указать далее при настройке доступа к Google-таблице. ==== Создание ключа доступа к сервисному аккаунту ==== Теперь нужно создать ключ для доступа к сервисному аккаунту из программы, которую будем разрабатывать. Перейти по ссылке с именем аккаунта а разделе «Service Accounts»: {{ :product:api:integration_examples:gcc9.png?600 |}} На странице настроек аккаунта нужно перейти на вкладку «Keys» и вызвать команду создания нового ключа через меню «Add key / Create new key». {{ :product:api:integration_examples:gcc10.png?600 |}} По запросу о типа ключа выбрать ''JSON'' и нажать **Create**. Появится сообщение, что ключ сохранён на компьютере и одновременно с этим начнётся скачивание файла. Полученный файл нужно сохранить на диске и изменить его название на «service-account.json». Далее он потребуется при создании кода приложения. Пример структуры файла «service-account.json»: {{ :product:api:integration_examples:gcc12.png?700 |}} В реальных проектах важно обеспечить ограниченный доступ к файлу ключа и по возможности шифровать. Если ключ попадёт в поисковые системы, Google автоматически заблокирует его. ===== Настройка доступа в Google-таблице ===== В Google-таблице, в которую приложение будет записывать данные, надо дать доступ на редактирование сервисной учётной записи. Диалог настройки вызывается кнопкой «Доступ» справа на панели инструментов. {{ :product:api:integration_examples:gcc13.png?600 |}} В поле email-адреса необходимо ввести адрес почты сервисной учётной записи. Его можно найти в JSON-файле с данными авторизации, который был сохранен ранее. Он записан в элементе ''client_email''. {{ :product:api:integration_examples:gcc14.png |}} Система предложит указать уровень доступа – нужно выбрать «Редактор». Опцию «Уведомить пользователей» можно отключить и нажать «Открыть доступ». {{ :product:api:integration_examples:gcc15.png?500 |}} После сохранения настроек доступа, адрес сервисного аккаунта появится в списке пользователей таблицы, с выбранным уровнем доступа. ===== Примеры программного кода ===== ==== Общие сведения о примерах ==== К инструкции прилагаются два примера кода, созданные в [[https://code.visualstudio.com|Visual Studio Code]]: * {{ :product:api:integration_examples:exporttogooglesheets1libs.zip |}} - демонстрирует выгрузку данных из ADVANTA в Google-таблицу с помощью библиотек Google, которые загружены в проект через NuGet. Библиотеки удобно использовать, если есть полный доступ к среде разработки, как например, при создании самостоятельного веб-сервиса: * {{ :product:api:integration_examples:exporttogooglesheets2nolibs.zip |}} - вариант экспорта данных без использования библиотек Google. Он значительно более сложный, но такой вариант можно использовать, например, в модуле триггеров, где нельзя подключить сторонние библиотеки. Общий алгоритм работы примеров кода одинаков: - Проверяется доступ к Google-таблице, с помощью данных авторизации, настроенный в «Google Cloud Console» и сохранённых в файл. - Проводится авторизация в ADVANTA. - Выполняется запрос списка объектов с помощью заранее настроенного в ADVANTA [[product:linq:about|LINQ-запроса]]. - Выполняется очистка Google-таблицы от всех данных. - Список объектов записывается в Google-таблицу. Чтобы открыть и запустить эти примеры, на ПК должен быть установлен [[https://dotnet.microsoft.com/ru-ru/download/dotnet/8.0|DotNet SDK 8]] и сама среда разработки [[https://code.visualstudio.com|Visual Studio Code]]. Для работы с C# в [[https://code.visualstudio.com|Visual Studio Code]] надо добавить расширение «C# Dev Kit». Для выгрузки данных из ADVANTA должен быть настроен LINQ-запрос. ==== Подготовка LINQ-запроса в ADVANTA ==== Для выгрузки списка объектов воспользуемся [[product:linq:about|LINQ-запросом]] «Все объекты» (ключ «GetAllObjects»). var projects = dataContext.Projects .Where(p => p.Name != null) .OrderBy(p => p.CreationDate) .Select(p => new { p.Id, p.Name, //p.Code, }); return projects; Необходимо убедиться, что запрос работает. Для этого, заходим в раздел [[product:linq:about|LINQ-запросов]] Системы и проверяем, что запрос существует. {{ :product:api:integration_examples:gcc16.png?500 |}} Далее необходимо перейти на страницу запроса кликом по названию, выполнить его кнопкой «Сделать запрос» и убедиться, что он формирует таблицу с перечнем объектов. {{ :product:api:integration_examples:gcc17.png |}} ==== Как запустить примеры кода ==== === Подготовка каталога для примеров === С помощью Проводника Windows необходимо создать на диске каталог ''C:\Projects'' и скопировать в него каталоги проектов из прилагаемых архивов {{ :product:api:integration_examples:exporttogooglesheets1libs.zip |ExportToGoogleSheet1Libs.zip}} и {{ :product:api:integration_examples:exporttogooglesheets2nolibs.zip |ExportToGoogleSheet2NoLibs.zip}}. В итоге, в каталоге «Projects» должны располагаться подкаталоги с программными файлами. {{ :product:api:integration_examples:gcc18.png?600 |}} === Запуск примера «ExportToGoogleSheet1Libs» (с библиотеками Google) === Необходимо запустить [[https://code.visualstudio.com|Visual Studio Code]] и выполнить команду «File > Open Folder…». В окне «Open Folder» перейти в каталог ''C:\Projects\ExportToGoogleSheet1Libs'' и нажать «Выбор папки». Содержащийся в каталоге код откроется в [[https://code.visualstudio.com|Visual Studio Code]]: {{ :product:api:integration_examples:gcc19.png |}} Прежде, чем запускать его на исполнение, необходимо проверить настройки параметров подключения к ADVANTA и к Google в коде: 1. Адрес сервера ADVANTA, логин и пароль пользователя, от имени которого будет выполняться LINQ-запрос: {{ :product:api:integration_examples:gcc20.png?500 |}} 2. Имя ключа LINQ-запроса и количество объектов, которые программа из него получит. Большое количество объектов может потребовать большого объёма оперативной памяти компьютера, на котором выполняется программа: {{ :product:api:integration_examples:gcc21.png?500 |}} 3. Далее нужно заменить в каталоге с кодом файл "service-account.json" на тот, который сгенерировали при настройке сервисного аккаунта в [[https://console.cloud.google.com|Google Cloud Console]]. При необходимости, можно разместить в каталоге с кодом несколько файлов авторизации и указать имя нужного в коде: {{ :product:api:integration_examples:gcc22.png?500 |}} Также нужно зарегистрировать дополнительный ''JSON'' в файле проекта «ExportToGoogleSheets1Lib.csproj», добавив в него код с новым именем файла, аналогично существующему: Always {{ :product:api:integration_examples:gcc23.png |}} 4. Далее указать идентификатор Google-таблицы, к которой дали доступ для сервисного аккаунта, а также имя листа в ней, на который требуется выгрузить данные: {{ :product:api:integration_examples:gcc24.png |}} **Идентификатор** - часть адреса страницы с таблицей, между ''/d/'' и ''/edit'', а имя листа – аналогично Excel: {{ :product:api:integration_examples:gcc25.png?600 |}} Перед запуском примера необходимо обязательно сохранить изменения. После этого можно запускать решение. Для запуска служат команды справа на панели закладок [[https://code.visualstudio.com|Visual Studio Code]]. Работа с примером {{ :product:api:integration_examples:exporttogooglesheets2nolibs.zip |}} полностью аналогична. Доступ к ADVANTA и Google настраивается точно также. Если потребуется проводить собственные эксперименты с примерами в [[https://code.visualstudio.com|Visual Studio Code]], рекомендуется создать новый проект, скопировать в него код из примера и подключить библиотеки Google.