Новый сервис обновлений от 1С. Описание

Ранее, долгое время, существовал инструмент для получения оглавления обновлений и сведений об их расположении. Это было описано и показано на примерах, реализовано в множестве интересных разработок, всяких обновляторов да интеграторов. Разумеется, не считая механизмов парсинга самих страниц сайтов 1С. На ИС такого предостаточно.

Но в конфигурациях с использованием современной БСП применён другой механизм, http-сервис, описания для которого мне найти не удалось нигде. Буквально в одном месте в скрипте было упомянуто. 

Покопавшись в типовой механике, выявил кое-что про этот сервис.

1. Обновление, как сущность, значительно жёстче привязано к конкретной ИБ, а не к конфигурации вообще. Потому, что в механизмах фигурирует UID базы и UID обновления (VersionUin). Вероятно, это связано с контролем легальности получения обновлений, подпиской и т.д. Отсюда следует, что утрата UID обновления - это проблема, т.к. не позволит получить следующее за ним.

2. Полная история (оглавление) версий обновлений недоступна. Можно скачать лишь актуальное, самое свежее, обновление, и сведения о нём, но нельзя получить данные о старом годичной давности. Вероятно, это вопрос оптимизации (старое нужно десяткам, а свежий релиз - миллионам систем, стучащимся на сервер).

3. Обновление конфигурации и скачивание-установка-применение патчей явно разделены, и для патчей сделан свой метод сервиса. О патчах подробнее, например, тут.

Большинство непосредственно работающего функционала реализовано в общем модуле ПолучениеОбновленийПрограммы.

Обращение к серверу

Сервер: update-api.1c.ru (или update-api.1c.eu)
Порт: 443
Прокси: не требуется
Авторизация: логин и пароль можно оставлять пустыми
Таймаут: 30 (обычно этого хватает)

Для ЗащищенноеСоединениеOpenSSL указывается "СертификатыУдостоверяющихЦентровОС"

В заголовках запросов для методов желательно в явном виде указывать Content-Type, равный "application/json".

Для проверки работоспособности можно применять метод "ping" (адрес вызова /update-platform/programs/update/ping), пример можно посмотреть в ИнтернетПоддержкаПользователей.ПроверитьURLДоступен.

Для методов используется набор дополнительных параметров "additionalParameters", описывающий конкретную ИБ и её конфигурацию. Получить его можно функцией ИнтернетПоддержкаПользователей.ДополнительныеПараметрыВызоваОперацииСервиса(), и уточнить разрядность системы (ключ "platform64Supported") функцией ПолучениеОбновленийПрограммыКлиентСервер.Это64РазрядноеПриложение().

Пример дополнительных параметров:

Данные передаются и получаются в json, преобразуются из/в коллекции 1С штатными глобальными ЗаписатьJSON/ПрочитатьJSON. При этом важно, что входные параметры должны быть представлены структурой, а не соответствием, т.к. видимо, в объявлении модели данных сервиса указан строгий порядок следования ключей в теле запроса, а соответствие порядок ключей при сериализации теряет. А вот выходные параметры следует десериализовывать в соответствие.

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

Метод "info"

Метод POST. Полный адрес для http-запроса: update-platform/programs/update/info

Назначение: Получение сведений о текущем актуальном обновлении для ИБ.

Параметры:

    programName // строка, служебное имя: Accounting, HRM, регистр букв не важен. В коде упоминается значение "Unknown", и передача такого параметра приводит к правильному, но пустому ответу (возможно, нужно было для тестирования)
    versionNumber // строка, в формате "4 точки"
    platformVersion // строка, в формате "4 точки"
    programNewName // строка, обычно пуста
    redactionNumber // строка, обычно пуста
    updateType // строка, допустимые значения: NewConfigurationAndOrPlatform (рабочее обновление), или NewPlatform (только платформа), или NewProgramOrRedaction (переход на другую программу/редакцию)    
    additionalParameters // массив структур вида key (строка), value (строка), см.выше

Возвращаемые данные:

    platformUpdateResponse // обычно пуст
    errorName // строка, служебное имя ошибки (например, "ConnectError"), при ряде ошибок пуста
    errorMessage // строка, подробное описание ошибки, может быть непуста при пустой errorName
    configurationUpdateResponse // если всё верно, содержит результатное соответствие, см.ниже
    additionalParameters // насколько я понял, пуст, возможно, зарезервирован на будущее

Сведения об обновлении содержит configurationUpdateResponse, имеющий следующие ключи (для примера, с содержанием)

Для случая updateType, равного "NewConfigurationAndOrPlatform"

Из updateInfoUrl можно получить гипертекстовое описание изменений по сравнению с предыдущим релизом. Это надёжнее, чем, например, обращение по адресу https://its.1c.ru/db/content/updinfo/src/<Имя>/<НомерВерсии>/index.htm (где "Имя", например, "hrm30", а "НомерВерсии" 3.1.15.96).

