SugarTalk - ресурс для администраторов и разработчиков системы SugarCRM.

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.

Пример:

1
2
3
4
5
$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. Как раз имя этого поля мы должны использовать.

Пример:

1
2
3
4
5
6
7
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 заметки.
Пример:

1
2
3
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 — его значение.

Пример:

01
02
03
04
05
06
07
08
09
10
set_entry(
  'session' => $sessionid,
  'module_name' => 'Contacts',
  'name_value_list' => array(
    array(
      'name' => 'name',
      'value' => 'SugarTalk'
    ),
  )
);

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

01
02
03
04
05
06
07
08
09
10
11
12
13
14
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) между двумя записями.

Пример:

01
02
03
04
05
06
07
08
09
10
11
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:

01
02
03
04
05
06
07
08
09
10
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 и т.д.

Пример:

1
2
3
4
get_module_fields(
  'session' => $sessionid,
  'module_name' => 'Contacts'
);

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

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

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

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

Последнее изменениеПонедельник, 10 июля 2017 18:10
  • Оцените материал
    (0 голосов)
  • Опубликовано в SugarCRM
  • Прочитано 23828 раз
Другие материалы в этой категории: « Web Services. Назначение Web Services. Примеры работы »

10963 комментарии

Оставить комментарий

Убедитесь, что вы вводите (*) необходимую информацию, где нужно
HTML-коды запрещены

Наверх

Последние новости

  • 1
  • 2
  • 3
  • 4

Популярные новости

  • 1
  • 2
  • 3
  • 4