Web Services. API

Добрый день всем читателям блога. Сегодня мы начинаем изучение CRM WEB API.
Начнем с краткого обзора всех функций SugarCRM, их параметров и назначения.

Список функций:
login ()
logout ()
seamless_login ()
get_user_id ()
get_entry ()
get_entries ()
get_entry_list ()
get_relationships ()
get_note_attachment ()
get_document_revision ()
set_entry ()
set_entries ()
set_relationship ()
set_note_attachment ()
set_document_revision ()
search_by_module ()
get_server_info ()
get_module_fields ()

login($user_auth, $application_name) — авторизация в SugarCRM и создание сессии.
Параметры функции:
$user_auth — массив пользовательской информации с логином, паролем и используемой версией протокола. Пароль должен быть зашифрован в md5.

Пример:

$user_auth => array(
  'user_name' => 'admin',
  'password' => '21232f297a57a5a743894a0e4a801fc3',
  'version' => '2'
),

$application_name — это просто имя вашего приложения, которое обращается к ЦРМ. Используется только для логирования, указывайте любое.

В случае успешной авторизации в ответ мы получаем имя пользователя(name), его id (user_id), валюту по умолчанию и, самое главное, — номер сессии(id), который нужно обязательно сохранить для всех последующих запросов. Далее id сессии сохраним в переменной $session и в этой статье используем его под этим же именем без дальнейших объяснений.

P.S. Данную информацию получаем только при использовании REST протокола, при использовании SOAP в ответ приходит только id сессии.

logout($session) — выход из CRM и завершение сессии.

seamless_login($session) — используется для Sugar Offline Client. Это функция только PRO версии.

get_user_id($session) — получить id текущего пользователя.

get_entry($session, $module_name, $id, $select_fields, $link_name_to_fields_array) — получить запись на основании ее уникального id.

Параметры функции:
$module_name — имя модуля, содержащего нужную запись;
$id — id записи (во всех стандартных модулях это 36-значный varchar);
$select_fields — массив со списком полей, необходимых для извлечения. Данный параметр можно не передавать, в данном случае CRM вернет значения всех полей;
$link_name_to_fields_array — получить поля из связанного модуля. Для связи в системе используется поля типа link. Как раз имя этого поля мы должны использовать.

Пример:

get_entry (
  'session' => $sessionid,
  'module_name' => 'Accounts',
  'id' => '3d921d14-047f-cc7d-1988-490b63592ae8',
  'select_fields' =>
    array('name', 'type'),
)

get_entries($session, $module_name, $ids, $select_fields, $link_name_to_fields_array) — получить массив записей по переданным $ids. Останавливаться подробно на ней не будем.
Функция полностью аналогична предыдущей get_entry, за исключением того, что в $ids у нас массив id.

get_entry_list($session, $module_name, $query, $order_by, $offset, $select_fields, $link_name_to_fields_array, $max_results, $deleted ) — получить список (list) записей указанного модуля с переданным условием.

Параметры функции:
$module_name — имя модуля;
$query — фильтр для извлечения записей(в виде sql запроса). Например: «name LIKE '%IBM%'». Таким образом извлечем все записи в имени которых присутствует IBM;
$order_by — параметр сортировки. Например: «name DESC»;
$offset — сколько записей с начала пропустить;
$select_fields, $link_name_to_fields_array — полностью аналогичны параметрам из предыдущей функции get_entry;
$max_results — максимальное количество записей для извлечения. Если не передан, берется соответствующий параметр из настроек SugarCRM (по умолчанию 20);
$deleted — 0: не удаленные записи, 1: удаленные записи. Этот параметр можно не передавать, если вам не нужно отображать удаленные записи.

Пример использования этой функции в следующей статье.

get_relationships($session, $module_name, $module_id, $related_module, $related_module_query, $deleted) — загрузить информацию из связанного модуля.

Все параметры мы рассматривали в предыдущих функциях. Пример использования этой функции в следующей статье.

get_note_attachment($session,$id) — получить прикрепление к заметке.

В данном случае $id — это id заметки.
Пример:

get_note_attachment(
  'session' => $sessionid, 'id' => 's5gvd0f3-67fv-bn6m-4dsv-490bdsd6fdtr'
)

get_document_revision($session, $id) — функция, аналогичная предыдущей, только для работы с модулем документы.

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

set_entry($session, $module_name, $name_value_list) — создать или изменить запись в CRM.

$name_value_list — это массив, каждый элемент которого, тоже, в свою очередь, массив из двух элементов с ключами name и value, где name — это имя поля, а value — его значение.

Пример:

