Методы API Jasper#

Для проверки работы клиента и отправки запросов к интеграционному сервису API Jasper можно использовать Postman.

Все запросы отправляются в адрес: https://{APIURL}/api/v1/{путь_до_метода}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {путь_до_метода} – путь до вызываемого метода API Jasper.

Получение токена авторизации#

Прежде чем начать проверку запросов в Postman, следует получить токен авторизации для доступа к API Jasper. Для этого:

  1. Отключите проверку SSL-сертификата на вкладке Settings:

../../_images/postsetting.png ../../_images/postsetting1.png
  1. Создайте новый запрос:

../../_images/postsetting2.png
  1. Заполните поля на вкладке Authorization:

../../_images/setting1.png

где:

  • [Type] – выберите «OAuth 2.0»;

  • [Token Name] – введите произвольное наименование токена, например, Jasper;

  • [Grant Type] – выберите «Client Credentials»;

  • [Access Token URL] – введите адрес интеграционного сервиса API Jasper для получения токена https://jasper-geometa.gemsvostok.ru/connect/token;

  • [Client ID] – укажите логин клиента в API Jasper;

  • [Client Secret] – укажите пароль клиента в API Jasper;

  • [Scope] – укажите «jasperApi»;

  • [Client Authentication] – выберите «Send client credentials in body».

../../_images/client_api1.png

где

  • [Type] – выберите «OAuth 2.0»;

  • [Token Name] – введите произвольное наименование токена, например, Jasper;

  • [Grant Type] – выберите «Authorization Code (With PKCE)»;

  • [Callback URL] – введите URL-адрес, на который будет произведено перенаправление для завершения процесса авторизации;

  • [Auth URL] – введите адрес сервиса API Jasper для авторизации https://jasper-geometa.gemsvostok.ru/connect/authorize;

  • [Access Token URL] – введите адрес интеграционного сервиса API Jasper для получения токена https://jasper-geometa.gemsvostok.ru/connect/token;

  • [Client ID] – укажите логин клиента в API Jasper;

  • [Client Secret] – укажите пароль клиента в API Jasper;

  • [Scope] – укажите «jasperApi»;

  • [Client Authentication] – выберите «Send client credentials in body».

  1. Нажмите кнопку Get new Access Token.

Для клиента в качестве пользователя Geometa появится окно для авторизации пользователя в Системе. Необходимо ввести логин и пароль своей персональной учётной записи и нажать кнопку Войти. Postman сообщит об успешном получении токена – «Authentication complete»:

../../_images/gotovo.png
  1. Нажмите кнопку Proceed или дождитесь автоматического открытия окна «MANAGE ACCESS TOKENS»:

../../_images/Procced.png
  1. Нажмите Use Token для использования полученного токена в следующих проверках. Полученный токен будет прописан в поле [Access Token]:

../../_images/use_token.png

Получение информации о правах на просмотр#

Права на просмотр объектов в Системе задаются в приложении API Jasper.

Назначенные права на просмотр можно запросить с помощью метода rights путём выполнения HTTP-GET запроса.

В заголовке необходимо указать Content-Type: application/json. В ответе будет возвращён список алиасов и наименований всех доступных для просмотра объектов Системы.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/rights -H 'content-type: application/json'

где:

  • {APIURL} – адрес интеграционного сервиса.

Ответ придёт в формате:

{
"rights":[
    {
        "name": "Наименование типа объекта",
        "alias": "EntityAlias",
        "type": "reading"
    }
] ,
    "name": "Наименование схемы проекта",
    "alias": "scheme"

    }

где:

  • «rights» – массив объектов Cистемы, который содержит псевдоним и наименование типа объекта. Права на просмотр указанных объектов назначены клиенту с типом «reading»;

  • «name» в блоке «rights» – наименование объекта, для которого даны права на просмотр;

  • «alias» в блоке «rights» – псевдоним объекта, для которого даны права на просмотр;

  • «type» – тип предоставляемых прав, на данный момент всегда «reading»;

  • «name» – наименование схемы проекта, в рамках которой действуют права;

  • «alias» – псевдоним схемы проекта, в рамках которой действуют назначенные клиенту права.

Получение списка всех доступных xsd#

Для получения списка всех доступных xsd используется метод XSDs путём выполнения HTTP-GET запроса. В заголовке необходимо указывать Content-Type: application/json. В ответе будет возвращён список доступных для загрузки xsd.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/XSDs -H 'content-type: application/json'

