Falcon Space

Исходящие запросы API (отправка запросов к внешним API с сайта)

Оглавление
Вы можете обратиться к внешним API через использование Внешних действий (код apirequest, использование описано в документации по Формам). 
Чтобы создать запрос, необходимо выполнить следующее:
  • создать запись о новом запросе (таблицы Исходящие запросы API на /asapi)
  • реализовать процедуру request(она выдает адрес и параметры для выполнения запроса)
    • На входе: @parameters ExtendedDictionaryParameter (коллекция входных параметров в Key nvarchar(32), Value2 nvarchar(max))  и @username (текущий пользователь)
    • Возвращает SELECT 1 (Msg, Result и URL, ContentType)
      • URL - адрес, который будет вызван по HTTPS
      • RequestParameterForResponse - некая строка, которую потом можно извлечь в процедуре respose по одноименному ключу из @parameters.  В исходящий запрос эта информация не идет. 
      • ContentType - можно задать для POST запросов свой ContentType (для формы).
        • По умолчанию он подставляется для форм multipart/form-data; boundary=------
        • и для json тела application/json
    • и SELECT 2 (параметры которые будут передаваться вовне - name, value, type). 
      • type - вариант form, header, json.
        • Если отправить надо post запрос, то параметры ставьте в form.
        • Если передан json (используется для POST, имя можно также ставить в JSON) - то его содержимое будет телом всего запроса POST. Все остальные параметры типа Form в этом случае игнорируются (при этом параметры типа headers не игнорируются).
        • Если нужны обычные get параметры - то передавайте их через URL
  • реализовать процедуру обработки ответа - response
    • На входе ответ от внешнего источника в виде строки @response, @parameters ExtendedDictionaryParameter (коллекция входных параметров в Key, Value2, которые приходили в Request процедуру. Сюда также приходит от Request параметр RequestParameterForResponse)
    • Ответ
      • SELECT 1 Msg, Result и Response (может быть дополнительная обработка и выдача ответа вовне). 
      • SELECT 2 Вызов внешних действий (Внешние запросы API и т.д.)

Ответ при вызове API, например, из формы, передается в поле Response из SELECT 1. 

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

Для тестирования API можно использовать метод /Api/Req/{code} - он вернет ответ в JSON формате. 
 
Пример хранимой процедуры request: 
CREATE PROCEDURE [dbo].[api_metrikaMonth_request]
	@parameters ExtendedDictionaryParameter READONLY,  -- входящие параметры для внутренней обработки (используйте Key, Value2)
	@username nvarchar(32)  -- текущий пользователь.
AS
BEGIN


declare @metrikaID nvarchar(256)
	set @metrikaID = '53312170' -- Falcon

--set @metrikaID = '60713749' -- DEMO

declare @date1 nvarchar(256) = convert(nvarchar(10), dateadd(day, -30, getdate()), 120)  --2020-04-26
declare @date2 nvarchar(256) = convert(nvarchar(10), getdate(), 120)


declare @token nvarchar(256) = 'token...'
declare @url nvarchar(512) = 'https://api-metrika.yandex.net/stat/v1/data/bytime?'
    	+ 'id='+@metrikaID
    	+ '&preset=sources_summary'
        + '&group=day'
    	+ '&metrics=ym:s:users,ym:s:visits,ym:s:manPercentage,ym:s:womanPercentage' +
        + '&date1=' + @date1   --2020-04-26
    	+ '&date2=' + @date2    -- 2020-04-26
    	-- SELECT 1  Msg, Result, Url (адрес, куда будет идти запрос)
	select '' Msg, 1 Result, @url Url

	-- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
--	select 'Content-type' name, 'application/json' value, 'header' [type] -- form (в форме передается), header (в http headers), get запросы передавайте прямо в URL
  --  union
  --  select 'Accept' name, 'application/json' value, 'header' [type]
    --union
    select 'Authorization' name, 'OAuth '+ @token value, 'header' [type]
END
 
Пример response:
CREATE PROCEDURE [dbo].[api_metrikaMonth_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

Обработка ошибок API 

В @parameters процедуры response передается информация в следующих ключах (Key,Value2):
  • RequestResult - краткое описание возникшей ошибки.
  • RequestMsg - если False, то возникла ошибка при выполении запроса.
  • r_apiErrorStatus - код статуса ошибки (когда возникло исключение при запросе во внешнюю систему)
  • r_apiErrorInfo - детальная информация об ошибке (когда возникло исключение при запросе во внешнюю систему)
Пример извлечения: 
 DECLARE @reqRes  NVARCHAR(MAX) = ISNULL((SELECT TOP 1 Value2 FROM @parameters WHERE LOWER([Key]) = LOWER(N'RequestResult')),N'')
  DECLARE @reqMsg  NVARCHAR(MAX) = ISNULL((SELECT TOP 1 Value2 FROM @parameters WHERE LOWER([Key]) = LOWER(N'RequestMsg'   )),N'')
  declare @apiErrorStatus nvarchar(max)  = (select value2 from @parameters where [key]='r_apiErrorStatus')
  declare @apiErrorInfo nvarchar(max)  = (select value2 from @parameters where [key]='r_apiErrorInfo')
 
Примечание: 
Учитывайте длину кодов и ключей (Key не должны быть больше 32 символов).

Работа с JSON в SQL Server

Работа с XML в SQL Server 

Онлайн редакторы для XML и JSON

Инструменты позволяют скопировать большой текст и просматривать через дерево элементов.

Falcon Space - функциональная веб-платформа разработки на узком стеке MS SQL/Bootstrap. Вводная по Falcon Space
Насколько полезной была статья?

Google поиск по нашей документации

Выгода от использования Falcon Space

В 2-3 раза экономнее и быстрее, чем заказная разработка
Более гибкая, чем коробочные решения и облачные сервисы
Используйте готовые решения и изменяйте под свои потребности
Нужна бесплатная консультация?
Планируете делать веб-проект?
Сайт использует Cookie. Правила конфиденциальности OK