Программное взаимодействие через API между 2 разными экземплярами Falcon

В этой статье покажем как можно настроить обработку данных между 2 разными системами через API. 

Одна система будет посылать запрос через механизм исходящих запросов API, а вторая система - принимать этот запрос через входящий API и обрабатывать переданные данные. 

В качестве примера возьмем задачу создания бага - на демо решениях есть форма, которая позволяет создать описание ошибки. Эти данные идут в нашу систему учета задач и багов и там создается баг на основе этого внешнего запроса. 

Входящий API на системе учета задачами и багами

На принимающей стороне создаем метод входящего API в разделе /asapi: 

Создаем хранимую процедуру обработки этого метода: 

CREATE PROCEDURE [dbo].[api_bug_newbug]
@parameters ExtendedDictionaryParameter READONLY,
@username nvarchar(256)
as
begin
	declare @type nvarchar(max) = ''
	select @type = Value2 from @parameters where [Key] = 'type'

    declare @text nvarchar(max) = ''
	select @text = Value2 from @parameters where [Key] = 'text'

    declare @info nvarchar(max) = ''
	select @info = Value2 from @parameters where [Key] = 'info'

    declare @g nvarchar(max) = ''
	select @g = Value2 from @parameters where [Key] = 'g'


    declare @projectID int
    select @projectID = id from tt_projects where bugGuid = @g


	if(@projectID is null) begin
    	select 'Wrong BugGuid' Msg, 0 Result, 0 errorCode
    	return
    end

    if(len(@text)>1023) set @text  = substring(@text, 1, 1024)
    if(len(@info)>1023) set @info  = substring(@info, 1, 1024)

    insert into tt_bugs
    	(screen, url, text, description,
         projectID, created, createdBy, statusID)
    values('', '', isnull(@type, '') + '  ' +  isnull(@text, ''),  isnull(@info, ''),
          @projectID, getdate(), '', 1)


    select '' Msg, 1 Result, 0 errorCode
	select 1
	select 'notification' type,
    	'Новый Баг по API - смотреть' text ,
        'someuser' [to],
        'common' typeCode,
        '' url,
        '' additional

end
	

Исходящий API запрос из демо решения

Создаем метод исходящего запроса API: 

Прописываем процедуру Request - подготовка запроса к отправке: 

CREATE PROCEDURE [dbo].[api_sendBug_request]
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2)
	@username nvarchar(32)  -- текущий пользователь.
AS
BEGIN
	declare @type nvarchar(max) = ''
    select @type   = value2 from @parameters where [key]='type'
    declare @text nvarchar(max) = ''
    select @text   = value2 from @parameters where [key]='text'
    declare @info nvarchar(max) = ''
    select @info   = value2 from @parameters where [key]='info'

    declare @bugGuid nvarchar(max) = ''
    select @bugGuid   = value2 from @parameters where [key]='bugGuid'


	-- SELECT 1  Msg, Result, Url (адрес, куда будет идти запрос)
	select '' Msg, 1 Result, 'https://site.ru/api/action/newbug?g='+@bugGuid+'&text='+@text+'&info='+@info+'&type='+@type Url

	-- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
	select 'id' name, '5' value, '' [type] -- form (в форме передается), header (в http headers), get запросы передавайте прямо в URL
END

Прописываем процедуру Response - обработка ответа от источника API после выполнения запроса: 

CREATE PROCEDURE [dbo].[api_sendBug_response]
	@response nvarchar(max),
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2 - те же что и на request)
	@username nvarchar(32)
AS
BEGIN
	-- SELECT 1
	select '' Msg, 1 Result, @response Response
	-- SELECT 2 Внешние действия
END

В форме, где происходит сохранение бага в SaveItem через внешнее действие вызовем это действие в SELECT 2: 

-- SELECT 2 в SaveItem
select 'apirequest' type,
	'sendBug' code, 'type' p1_name, @ptype p1_value, 'text' p2_name, @ptext p2_value,
	'info' p3_name, @pdata p3_value, 'bugGuid' p4_name, @bugGuid p4_value

Таким образом, настроена передача данных из одной системы в другую через универсальный механизм API. 

Безопасность обработки данных в данном случае обеспечивается за счет использования bugGuid - при неверном данном API просто будет отбрасывать данные и не создавать баг в соответствующем проекте. 

Альтернативный вариант - использовать API с Token, когда сначала идет запрос auth для получения token, а затем уже выполняется основной запрос. 

В этом случае процедура была бы несколько сложнее - потребовалось бы в Response процедуре вызывать  через внешнее дейвствие дополнительный метод. 

Данный подход позволяет организовать активное плотное взаимодействие между разными экземплярами Falcon Space без необходимости напрямую залезать в БД другого экземпляра. 

Документация про API веб-платформы Falcon Space