где:

  • {APIURL} – адрес интеграционного сервиса.

Получение одной xsd-схемы#

Для получения одной конкретной xsd используется метод XSD/{businessScope} путём выполнения HTTP-GET запроса. В заголовке необходимо указать Content-Type: application/json. В ответе будет возвращена запрошенная xsd.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/XSD/{businessScope} -H 'content-type: application/json'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {businessScope} – наименование xsd-файла, полученного в результате вызова метода XSD.

Получение доступных схем проектов#

Xsd-файлы работают только в рамках тех проектов, схемы которых описаны в xsd.

Для получения схем БД используется метод schemes/{bussinessScope} путём выполнения HTTP-GET запроса. В заголовке необходимо указать Content-Type: application/json. В ответе будут возвращены наименования и псевдонимы схем БД, доступных для работы с xsd.

Пример cURL-запроса:

curl -X GET HTTPS://{APIURL}/api/v1/schemes/{bussinessScope} -H 'content-type: application/json'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {bussinessScope} – наименование xsd-файла, полученного в результате вызова метода XSD.

Загрузка файла#

Для загрузки файла в файловое хранилище Системы используется метод file/{schemeId} путём выполнения HTTP-PUT запроса. В заголовке нужно указать Content-Type: multipart/form-data. В тело запроса следует поместить файл. Размер одного файла не должен превышать 1 Гб. В ответ на запрос будет возвращён ключ файла в файловом хранилище Cистемы. В дальнейшем ключ может быть использован в xml-пакете с данными, которые нужно отправить в Cистему.

Пример cURL запроса:

curl -X PUT HTTPS://{APIURL}/api/v1/file/{schemeId} -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -F attachment=@{file}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {file} – путь к файлу.

Схема загрузки файлов в файловое хранилище Cистемы:

../../_images/upload_file1.png

Скачивание файла#

