API (ver. 2.5)

Общие сведения

Протокол и точки подключения

1. Обмен данными осуществляется посредством передачи xml документов по протоколу HTTP
2. Конечная точка имеет вид http(s)://%адрес сервера Grotem%/%имя решения%/admin/%метод%, номер порта зависит от конфигурации web сервера IIS (по умолчанию 80 для http и 443 для https), например:
   http://server.cloudapp.net/agent/admin/uploaddata2
3. Используется "Basic" авторизация, имя пользователя - "admin", пароль - пароль решения.
4. Сервер поддерживает обмен сжатыми данными, клиент должен указать значение "gzip" или "deflate" в заголовке "content-encoding" и(или) "accept-encoding"
5. Кодировка - UTF-8

Методы

UploadData2 (POST)

1. Загружает данные на сервер. 
2. Структура xml документа:
   

   <?xml version="1.0" encoding="UTF-8"?>
   <Root>
       <RegionalSettings NumberDecimalSeparator="" NumberGroupSeparator=""/>
       <Rows>
           <Row _Type="%Тип данных%" _RS="%статус строки%" Id="%GUID объекта%" ...%атрибуты объекта%>
               <%Подчиненная таблица% Key="%ключ строки%">
                   <Row LineNumber="%номер строки%" ...%атрибуты строки%/>
                   <Row LineNumber="%номер строки%" ...%атрибуты строки%/>
               </%Подчиненная таблица%>
           </Row>
       </Rows >
   </Root>

3. Статусы строки: "0" - новая запись, "1" - измененная запись, "2" - удаленная запись, "3" - помеченная на удаление
4. Типы данных - имя типа объекта, например "Catalog.Outlet"
5. Подчиненные таблицы - объект может иметь 0 или более подчиненных таблиц.
6. Ключ строки - одно или несколько названий полей подчиненной таблицы, разделенные запятой. Необязательный атрибут. От его наличия зависит способ которым сервер изменит объект на сервере. Если ключ строки не указан, то при записи сервер сначала удалит все строки из подчиненной таблицы а затем вставит из файла. При наличии ключа сервер будет пытаться найти запись и обновить ее, или вставить если не найдет. Рекомендуется всегда указывать ключ, это позволит снизить трафик между мобильным агентом и сервером, предотвратить рост трекинговых таблиц.
7. В необязательном теге RegionalSettings указываются значения разделителей целой и дробной частей числа, групп разрядов.
8. Возвращаемое значение - "ок" в случае успеха или текст ошибки в противном случае.
9. Команда -ud утилиты utils.exe использует метод UploadData2 для загрузки данных.

UploadData2Async (POST)

1. Асинхронная версия UploadData2
2. Возвращает GUID сессии загрузки и продолжает работу в фоновом режиме.
3. Для получения статуса сессии следует использовать метод AsyncTaskStatus

UploadData3 (POST)

1. Загружает данные на сервер
2. Загрузка аналогична UploadData2, за исключением интерпретации атрибута "_RS". Если UploadData2 строго выполняет действие согласно значению атрибута, то UploadData3 проверяет существование объекта в базе и выполнит вставку если объекта нет и обновление если есть не зависимо от указанного в "_RS" значения.
3. За счет дополнительных проверок работает чуть медленнее, для первоначальной загрузки данных в базу рекомендуется использовать метод UploadData2 со значением "_RS" равным нулю.
4. Возвращаемое значение - "ок" в случае успеха или текст ошибки в противном случае.

UploadData3Async (POST)

1. Асинхронная версия UploadData3
2. Возвращает GUID сессии загрузки и продолжает работу в фоновом режиме.
3. Для получения статуса сессии следует использовать метод AsyncTaskStatus

DownloadData (POST)

1. Получает данные с сервера

2. Клиент формирует уникальный номер сессии и передает его серверу вместе со списком типов необходимых объектов с просьбой вернуть новые или измененные с момента последнего сеанса данные. После обработки клиент должен подтвердить получение данных с помощью метода "DownloadDataCommit"

