18.02.2021 08:43
iTrack 1 1300 Источник

Практический кейс о том, как разработать свой сценарий интеграции

Появившиеся в 2006 году сервисы Google по работе с текстовыми документами (Google Docs) и таблицами (Google Sheets), дополненные 6 лет спустя возможностями работы с виртуальным диском (Google Drive), завоевали широкую любовь пользователей, лишив компанию Microsoft сложившейся десятилетиями монополии на работу с офисным программным обеспечением.

Вспоминается, как один консультант, занимавшийся внедрением дорогостоящих систем бюджетирования, искренне радовался появлению бесплатной электронной Google-таблицы, в которую можно поместить требуемую бюджетную модель и дать к ней доступ всем, кому нужно. Совместная работа над текстом в Интернете тоже стала повсеместной практикой с появлением Google-сервисов.

В связи с популярностью последних часто возникает задача сделать новый или обновить существующий Google-файл в привязке к событиям в CRM-системе. Например, при переходе сделки на этап «Составление коммерческого предложения» необходимо, взяв из CRM-системы наименование клиента и сумму сделки, создать на Google Drive предварительный текст коммерческого предложения, дать к нему доступ юристу, отправив ссылку на редактирование контракта. А когда сделка будет успешно закрыта, может появиться другая задача внести данные по закрытой сделке в Google-таблицу сбора статистики продаж.

В базовом функционале CRM-систем интеграция с сервисами Google представлена лишь в Битрикс24 и предполагает создание пустого документа на базе диска с переходом в режим редактирования при последующем клике на него.

Конечно, в маркетплейс Битрикс24 или дополнениях amoCRM можно найти определенный набор решений для закрытия тех или иных более глубоких сценариев интеграции. Но как быть, если необходимо разработать свой сценарий?

Для того, чтобы выполнить какое-то действие на Google – диске своего аккаунта есть два подхода: вызвать соответствующий REST API метод или запустить написанный Google Script. Как показал наш опыт, REST API библиотека Google пока имеет гораздо более бедный набор возможностей по отношению к скриптам, например, с помощью метода create можно создать исключительно пустой документ без наполнения. Поэтому, универсальным является сейчас комбинированный подход, заключающийся в написании исполняемого скрипта, который будет вызываться извне с помощью API с определенным набором параметров.

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

Шаг 1. Создание скрипта

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

Сам script добавляется на диске точно также как мы добавляем обычный файл на него.

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

Шаг 2. Привязка скрипта к проекту Google Cloud Platform

После того как скрипт написан рекомендуем прогнать его, нажав кнопку «Выполнить» в редакторе. Далее вам необходимо создать проект на Google Cloud Platform. Наиболее простым вариантом для этого является нажатие кнопки Enable Google Script API по ссылке: https://developers.google.com/apps-script/api/quickstart/php.

Пройдя все шаги мастера создания API, вы скачиваете файл credentials.json, который будет нужен для работы обработчика. После этого вы берете номер проекта и привязываете его к скрипту в настройках.

Шаг 3. Публикация скрипта

Чтобы скрипт был доступен извне, его надо развернуть через кнопку начать развертывание.

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

Шаг 4. Написание PHP-обработчика

Для работы с API Google существует готовая библиотека, которую вы подключаете к своему проекту командой: composer require google/apiclient:^2.0  

В файле с подключенной библиотекой вызываете функцию для подключения токена авторизации:

function getClient()
{
    $client = new Google_Client();
    $client->setApplicationName('Google Apps Script API PHP Quickstart');
    // перечисляем области действия токена через пробел
    $client->setScopes("https://www.googleapis.com/auth/documents https://www.googleapis.com/auth/drive");
    // файл credential.json, полученный от Google
$client->setAuthConfig('credentials.json');
    $client->setAccessType('offline');
    $client->setPrompt('select_account consent');

    // Формируемый файл token.json
    $tokenPath = 'token.json';
    if (file_exists($tokenPath)) {
        $accessToken = json_decode(file_get_contents($tokenPath), true);
        $client->setAccessToken($accessToken);
    }

    // Действие если токен просрочен
    if ($client->isAccessTokenExpired()) {
        if ($client->getRefreshToken()) {
            $client->fetchAccessTokenWithRefreshToken($client->getRefreshToken());
        } else {
            $authUrl = $client->createAuthUrl();
            printf("Open the following link in your browser:\n%s\n", $authUrl);
            print 'Enter verification code: ';
            $authCode = trim(fgets(STDIN));

            $accessToken = $client->fetchAccessTokenWithAuthCode($authCode);
            print_r($accessToken);
            $client->setAccessToken($accessToken);
            
            if (array_key_exists('error', $accessToken)) {
                throw new Exception(join(', ', $accessToken));
            }
        }

        // Сохранение токена в файл
        if (!file_exists(dirname($tokenPath))) {
            mkdir(dirname($tokenPath), 0700, true);
        }
        file_put_contents($tokenPath, json_encode($client->getAccessToken()));
    }
    return $client;
}

Файл с этой функцией должен быть изначально исполнен в командной строке ssh – клиента “php (имя файла)”.

При первом запуске на экране появится url, который вы открываете в своем браузере и дав необходимые разрешения копируете verification code из url ресурса приложения, который вы указали на шаге 1, вставляя его в командную строку. После этого система создает файл токена авторизации (token.json), сохраняя его в папке PHP-обработчика. Следует отметить, что данную операцию надо выполнить один раз.

С готовым файлом токена, исполняется вторая часть функции, предполагающая запуск самого скрипта. 

// вызов ранее описанной функции для получения токена авторизации
$client = getClient();
$service = new Google_Service_Script($client);

// код развернутого скрипта
$scriptId = '***********************wKhTTdKL7ChremS5AkvzwlPJARnxqisW7TzDB ';

$request = new Google_Service_Script_ExecutionRequest();
// имя и параметры функции в рамках скрипта
$request->setFunction('FillTemplate');
$request->setParameters([$_REQUEST['customer'],$_REQUEST['link'],$_REQUEST['formsv'],$_REQUEST['socnet'],$_REQUEST['whatsi'],   $_REQUEST['ats'],$_REQUEST['pipeline'],$_REQUEST['outscope'],$_REQUEST['editor'],$_REQUEST['viewer']]);

try {
    // Make the API request.
    $response = $service->scripts->run($scriptId, $request);
    if ($response->getError()) {
        // Обработчик ошибок

        $error = $response->getError()['details'][0];
        printf("Script error message: %s\n", $error['errorMessage']);

        if (array_key_exists('scriptStackTraceElements', $error)) {
            print "Script error stacktrace:\n";
            foreach($error['scriptStackTraceElements'] as $trace) {
                printf("\t%s: %d\n", $trace['function'], $trace['lineNumber']);
            }
        }
    }     
} catch (Exception $e) {
    // Обработчик исключения
    echo 'Caught exception: ', $e->getMessage(), "\n";
}

Шаг 5. Вызов PHP-обработчика из CRM

Имея протестированный обработчик, можно запустить его в привязке к событиям CRM.

Базовым вариантом запуска является вызов исходящего вебхука в привязке к событию CRM и данному обработчику, см. cтатьи про настройки вебхуков в:

При этом, в Битрикс24 вебхук может быть встроен в бизнес-процесс, получая в качестве своих Get-параметров данные из сделки, переменных и констант бизнес-процесса.

Итогом работы данного вебхука стали добавляемые документы в соответствующую папку Google Drive:

Существенным ограничением запусков обработчиков через вебхуки является предельно допустимая длина URL, в которой будут передаваться Get-параметры. Напомним, что она составляет 4 кб (или 2048 символов).

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