Для выгрузки файла из файлового хранилища Системы используется метод file/{schemeId}/{fileKey} путём выполнения HTTP-GET запроса.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/file/{schemeId}/{fileKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {fileKey} – ключ файла, который нужно выгрузить.

Схема выгрузки файлов из файлового хранилища Системы:

../../_images/vigruzka_faila.png

Удаление файла#

Для удаления файла из карточки объекта используется метод file/{schemeId}/{entityAlias}/{entityKey}/files/{fileKey} путём выполнения HTTP-DELETE запроса.

Примечание

Содержимое файла удаляется из БД, но остается в файловом хранилище.

Пример cURL запроса:

curl -X DELETE HTTPS://{APIURL}/api/v1/file/{schemeId}/{entityAlias}/{entityKey}/files/{fileKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {entityAlias} – алиас типа объекта;

  • {entityKey} – ключ объекта, с которым связан файл;

  • {fileKey} – ключ файла, который нужно удалить.

При успешном выполнении запроса в БД в столбце [sys_status] таблицы d_file_content для этого файла будет установлено значение 1.

Загрузка изображений#

Примечание

Загрузка изображения в карточку объекта возможна при наличии секции Изображения.

../../_images/image.png

Для загрузки изображения в карточку объекта используется метод image/{schemeId}/{typeAlias}/{entityKey} путём выполнения HTTP-PUT запроса. В заголовке нужно указать Content-Type: multipart/form-data.

В тело запроса следует поместить файл с одним либо несколькими изображениями. Запрос должен содержать токен авторизации. Максимальный размер загружаемых данных не должен превышать 1 Гб. Изображение может быть в форматах .tif, .jfif, .pjp, .apng, .ico, .tiff, .gif, .svg, .webp, .xbm, .jxl, .svgz, .jpg, .jpeg, .png, .bmp, .pjpeg, .avif.

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

Пример cURL запроса:

curl -X PUT HTTPS://{APIURL}/api/v1/image/{schemeId}/{typeAlias}/{entityKey} -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' -F attachment=@{file}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {entityKey} – ключ объекта, для которого необходимо загрузить изображение;

  • {file} – путь к файлу с изображением.

Получение списка изображений#

Для получения списка изображений из секции Изображения в карточке объекта используется метод {schemeId}/{typeAlias}/{entityKey}/images путём выполнения HTTP-GET запроса. Для этого необходимо выполнить GET-запрос по ключу объекта, который имеет MR-связь «Изображения (Photo)».

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/{schemeId}/{typeAlias}/{entityKey}/images

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {entityKey} – ключ объекта, изображения которого необходимо выгрузить.

Скачивание превью изображения#

Для выгрузки превью (миниатюры) изображения из секции Изображения в карточке объекта используется метод {schemeId}/{typeAlias}/{entityKey}/images/{imageId}/thumbnail путём выполнения HTTP-GET запроса.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/{schemeId}/{typeAlias}/{entityKey}/images/{imageId}/thumbnail

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {entityKey} – ключ объекта, превью изображения которого необходимо выгрузить;

  • {imageId} – ключ изображения, превью которого необходимо скачать.

Проверка в Postman

  1. Сформируйте GET-запрос к интеграционному сервису API Jasper вида: https://{APIURL}/api/v1/{schemeId}/{typeAlias}/{entityKey}/images/{imageId}/thumbnail.

  2. Нажмите Send. Проверка выполнена успешно, если в ответе возвращена миниатюра изображения объекта:

../../_images/preview_image.png

Скачивание изображения#

Если у объекта присутствуют изображения, то с помощью HTTP-GET запроса можно скачать конкретное изображение, используя метод image/{schemeId}/{imageKey}.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/image/{schemeId}/{imageKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {imageKey} – ключ изображения, которое необходимо скачать.

Выгрузка архива с изображениями объекта#

Для выгрузки архива с изображениями из секции Изображения в карточке объекта используется метод images/{schemeId}/{typeAlias}/{entityKey} путём выполнения HTTP-GET запроса.

Пример cURL запроса:

curl -X GET HTTPS://{APIURL}/api/v1/images/{schemeId}/{typeAlias}/{entityKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {typeAlias} – алиас объекта в Cистеме;

  • {entityKey} – ключ объекта, изображения которого необходимо выгрузить архивом.

Удаление изображения#

Для удаления изображения и миниатюры из карточки объекта используется метод {schemeId}/{entityAlias}/{entityKey}/images/{imageKey} путём выполнения HTTP-DELETE запроса.

Удаляется связь объекта с изображением, связь изображения с миниатюрой и миниатюра.

Примечание

Изображение и миниатюра удаляются из БД, но остаются в файловом хранилище.

Пример cURL запроса:

curl -X DELETE HTTPS://{APIURL}/api/v1/{schemeId}/{entityAlias}/{entityKey}/images/{imageKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {entityAlias} – алиас типа объекта;

  • {entityKey} – ключ объекта, с которым связано изображение;

  • {imageKey} – ключ изображения, которое нужно удалить.

При успешном выполнении запроса в БД в столбце [sys_status] таблицы d_file_content для изображения и миниатюры будет установлено значение 1.

Получение списка объектов#

Важно

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

В API Jasper v2 реализована возможность получения определённых полей объектов.

Также реализована возможность получения ответа в форматах .json и .xml:

  • чтобы получить ответ в формате .json, в Headers запроса необходимо указать:

Content-Type: application/json
Accept: application/json
  • чтобы получить ответ в формате .xml, в Headers запроса необходимо указать:

Content-Type: application/json
Accept: application/xml

Примечание

Получение информации об объектах, которые имеют SR-связь, занимает много времени. Чтобы ускорить ответ, укажите в теле запроса только требуемые поля.

Для получения информации по объектам используется метод entities/{schemeId}/{typeAlias} путём выполнения HTTP-POST запроса.

Пример cURL запроса:

curl -X POST HTTPS://{APIURL}/api/v2/entities/{schemeId}/{typeAlias}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {typeAlias} – алиас объекта в Системе.

TypeAlias – псевдоним объекта Geometa, по которому можно выполнить поиск. Перечень псевдонимов объектов, доступный для поиска, задаётся правами для клиента на этапе его регистрации в API. Получить данный перечень можно методом rights.

В результате запроса будут получены первые 100 объектов с их полями. Количество возвращаемых в ответе объектов можно ограничить.

Примечание

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

Получение ограниченного количества объектов#

Управлять количеством объектов и страниц можно с помощью query-параметров count и start.

Получение ограниченного количества объектов с помощью параметра count:

Пример POST-запроса:

HTTPS://{APIURL}/api/v2/entities/{schemeId}/{typeAlias}?count={quantity}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {quantity} – количество необходимых объектов.

Постраничный вывод объектов с помощью параметров count и start:

Для того чтобы выводить объекты постранично, необходимо добавить к параметру count параметр start и указать, с какого по счёту объекта начать вывод.

Пример POST-запроса:

HTTPS://{APIURL}/api/v2/entities/{schemeId}/{typeAlias}?count={quantity}&start={position}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {quantity} – количество необходимых объектов;

  • {position} – позиция объекта, с которой необходимо начать вывод. Позиция начинается с нуля.

Получение списка объектов с ограниченным выводом полей#

Для получения информации из конкретных полей объектов, включая поля связанных объектов, необходимо в теле запроса указать только требуемые поля с уровнями вложенности, используя параметр paths:

  {
"paths":
 [
 "{Field_1}",
 "{Field_2}",
 "{Field_3}"
 ]
  }

где:

  • {Field_1}, {Field_2}, {Field_3} – пути до необходимых полей.

Формирование пути возможно двумя способами:

  • указать алиас LVItem, в этом случае алиас LV указывать не нужно;

    Например:

    {
    "paths":
    [
    "AdrCapitalBuild/WfAdrPointActiveView/AdrPoint/KeyField",
    "AdrCapitalBuild/Geometry",
    "AdrCapitalBuild/OriginalGeometry"
    ]
    }
    
  • указать алиас LT целевого типа, а не алиас LVI, если в пути используется получение полей по связи, указывающей на LV.

    Например:

    {
    "paths":
    [
    "DocRelRSObjectOKS/WfLinearObject/TPRelLineObjWithMonitoring/EngElectroNetwork/AdrRelReconOks/GknOKS/KN"
    ]
    }
    

Если хотя бы у одного из типов не будет предоставлено прав доступа, то ответ не будет получен.

Для получения значения из поля, необходимо корректно задать к нему путь:

  {
"paths":
 [
 "{alias поля}",  //путь к простому полю
 "{alias поля справочного значения}/{alias справочника}/{alias поля}", //путь к полю со справочным значением
 "{alias поля связи}/{alias объекта}/{alias поля}", //путь к полю через локальну MR-связь c LT
 "{alias второго поля MR-связи}_{alias связи}/{alias объекта}/{alias поля}", //путь к полю через глобальную MR-связь c LT
 "{alias поля связи}/{alias LVI}/{alias поля в LT}", //путь к полю через MR-связь c LVI
 "InfoSetKey/DmdInfoSet/{alias поля}", //путь к полю набора данных
 "Geometry", //получение геометрии объектов в системе координат EPSG:4326
 "OriginalGeometry" //получение геометрии объектов в оригинальной системе координат
 ]
  }

Получение отфильтрованного списка объектов#

Для фильтрации выводимого списка объектов необходимо в тело запроса добавить критерии фильтрации с помощью параметра filter.

Например:

{
            "filter": {
                "operator": "and",
                "criterions": [
                    {
                        "operator": "eq",
                        "property": {
                            "alias": "m_Street",
                            "type": "field"
                        },
                        "value": "Рощинская"
                    }
                ]
            }
        }

Внутри параметра filter необходимо добавить критерии поиска объектов Системы в формате .json. Формат критериев должен содержать в себе корневой элемент {"filter": "operator", "criterions":[]}.

Например:

{
    "paths":
    [
    "AdrCapitalBuild/WfAdrPointActiveView/AdrPoint/KeyField",
    "AdrCapitalBuild/Geometry",
    "AdrCapitalBuild/OriginalGeometry"
    ],
    "filter": {
        "operator": "and",
        "criterions": [
            {
                "operator": "eq",
                "property": {
                    "alias": "m_Street",
                    "type": "field"
                },
                "value": "Рощинская"
            }
        ]
    }
}

Параметр operator в фильтре может принимать значения and или or. Если в запросе приведён только один блок критериев, то значение operator может быть любым.

В массиве criterions параметр operator может принимать значения: «like», «notlike», «gt» (>), «lt» (<), «gte» (>=), «lte» (<=), «eq», «noteq», «empty», «notempty», «in», «notin».

Так можно делать вложенные подкритерии:

{"operator":"and","criterions":[{"operator":"or","criterions":[{"operator":"and","criterions":[]}]}]}.

В массив criterions добавляются условия поиска в формате:

{
    "operator": "operator",
    "property":{"alias":"FieldAlias","type":"field"},
    "value":"2018-04-25T00:00:00"
}

В параметре alias указывается псевдоним поля, по которому выполняется поиск и к которому указываются условия в блоке criterions.

В параметре type всегда указывается константа field.

Если нужно использовать несколько вложенных критериев, следует добавить их через запятую:

{
"filter": {
    "operator": "and",
    "criterions": [
        {
            "operator": "",
            "property": {
                "alias": "",
                "type": "field"
            },
            "value": ""
        },
        {
            "operator": "",
            "property": {
                "alias": "",
                "type": "field"
            },
            "value": ""
        }
    ]
}
}

Если не требуется устанавливать критерии поиска объекта, то параметр criterions может быть не задан.

Например, тело запроса для получения всех значений Системы определённого типа будет выглядеть следующим образом:

{
"operator":"and",
"criterions":[]
}

В ответ будет возвращаться массив данных (поля объекта, ключи и типы связанных объектов, описание геометрии в формате .geojson и наименование системы координат, если был запрошен геометрический объект), найденных в Системе по заданному условию в следующем формате:

    [{
"EntityAlias": "EntityAlias",
"EntityKey": EntityKey,
"Fields": {
    "Project": "Name of prpject",
    "SomeFieldA": "SomeValueA",
    "SomeFieldB": "SomeValueB",
"Geometry": {
    "Geojson": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                101818.45,
                635684.6
            ],
            [
                101881.62,
                635741.48
            ],
            [
                101968.61,
                635644.87
            ],
            [
                101905.44,
                635588
            ],
            [
                101818.45,
                635684.6
            ]
        ]
    ]
},
"Srs": "SomeSrs"
},
"Project": "SomeProject"
}
}]