Из howToUpdateInfoUrl можно получить гипертекстовое описание порядка обновления. Впрочем, они обычно редко меняются и всем давно известны.

Метод вызывается, например, в функции ПолучениеОбновленийПрограммы.ИнформацияОДоступномОбновленииСлужебная

Метод "update"

Метод POST. Полный адрес для http-запроса: update-platform/programs/update/

Назначение: Получение сведений о файлах обновления и связанных данных, пригодных для скачивания и применения.

Параметры:

    programVersionUin // строка, VersionUin нужного обновления
    upgradeSequence // массив строковых VersionUin, с которых возможен переход на нужное; если пуст или внутренне противоречит заявленным совместимостям обновлений, то метод не сработает
    platformDistributionUin // строка, обычно пуста    
    login // строка, учётная запись пользователя ИТС
    password // строка, пароль учётной записи ИТС
    additionalParameters // массив структур вида key (строка), value (строка), см.выше

Возвращаемые данные:

    platformDistributionUrl // обычно пуст
    errorName // строка, служебное имя ошибки, при ряде ошибок пуста
    errorMessage // строка, подробное описание ошибки, может быть непуста при пустой errorName
    configurationUpdateDataList // если всё верно, содержит результатный массив соответствий, см.ниже
    additionalParameters // обычно пуст

Сведения о файлах содержит configurationUpdateDataList, каждый элемент массива - соответствие, данные об отдельном файле обновления, последним идёт запись о текущем (актуальном) обновлении. Соответствие имеет следующие ключи (для примера, с содержанием)

Из updateFileUrl можно получить уникальный путь для скачивания. Время жизни и актуальности этой ссылки не изучал. Может, это временно генерируемый "на лету" путь для отдачи файла, а может, она стабильна долгое время. На всякий случай, лучше такое не хранить, а сразу качать нужные данные.

Из updateFileName и updateFileFormat можно получить общее понимание, что за данные.

Из templatePath можно получить относительный путь, удобный для организации раздельного развёртывания и хранения данных.

Из hashSum можно получить строку для самопроверки правильности скачивания и раскрытия zip-архива, т.к. это Base64Строка от хеша MD5 от файла cf/cfu (который updateFileName), а не хеш архива.

Метод вызывается, например, в функции ПолучениеОбновленийПрограммы.ПолучитьОписаниеФайловОбновленияКонфигурацииИПлатформы

Скачивание файла по этим данным желательно выполнять с другим http-соединением, нежели для предыдущих методов, и сведения берутся из предоставленной адресной строки. Для приведённого выше примера это будет:

Сервер: dl03.1c.ru
Порт: 443
Прокси: не требуется
Авторизация: логин и пароль пользователя ИТС
Таймаут: 43 200

Полный адрес для http-запроса: public/file/tmplts/get/46303814-0a6f-4f64-982f-40d5fd733fe7

Выполняется обычный GET-запрос вида хттпСоединение.Получить(хттпЗапрос, ПутьИмяСкачанногоФайла) и, если всё успешно, в означенном месте появится файл 1Сv8.zip

Это обычный архив, раскрываемый с помощью ЧтениеZipФайла, причём РежимВосстановленияПутейФайловZIP рекомендуется "Восстанавливать". В составе архива находится обычный пакет файлов - UpdInfo.txt, 1cv8upd.htm, 1cv8.mft, иногда описание версий библиотек, а также "Новое в версии" и собственно файл обновления сfu либо полноценный cf.

Метод "getInfo"

Метод POST. Полный адрес для http-запроса: update-api.1c.ru/update-platform/patches/getInfo

Назначение: Получение сведений об исправлениях (патчах).

Параметры:

    programVersionList // массив структур или соответствий, в каждом из которых 2 ключа: "programName" (строка), например, "HRM", и "versionNumber" (строка), например, "3.1.15.96". Типовая механика заполняет несколькими версиями (текущей, актуальной планируемой), но достаточно внести хотя бы текущую версию основной конфигурации. Номер версии можно взять, например, из доп.параметров, из ключа "ConfigVersion".
    installedPatchesList // массив строк, идентификаторов исправлений, уже установленных в системе. Может быть получен функцией ПолучениеОбновленийПрограммы.ИдентификаторыУстановленныхИсправлений(), где, кстати, сказано, что в отличие от идентификаторов обновлений, идентификаторы исправлений не являются коммерческой тайной вендора.
    additionalParameters // массив структур вида key (строка), value (строка), см.выше

Возвращаемые данные:

    errorName // строка, служебное имя ошибки, при ряде ошибок пуста
    errorMessage // строка, подробное описание ошибки, может быть непуста при пустой errorName
    patchUpdateList // если всё верно, содержит результатный массив соответствий, см.ниже