set_entry(
  'session' => $sessionid,
  'module_name' => 'Contacts',
  'name_value_list' => array(
    array(
      'name' => 'name',
      'value' => 'SugarTalk'
    ),
  )
);

В данном примере мы создали новую запись с именем SugarTalk. Если нам необходимо изменить запись, то к необходимым параметрам мы добавляем id записи для обновления.

set_entry(
  'session' => $sessionid,
  'module_name' => 'Contacts',
  'name_value_list' => array(
    array(
      'name' => 'id',
      'value' => 's5gvd0f3-67fv-bn6m-4dsv-490bdsd6fdtr',
    ),
    array(
      'name' => 'name',
      'value' => 'SugarCRM WEB',
    ),
  )
);

Теперь мы уже не создаем новую запись, а обновляем запись с заданным id.

set_entries($session,$module_name, $name_value_lists) — создать или изменить записи.

Функция полностью аналогична предыдущей. Только теперь в $name_value_lists передается сразу массив для добавления или обновления записей.

set_relationship($session, $module_name, $module_id, $link_field_name, $related_ids) — Устанавливает связь (relationship) между двумя записями.

Пример:

set_relationship(
  'session' => $sessionid,
  'module_name' => 'Accounts',
  'module_id' => '4аеtd5np-cg5t-cof8-fb5h-4tfv5ythpets',
  'link_field_name' => 'contacts',
  'related_ids' =>
  array(
    '2f043319-7cb0-6bfa-75d3-490b63fa6c08',
    'c57d7598-42e6-cca8-a302-490b63118b48'
  ),
)

В данном примере мы связываем два контакта, имеющие соответствующие id, с контрагентом.

set_relationships($session, $module_names, $module_ids, $link_field_names, $related_ids) — аналогичная функция для установки сразу нескольких разных связей.

set_note_attachment ($session, $note) и set_document_revision ($session, $document_revision) — очень схожи, и позволяют загрузить документ или заметку.
Разберем подробнее работу функции set_document_revision ($session, $document_revision)

Параметры:
$document_revision — это массив из следующих параметров: id документа (если необходимо обновить документ), имя документа, имя файла и сам контент файла в кодировке base64.

Пример из документации SugarCRM:

set_document_revision(
  'session' => $sessionid,
  'document_revision' => array(
    'id' => '8d7f0917-19d3-9f88-80d7-49121ddb62e2',
    'document_name' => 'test document',
    'revision' => 'B',
    'filename' => 'test.txt',
    'file' => 'fdgh754hjnfdbsy56tgefdshgt8765t4wesygdfbGHfd574tegrdf'
  )
);

search_by_module($user_name, $password, $search_string, $modules, $offset, $max_results) — функция поиска строки в указанных модулях.
Параметры:
$user_name — имя пользователя;
$password — пароль пользователя (в md5);
$search_string — строка поиска;
$modules — массив с именами модулей, в которых будет осуществляться поиск;
$offset — сдвиг от начала записей (по умолчанию 0);
$max_results — максимальное количество возвращаемых записей (limit в sql).

get_server_info() — возвращает информацию о SugarCRM: версию, редакцию (CE, PRO, ENT), текущий часовой пояс и т.д.

get_module_fields($session, $module_name) — возвращает описание всех полей, используемых у вас в модуле: их название, тип, label и т.д.

Пример:

get_module_fields(
  'session' => $sessionid,
  'module_name' => 'Contacts'
);

Итак, мы разобрали используемые фукнции и их параметры. Если кому-то нужна более подробная информация, скачиваете документ «5.5 web services overview».

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

Теперь возникает вопрос, как всем этим пользоваться? Основные принципы использования SugarCRM WEB API обязательно разберем в следующей статье данного цикла.

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