Получение реплицированных/нереплицированных объектов#

По умолчанию запрос в текущем режиме возвращает информацию по всем объектам проекта: реплицированным и нереплицированным.

Для получения только реплицированных или только нереплицированных данных необходимо использовать в теле запроса параметр owndata, который применяется к корневому типу объекта.

  • Чтобы получить собственные данные проекта, укажите для параметра значение true:

{
"owndata": true
}
  • Чтобы получить реплицированные данные, укажите для параметра значение false:

{
"owndata": false
}

Например, тело запроса для получения данных реплицированных физических лиц будет выглядеть следующим образом:

{
    "paths": [
        "KeyField"
    ],
    "owndata": false
}

Получение объекта по ключу#

Для получения информации об объекте используется метод entities/{schemeId}/{typeAlias}/{entityKey} путём выполнения HTTP-POST запроса.

Пример cURL запроса:

curl -X POST HTTPS://{APIURL}/api/v2/entities/{schemeId}/{typeAlias}/{entityKey}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – алиас схемы проекта;

  • {typeAlias} – алиас объекта в Системе;

  • {entityKey} – ключ объекта, информацию о котором необходимо получить.

Для вывода определённых полей объекта в теле запроса укажите список нужных полей с уровнями вложенности.

Например:

[
"GName",
"CultCategoryOKN/CultCategoryOKN/Name",
"CultKindOKN/CultKindOKN/Name",
"Geometry"
]