3. Сервер возвращает данные, измененные с момента последней подтвержденной сессии загрузки.

4. Структура запроса
   

   <?xml version="1.0" encoding="UTF-8"?>
   <Request Session="%GUID сессии%">
       <Entity Name="%Тип данных%"/>
       <Entity Name="%Тип данных%"/>
   </Request>

5. Возвращаемое значение - xml document

DownloadDataCommit (POST)

1. Помечает на сервере сессию загрузки данных как успешную.
2. Сервер возвращает данные, измененные с момента последней подтвержденной сессии загрузки.
3. Структура запроса
   

   <?xml version="1.0" encoding="UTF-8"?>
   <Request Session="%GUID сессии%">
   </Request>

4. Возвращаемое значение - "ок" в случае успеха или текст ошибки в противном случае.

DownloadDeleted (GET)

1. Возвращает список объектов, помеченных на удаление.
   
   

CheckIfExists (POST)

1. Возвращает список объектов, не существующих в базе данных.
2. Структура запроса:
   

   <?xml version="1.0"?>
   <Request>
       <Entity Name="%Тип объекта%">
           <Row Id="%GUID объекта%"/>
       </Entity>
   </Request>

3. Структура ответа:
   

   <?xml version="1.0"?>
   <Root>
       <Entity Name="%Тип объекта%">
           <Row Id="%GUID объекта%"/>
       </Entity>
   </Root>

4. Пример запроса: Обмен данными с сервером 
5. Пример ответа: Обмен данными с сервером 

AsyncTaskStatus (GET)

1. Возвращает статус сессии асинхронной загрузки данных
2. Возможные значения: "ok", "xxx completed.." (где xxx - количество обработанных объектов), или текст ошибки.
3. Пример запроса: http://server.cloudapp.net/agent/admin/asynctaskstatus/542EF0E8-C178-406E-BF55-800BEE853AD9

DownloadDeviceLog (GET)

1. Возвращает логи обмена мобильных агентов с сервером - содержимое таблицы DeviceLog.

Реализация

Сценарии обмена

1. В 1С конфигурациях для взаимодействия с платформой Grotem существует регистр сведений "ChangedData", который с помощью подписок на события наполняется ссылками на новые, измененные или помеченные на удаление объекты.
2. Для выгрузки данных на сервер обработка 1С, которая занимается обменом формирует xml документ на основе данных из регистра и отправляет его серверу (UploadData2 или UploadData3). В случае если сервер вернул "ок" - регистр очищается.
3. Для загрузки данных с сервера обработка формирует уникальный ключ сессии со списком необходимых типов данных и отправляет его серверу (DownloadData). В случае успешной обработки полученных данных обработка вызывает DownloadDataCommit для фиксации успешной сессии загрузки.
4. Обмен может быть настроен в автоматическом режиме с помощью регламентного задания или запуска процесса 1cv8.exe планировщиком заданий Windows

Пример отправки данных из 1С

//RequestFileName содержит данные для отправки на сервер

//сжимаем данные
ZipFileName = GetTempFileName(".zip"); 
ZipFile = New ZipFileWriter(ZipFileName, , , ZIPCompressionMethod.Deflate, ZIPCompressionLevel.Optimal);
ZipFile.Add(RequestFileName, ZIPStorePathMode.StoreRelativePath, ZIPSubDirProcessingMode.ProcessRecursively);
ZipFile.Write();

//отправляем
Connection = New HTTPConnection("server.cloudapp.net",80,"admin", "S0mePassword"); 
ResultFileName = GetTempFileName(); 
HeaderHTTP = New Map(); 
HeaderHTTP.Insert("Content-Encoding", "deflate");
Connection.Post(ZipFileName,"/webapp/admin/uploaddata2", ResultFileName, HeaderHTTP);

//результат
Result = New TextDocument();
Result.Read(ResultFileName, TextEncoding.UTF8);
    For C = 1 To Result.LineCount() Do
    Message(Result.GetLine(C));
EndDo;