Библиотека для работы с Megaplan API.

Быстрый старт

В данном руководстве будет описан MegaplanDataStore. Это общий класс для работы со всеми сущностями Мегаплана. Но в силу того, что набор сущностей реализован не полностью, в тексте будут уточняться некоторые моменты именно с точки зрения работы со сделками Мегаплана.

Установка

С помощью команды composer lib install запустите инсталлер библиотеки: MegaplanInstaller. По ходу установки инсталлер будет задавать вопросы по устанавливаемым значениям. Наиболее важным значением при работе со сделаками является параметр Program - id схемы сделок. Если его не указать или указать неправильно, то могут возникнуть проблемы с доступом и отсутвием настраиваемых параметров (об этом ниже).

В папке config/autoload должен появиться файл rollun.api.Api.Megaplan.Megaplan.dist.local.php. В нем окажутся только те параметры, которые требуют обязательной ручной (до)настройки в определенном серверном окружении. Остальные параметры, которые имеют жесткие неизменяемые значения, останутся в ConfigProvider'е расширения. Формально, Вы можете переопределить и их, но делать это строго НЕ рекомендуется.

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

Разделы конфигурации

Обращаем Ваше внимание, что все настройки библиотеки разделены на две части:

• обзятельные и (условно) неизменямые настройки находятся в файле ConfigProvider.
• параметры, которые требуют ручной донастройки, находятся в файле rollun.api.Api.Megaplan.Megaplan.dist.local.php.

Итак, список разделов конфигурации:

1. megaplan. Настройка доступа к серверу Мегаплана. Здесь нужно ввести название Мегаплана, логин и пароль доступа.
2. megaplan_entities. Здесь заполняются сервисы-обертки для доступа к API Мегаплана. Каждый сервис содержит 4 обязательных параметра:

• entity. Какой тип сущностей нужно будет получить при запросе к Мегаплану. Заполнять нужно по имени класса сущности (доступные сущности можно посмотреть в папке rollun-api/src/Api/src/Api/Megaplan/Entity).
• dataStore. Сервис, который описывает, в какой именно тип dataStore будет записываться результат.
• serializer. Данные от Мегаплана приходят в специальном формате. Данный сериалайзер призван выполнить рутинные действия по извлечению этих данных из этой структуры и подготовке их к записи в dataStore.
• serializerOptions. Настройки для сериалайзера.

Два последних параметра ссылаются на одноименные псевдонимы (секция aliases).

3. dataStore. Собственно, раздел, где описываются сервисы dataStore для их дальнейшего использования. Нужно раличать этот раздел с одноименным разделом из секции megaplan_entities.

Использование класс для работы со сделками.

// some_entity_service - это сервис, описанный в файле конфигурации (см.выше)
$megaplanClient = $container->get('some_entity_service');

// $result получить список сделок по указнной в конфигруации схеме
$result = $megaplanClient->get();
//...
// Получить карточку сделки по ее Id
$result = $megaplanClient->get(<Id сделки>);

Специфика архитектуры Мегаплана по работе со сделками не позволяет работать одинаково со списком сделок и с одной сделкой (карточкой сделки). В связи с этим класс DataStore содержит две ссылки на разные сущности: список (dealsEntity) и карточка (dealEntity).

Кроме того, обязательным параметром для работы со сделками является Id схемы сделок. Дело в том, что Мегаплан позволяет добавить неограниченное число параметров к сделке. Но все они привязаные к какой-то конкртеной схеме. Т.е. один набор дополнительных параметров привязан к одной схеме, другой - к другой и т.д.

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

Поэтому обе сущности - и карточка сделки, и список сделок - перед непосредственным получением данных, запрашивают у Мегаплана список дополнительных полей по указанной в конфигурации схеме (параметр Program). Затем эти поля передаются в секции ExtraFields, чтобы они оказались в списке. Для этого используется сущность \rollun\api\Api\Megaplan\Entity\Deal\Fields.

Serializer

Как было сказано выше, данные от Мегаплана приходят в специальном формате (на примере Сделок):

Array
(
    [status] => Array
        (
            [code] => ok
            [message] =>
        )
    [data] => Array
        (
            [deals] => Array
                (
                    [0] => Array
                        (
                            // Deal data
                        )
                    [1] => Array
                        (
                            // Deal data
                        )
                    // ...
                    [N] => Array
                        (
                            // Deal data
                        )
                )
        )
)

Кроме того, весь этот массив приходит в виде JSON-строки. Задачи сериалайзера развернуть этот массив, затем извлечь сами Сделки (['data']['deals']), а затем подготовить эти данные к записи в dataStore.

По умолчанию используется класс сериализатора \rollun\api\Api\Megaplan\Serializer\Megaplan и класс его настроек \rollun\api\Api\Megaplan\Serializer\MegaplanOptions. Класс сериализатора реализует интерфейс \Zend\Serializer\Adapter\AdapterInterface; при желании можно не писать этот класс с нуля, а отнаследоваться от класса \Zend\Serializer\Adapter\AbstractAdapter.

Сериализатор \rollun\api\Api\Megaplan\Serializer\Megaplan требует обязательного наличия класса настроек. Такой класс должен обязательно реализовавыть интерфейс \rollun\api\Api\Megaplan\Serializer\MegaplanOptionsInterface. Это необходимо, чтобы передавать в сериализатор тип сущности Мегаплана, с которым он (сериализатор) будет работать. Как и в случае с основным классом, можно не писать класс настроек с нуля, а отнаследоваться от класса \rollun\api\Api\Megaplan\Serializer\MegaplanOptions.