Есть 14 коммент. к “Web Services. API”

  1. kolya27:

    такой вопрос.

    Есть метод — $link_name_to_fields_array — получить поля из связанного модуля. Для связи в системе используется поля типа link. Как раз имя этого поля мы должны использовать. Так вот пишу

    $linkArr = array (array ('name' => 'opportunities', 'value' => array ('id', 'name', 'amount')));

    $response = $this->client->get_entry_list ($this->sessionId, 'Contacts', $filter,'contacts.date_entered DESC',0, array ('id','first_name', 'last_name',$linkArr,2000,0);

    Так вот проблема в том что в Sugar 6.2 Profession выдает ошибку как только дополнительный модуль не прикручивай. Может быть кто сталкивался с подобной проблемой!??!?!

  2. Шуга Админ:

    Смотрите в логах что за ошибка. И кидайте логи с ошибкой в студию :wink:

  3. kolya27:

    Итак, после задания настроить приложение с SugarCrm 6.2.0 Pro выявил следующие недостатки протокола SOAP:

    1. Для модуля contacts «выгребает» почему то с повторяющимися id записи и кол-во «выгребки» максимум 2200 штук (вероятно нет group by contacts.id), и это при том что 2/3 повторяющихся, т.е реальное кол-во меньше тысячи. Это не получилось обойти ни как.

    2. Вообще не работает 'link_name_to_fields_array' для get_entry_list.

    В связи с этим, перешел на протокол REST c использованием curl. Все работает отлично. И количество «выгребки» из контактов 3300 без повторяющихся id (вероятно есть group by contacts.id)

  4. Шуга Админ:

    Я тоже использую протокол REST в своих php и python приложения для работы с SugarCRM.

    Насчет ограничения количества выборки странно, сложно так сказать как вы загружаете записи,

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

    и вследствие этого вы доходите до ограничения запросов к БД, которые ограничивает шугаровский database manager.

    Попробуйте в секции в config.php в секции 'resource_management'->'special_query_modules' добавить модуль с каким вы пытаетесь работать, или же увеличить 'resource_management'->'default_limit'

  5. romashka:

    Спасибо, очень полезная статья. :-D

    Правда, кое-что уже в ней устарело ...

    Думаю, в статье стоит упомянуть, что функции типа set_ возвращают объект, содержащий в тос числе и id новой записи.

    Сам дошёл этого интуитивно ))) Но до этого не знал, как получить этот ай ди

    Сейчас пишу класс для связи сторонней системы с SugarCRM , пишу на версии 6.2.1 CE

    Возникла проблема. Хочу связать email адрес с контактом, но получаю

    Fatal error: Uncaught SoapFault exception: [Client] looks like we got no XML document in … далее описание вызванного метода

    Вот мой код:

    $params = array(
    'module1' => 'Contacts',
    'module1_id' => 'eb0d9036-30e5-da66-08b0-4e42929bf751',
    'module2' => 'EmailAddresses',
    'module2_id' => 'a6e8ae94-5f55-4d7c-a65e-4e428e8a5b69');
    $this->response=$this->client->set_relationship($this->session,$params);
    

    Но вот код, работающий штатно, т.е. связь контакта с контрагентом:

    $params = array(
    'module1' => 'Contacts',
    'module1_id' => 'eb0d9036-30e5-da66-08b0-4e42929bf751',
    'module2' => 'Accounts',
    'module2_id' => 699cf056-4940-d414-e6c8-4e410cdd2b77');
    $this->response=$this->client->set_relationship($this->session,$params);
    

    Не оставьте в беде! Заказчики требуют...

  6. Шуга Админ:

    Не скажу за последние версии, времени нет проверить.

    Раньше всегда делал самым простым способом. Просто для контакта исользовал поле email1,

    при сохранении автоматически создавался email и связь с ним:

    $client->set_entry($session_id, 'Contacts', array(
                array("name" => 'first_name',"value" => 'Vasya'),
                array("name" => 'last_name',"value" => 'Batareikin'),
                array("name" => 'email1',"value" => 'example@email.com')
                ));
    

    • romashka:

      А что делать, если мне надо получить тут же id данного имейла, чтобы прикрепить его ещё и к контрагенту?

      Было бы круто иметь API для работы с таблицей email_addr_bean_rel напрямую

      • Шуга Админ:

        Ничего не мешает вам дописать это API,

        мне обычно тоже для связи с внешними приложениями не достаточно, или не удобно работать с их API,

        я обычно всегда расширяю API под себя, SugarCRM это позволяет в upgrade safe.

        Не разбирался с расширением SOAP, так как работаю с REST, который точно очень легко расширить, буквально за десять-двадцать минут, написать функцию которая бы прикрепляла ваш email к нужным контрагентам, контактам, да и вообще делала все то как вы хотите )

        Давно уже подумываю написать статью по расширению WEB API, но время не позволяет.

        • romashka:

          Как раз кое-что мешает — техническое задание по проекту предусматривает только написание класса, спомощью которого можно подсоединяться и делать дело. Sugar будет стоять не на моём севере, на заказчик будет подключать класс для связи двух своих систем.

          Сам в качестве CRM использую Drupal =)

          Спасибо! Фишка с email1 прокатила для контактов. :-P

          Но...

          get_relationship для email и contact тоже выдаёт похожую системную ошибку...

          А get_entry для контакта показывает только сами адреса, а не их id

        • romashka:

          Всё, я разобрался! Спасибо спасибо! :-D

  7. а где ж брать $module_id для get_relationships?

  8. Шуга Админ:

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

Написать комментарий

Вы должны войти чтобы комментировать.