Сведения о файлах содержит patchUpdateList, каждый элемент массива - соответствие, данные об отдельном исправлении. Соответствие имеет следующие ключи (для примера, с содержанием)

Из applyToVersion можно получить, для каких конфигураций каких релизов может быть применено исправление. Каждое соответствие содержит ключи "programName" (в нотации, аналогичной входному параметру "programVersionList") и "versionNumber" (один или несколько номеров версий в формате "4 точки", и если несколько, то разделены запятой).

Из ueid можно получить, по какому пути следует обращаться для скачивания файла исправления. В самом простом случае, ссылка на скачивание будет иметь вид <ИмяСервера>/public/sso/patches/download?keys=<Идентификатор>, например, "https://dl03.1c.ru/public/sso/patches/download?keys=3e1984b1-28da-4bef-9d75-97513be91fd6"

Из name можно получить, каково имя исправления на сайте, файла в архиве и расширения этого исправления в конфигурации. Следует иметь в виду, что по ссылке находится zip-архив вида patches_<Код>, причём этот "Код" не коррелирует с ИД патча (например, patches_281020201714). В нём вложенный zip-архив, уже с ID патча, например, 90ae5713-81a0-4c3b-b472-3a83d5441eae.zip. В свою очередь, в этом вложенном архиве находятся собственно файл манифеста и файл расширения (например, EF_30174583.cfe).

Из status можно получить, каков текущий статус исправления. Значение "publish" (доступно) или "revocation" (отозвано). Отозванные исправления недоступны для скачивания в интерфейсе https://releases.1c.ru/patches, однако могут быть прочитаны и потому следует учитывать этот ключ при каждом обращении.

Файл манифеста Manifest.xml содержит сведения, в целом дублирующие основной набор, а именно:
<Name>EF_30174583</Name>
<Description>В форме П-6 за 9 месяцев не проверяется условие "строки с 700 по 800 заполняются 
только в отчёте за «январь-июнь»"</Description>
<UUID>90ae5713-81a0-4c3b-b472-3a83d5441eae</UUID> - это ИД патча
<ModifiedMetadata>ОбщийМодуль.ИнтерпретаторКонтрольныхСоотношенийРосстата.ПроверитьУсловиеНаПериод</ModifiedMetadata>
и несколько тегов, описывающих применимость, вида
<AppliedFor>
<ConfigurationName>УправлениеНебольшойФирмой</ConfigurationName> - т.е. тут уже нотация не служебное "Accounting", а "БухгалтерияПредприятия"
<Versions>1.6.22.75</Versions> - если несколько, будут через запятую
</AppliedFor>

Метод вызывается, например, в функции ПолучениеОбновленийПрограммы.ИнформацияОДоступныхИсправленияхКонфигураций

Скачивание файла по этим данным желательно выполнять с другим http-соединением, нежели для предыдущих методов. Логин и пароль для соединения не требуются, таймаут достаточно 30.

Метод "getFiles"

Метод POST. Полный адрес для http-запроса: https://update-api.1c.ru/update-platform/patches/getFiles

Назначение: Получение сведений о файлах исправлений, пригодных для скачивания и применения.

Параметры:
    patchUinList (массив строковых гуидов, чьи данные о файлах требуется получить к скачиванию)
    login // строка, учётная запись пользователя ИТС
    password // строка, пароль учётной записи ИТС
    additionalParameters // массив структур вида key (строка), value (строка), см.выше (и кстати, необходимость таких параметров в таком методе означает, что работа с исправлениями также привязана к конкретной ИБ, для которой скачиваем, т.к. требуется передача, например, параметра IBID).

Возвращаемые данные:

    errorName // строка, служебное имя ошибки, при ряде ошибок пуста
    errorMessage // строка, подробное описание ошибки, может быть непуста при пустой errorName
    patchDistributionDataList // если всё верно, содержит результатный массив соответствий, см.ниже

Сведения о файлах содержит patchDistributionDataList , каждый элемент массива - соответствие, данные об отдельном файле исправления, т.е. cfe-расширении. Соответствие имеет следующие ключи (для примера, с содержанием)

Метод вызывается, например, в функции ПолучениеОбновленийПрограммы.ОписаниеФайловИсправлений

P.S. Имя конфигурации в служебной нотации, т.е. "HRM", можно получить с помощью ИнтернетПоддержкаПользователей.СлужебнаяИмяПрограммы()

Пока на этом всё. Если в меня кинут ссылкой, где этот рест-сервис нормально описан, или если кто дополнит эту весьма краткую статейку, буду премного благодарен. Ну а если баян, то готов к тухлым помидорам.

Всё изложенное скорее всего актуально на релизах платформы 8.3.14 и выше.

UPD: Дописал про исправления.