Создание объектов в Системе#

Важно

Создание объектов в Системе возможно только в том случае, если права на их создание описаны в xsd-схеме.

Для создания объектов в Системе используется метод runpackage/{businessScope}/{schemeId} путём выполнения HTTP-POST запроса. В заголовке необходимо указывать Content-type: text/xml. В ответе будут возвращены ключ и алиас объекта в Системе, а также псевдоним схемы проекта, в котором был создан объект.

Пример cURL-запроса:

curl -X POST HTTPS://{APIURL}/api/v1/runpackage/{businessScope}/{schemeId} -H 'content-type: text/xml'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {businessScope} – наименование файла xsd, полученного в результате вызова метода xsd;

  • {schemeId} – псевдоним схемы проекта.

Обновление объектов в Системе#

Для обновления объектов в Системе используется метод runpackage/{businessScope}/{schemeId} путём выполнения HTTP-POST запроса.

В заголовке необходимо указывать Content-Type: text/xml.

Пример cURL-запроса:

curl -X POST HTTPS://{APIURL}/api/v1/runpackage/{businessScope}/{schemeId} -H 'content-type: text/xml'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {businessScope} – наименование файла xsd, полученного в результате вызова метода xsd;

  • {schemeId} – псевдоним схемы проекта.

Регистрация кнопки «Отправить»#

Зарегистрировать кнопку Отправить для одного экземпляра объекта Системы может только одна внешняя интеграционная система (клиент). При попытке зарегистрировать для такого объекта ещё одну кнопку Отправить другой системой в ответ будет возвращена ошибка.

