Различия

Показаны различия между двумя версиями страницы.

--- product:api:integration_examples:google_sheets [07.04.2025 08:59] – ekaterina.menkhuzina
+++ product:api:integration_examples:google_sheets [08.04.2025 10:27] (текущий) – ekaterina.menkhuzina
@@ Строка 2: / Строка 2: @@
 Google предоставляет множество сервисов для совместной работы с документами распространённых офисных форматов. В их числе - **Google Sheets**, облачный редактор электронных таблиц, аналогичный Excel.
-В некоторых ситуациях требуется переносить данные о проектах, сформированных в ADVANTA, в таблицы Google Sheets.
+Если требуется регулярно передавать данные о проектах в таблицы Google, можно автоматизировать этот процесс. Для этого надо написать приложение, которое будет получать данные из ADVANTA через ее API и записывать их в электронную таблицу через API системы Google Sheets.
-Если передавать данные требуется регулярно, можно автоматизировать этот процесс. Для этого можно написать приложение, которое будет получать данные из ADVANTA через ее API и записывать их в электронную таблицу через API системы Google Sheets.
 Шаги, которые надо выполнить для автоматизации передачи информации из ADVANTA в таблицы Google Sheets:
-  - Зарегистрировать «сервисный аккаунт» в системе «Google Cloud Console» для вызова к API.
+  - Зарегистрировать «сервисный аккаунт» в системе «Google Cloud Console» для вызова API и получить «ключ доступа» к нему.
   - Настроить доступ к файлу электронной таблицы в Google Sheets для связанной с «сервисным аккаунтом» учётной записи.
+  - Настроить в ADVANTA LINQ-запрос, который сформирует таблицу данных.
+  - Написать приложение, которое выполнит LINQ-запрос и запишет полученные данные в Google Sheets.
-Также ниже рассмотрены примеры двух максимально простых приложений на C#, которые получают данные из ADVANTA и записывают их в таблицы Google. На основе этих примеров Вы можете создавать собственные приложения для решения задач по автоматизации передачи данных из ADVANTA в облачные сервисы Google.
+Ниже рассмотрены примеры двух максимально простых приложений на C#, которые получают данные из ADVANTA и записывают их в таблицы Google. На основе этих примеров Вы можете создавать собственные приложения для решения задач по автоматизации передачи данных из ADVANTA в облачные сервисы Google.
+<image shape="thumbnail">{{ :product:api:integration_examples:a2-googlesheets-16200-630.jpg?700&direct |}}</image>
 ===== Общие сведения об API сервисов Google =====
@@ Строка 34: / Строка 36: @@
 ==== Подключение к «проекту» библиотеки 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 |}}
+<callout type="warning" icon="true">В реальных проектах важно обеспечить ограниченный доступ к файлу ключа и по возможности шифровать. Если ключ попадёт в поисковые системы, Google автоматически заблокирует его.</callout>
+===== Настройка доступа в 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-таблицу.
+<callout type="primary" icon="true">Чтобы открыть и запустить эти примеры, на ПК должен быть установлен [[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».</callout>
+==== Подготовка LINQ-запроса в ADVANTA ====
+Для выгрузки списка объектов воспользуемся [[product:linq:about|LINQ-запросом]] «Все объекты» (ключ «GetAllObjects»).
+<code csharp>
+var projects = dataContext.Projects
+      .Where(p => p.Name != null)
+      .OrderBy(p => p.CreationDate)
+      .Select(p => new {
+        	p.Id,
+        	p.Name,
+        	//p.Code,
+        });
+return projects;
+</code>
+Необходимо убедиться, что запрос работает. Для этого, заходим в раздел [[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 в коде:
+. Адрес сервера ADVANTA, логин и пароль пользователя, от имени которого будет выполняться LINQ-запрос:
+{{ :product:api:integration_examples:gcc20.png?500 |}}
+. Имя ключа LINQ-запроса и количество объектов, которые программа из него получит. Большое количество объектов может потребовать большого объёма оперативной памяти компьютера, на котором выполняется программа:
+{{ :product:api:integration_examples:gcc21.png?500 |}}
+. Далее нужно заменить в каталоге с кодом файл "service-account.json" на тот, который сгенерировали при настройке сервисного аккаунта в [[https://console.cloud.google.com|Google Cloud Console]]. При необходимости, можно разместить в каталоге с кодом несколько файлов авторизации и указать имя нужного в коде:
+{{ :product:api:integration_examples:gcc22.png?500 |}}
+Также нужно зарегистрировать дополнительный ''JSON'' в файле проекта «ExportToGoogleSheets1Lib.csproj», добавив в него код с новым именем файла, аналогично существующему:
+<code csharp>
+<ItemGroup>
+    <None Update="service-account.json">
+        <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+</code>
+{{ :product:api:integration_examples:gcc23.png |}}
+. Далее указать идентификатор 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 настраивается точно также.
+<callout type="info" icon="true">Если потребуется проводить собственные эксперименты с примерами в [[https://code.visualstudio.com|Visual Studio Code]], рекомендуется создать новый проект, скопировать в него код из примера и подключить библиотеки Google. </callout>