Фабрика для клиента Мегаплана

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

Поэтому для оригинального клиента Мегаплана была создана наша собственная фабрика, которая вычитывает конфиг, создает объект MegaplanClient и авторизует его на сервере Мегаплана. Такой подход позволяет использовать клиент с разными настройками доступа и передавать его в виде зависимости в другие классы/фабрики.

Класс фабрики: \rollun\api\Api\Megaplan\Entity\Factory\MegaplanClientFactory.

Сущности Мегаплана

Как все работает

Весь API Мегаплана построен на работе вокруг сущностей (Сделки, Заказы, Задачи и тд). При запросе к серверу нужно указать нужный URI для получения той или иной сущности - каждую сущность обслуживает отдельный URI.

В нашей библиотеке базовой сущностью для всех является абстрактный класс \rollun\api\Api\Megaplan\Entity\EntityAbstract. По сути, она делает всю работу. В классе содержится набор констант, которые должен переопределять класс-наследник:

• URI_ENTITY_GET; URI, который обслуживает данную сущность.
• ENTITY_LIST_KEY; ключ массива в ответе с сервера, где будут содержаться запрошенные данные.
• MAX_LIMIT; максимальный лимит получаемых данных. Чисто технический параметр. Дело в том, что сам Мегаплан НЕ отпускает более 100 строк ответа за один запрос. Если сущностей ожидается больше, то нужно выполнять смещение с помощью параметра запроса 'Offset'. Здесь эта константа не требует переопределения (хотя и может быть переопределена). Она нужна для правильной работы цикла выборки с нашей стороны. Переопределение ее в бОльшую сторону не имеет смысла и приведет к ошибке во время выполнения запроса.
• REQUESTED_FIELDS; требуемые поля (см. справку Мегаплана). Если не указать это значение или указать ему пустой массив, то этот ключ игнорируется.
• EXTRA_FIELDS; дополнительные поля (см. справку Мегаплана). Если не указать это значение или указать ему пустой массив, то этот ключ игнорируется.

Кроме конструктора, класс предоставляет всего один публичный метод - get(). Он не получает параметров - все параметры обозначены в вышеупомянутых константах. В этом методе производится выборка данных и их развертывание.

Списочные классы (не все) могут также предоставлять публичный метод query($condition), который позволяет выбрать сущности Мегаплана по указанным критериям. К сожалению, механизм выборки в самом API Мегаплана оставляет желать лучшего. Поэтому данный метод используется не часто и в очень ограниченной конфигурации.

Как создать новую сущность?

Для этого достаточно отнаследоваться от базового класса сущностей \rollun\api\Api\Megaplan\Entity\EntityAbstract и переопределить вышеуказанные константы на реальные значения.

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

Быстрый старт. Итог

Чтобы начать работу с API сделок Мегаплана, нужно после установки и настройки просто поднять megaplanDataStore из контейнера и просто начать его использовать:

$megaplanDataStore = $container->get("megaplan_deal_dataStore_service");

Псевдоним megaplan_deal_dataStore_service предопределен в ConfigProvider'е. Если Вы ничего не переопределяли в локальной версии конфигурации, то сервис нормально создастся.

Чтение сделки из Мегаплана:

$deal = $megaplanDatStore->read(123);

Создание сделки. Обращаю внимание, что данные непосредственно сделки должны быть обернуты в ключ "Model" набора данных:

$itemData = [
    'ProgramId' => 13,
    'Model' => [
        'Contractor' => 1000007,
        'Description' => 'Тестовая сделка; создание.',
        'Category1000051CustomFieldDataZakupki' => '2017-02-15',
        'Category1000051CustomFieldPostavshchik' => 'Some Company',
        'Category1000051CustomFieldSposobOplati2' => 'PayPal',
        'Category1000051CustomFieldDataPolucheniya' => '2017-03-01',
        'Category1000051CustomFieldDneyDoSoldOut' => 14,
        // ...
    ]
];
// В случае успеха вернет созданную сделку (на самом деле массив с полями; НЕ объект)
$justCreatedDeal = $megaplanDatStore->create($itemData);

Редактирование сделки.

$itemData = [
    'Id' => 12345,  // указываем реальный Id сделки в Мегаплане
    'Model' => [
        'Description' => 'Тестовая сделка; изменение.',
        // ...
    ]
];
$justUpdatedDeal = $megaplanDatStore->update($itemData);

Выборка сделок по параметрам.

use Xiag\Rql\Parser\Node\Query\ScalarOperator;
use Xiag\Rql\Parser\Query;

$query = new Query();
$node = new ScalarOperator\GeNode(
    'Category1000051CustomFieldDataZakupki', '2017-09-01 00:00:00'
);
$query->setQuery($node);
$result = $this->dataStore->query($query);

Более подробно о выборке можно почитать в моих пояснениях по MegaplanAPI

Сервис Мегаплана не предоставляет API для удаления сделок.

Для удобства работы с данными можно обернуть MegaplanDataStore в аспект. И в методах pre- реализовать какую-нибудь подготовительную работу с данными. Так сделано в задаче по переносу заказов из Amazon в Megaplan.