При вызове действия кнопки Отправить формируется запрос, в тело которого помещается следующая информация:

  • ключ и псевдоним объекта в Cистеме Geometa, где будет размещена кнопка;

  • адрес клиента;

  • схема проекта, где находится объект.

Для регистрации кнопки Отправить используется метод register/{schemeId}/{entityKey} путём выполнения HTTP-PATCH запроса. В теле запроса необходимо указать URL-адреса, куда будет возвращаться ответ по вызову действия данной кнопки в Системе.

В заголовке необходимо указывать Content-Type: application/json. При успешном ответе будет возвращён HTTP Status 204.

Пример cURL запроса:

curl -X PATCH HTTPS://{APIURL}/api/v1/register/{schemeId}/{entityKey} -H 'content-type: application/json' -d HTTP://{CLIENTURL}

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {entityKey} – ключ объекта, для которого необходимо зарегистрировать кнопку Отправить;

  • {CLIENTURL} – адрес клиента.

Пример тела запроса:

https://server_name:port

После регистрации Система будет отображать кнопку Отправить в карточке указанного объекта. При нажатии на кнопку отправляется HTTP-POST оповещение по зарегистрированному адресу.

Отправка сообщения о состоянии процесса (статуса)#

Отправить сообщение о статусе выполнения бизнес-процесса, например, о том, что результат услуги был успешно передан на портал услуг, можно только для того объекта Системы, для которого была зарегистрирована кнопка Отправить.

Для отправки сообщения пользователю Системы по заданному объекту используется метод status/{schemeId}/{entityAlias}/{entityKey} путём выполнения HTTP-PATCH запроса.

В заголовке необходимо указать Content-Type: application/json. При успешном ответе вернётся HTTP Status 204.

В тело запроса помещается сообщение (уведомление), которое необходимо доставить пользователю в кодировке UTF-8. Полученное сообщение (уведомление) может быть отображено для пользователя в отдельном поле [Результат отправки статуса] в карточке объекта Системы. Данная возможность необходима в случаях, когда пользователю требуется выполнить действие, указанное в сообщении (уведомлении).

Пример cURL запроса:

curl -X PATCH HTTPS://{APIURL}/api/v1/status/{schemeId}/{entityAlias}/{entityKey} -H 'content-type: application/json' -d '{ "successCode": "true", "message": "some message" }'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {entityAlias} – алиас объекта;

  • {entityKey} – ключ объекта.

"successCode" может принимать значения "true", "false" или быть пустым. С помощью "successCode" в Системе задаётся возможность отправки результата пользователем в интеграционный сервис, в том числе, если потребуются исправления в Системе в результате валидации на стороне интеграционного сервиса. Таким образом, "successCode" регулирует состояние кнопки Отправить в интерфейсе Системы.

  • "successCode":"true" должен быть направлен в случае, когда результат был успешно доставлен во внешнюю систему, например, на портал услуг.

Это означает завершение интеграционного взаимодействия по конкретному экземпляру объекта. В "message" может содержаться уведомление для пользователя об успешной отправке:

../../_images/message_otpravleno.png ../../_images/message_otpravleno2.png
  • "successCode":"false" должен быть направлен в случае, если после некоторых действий пользователя в Системе и попытки отправить результат в интеграционный сервис, произошла ошибка, которую необходимо устранить и отправить результат повторно.

Например, не пройдена валидация на стороне интеграционного сервиса. В "message" должно быть указано сообщение для пользователя, отражающее суть ошибки. Во всех остальных случаях "successCode" может быть пустым: "successCode":"". Это означает, что состояние кнопки Отправить в Системе останется неизменным. В таком сценарии пользователю Системы можно просто передать сообщение (уведомление). Например, что валидация переданного результата прошла успешно.

Отмена регистрации кнопки «Отправить»#

Чтобы убрать кнопку Отправить из карточки объекта, необходимо произвести отмену регистрации кнопки. Для этого используется метод unregister/{schemeId}/{entityKey} путём выполнения HTTP-PATCH запроса.

В заголовке необходимо указать Content-Type: application/json. При успешном ответе вернется HTTP Status 204.

Пример cURL запроса:

curl -X PATCH HTTPS://{APIURL}/api/v1/unregister/{schemeId}/{entityKey} -H 'content-type: application/json'

где:

  • {APIURL} – адрес интеграционного сервиса;

  • {schemeId} – псевдоним схемы проекта;

  • {entityKey} – ключ объекта, для которого необходимо отменить регистрацию кнопки Отправить.