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

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

• реализовать процедуру обработки ответа - response
  • На входе ответ от внешнего источника в виде строки @response, @parameters ExtendedDictionaryParameter (коллекция входных параметров в Key, Value2, которые приходили в Request процедуру. Сюда также приходит от Request параметр RequestParameterForResponse)
  • Ответ
    • SELECT 1 Msg, Result и Response (может быть дополнительная обработка и выдача ответа вовне). 
    • SELECT 2 Вызов внешних действий (Внешние запросы API и т.д.)

• вызвать запрос через внешние действия (при сохранении формы, отправке уведомления или других местах).
  Для форм - Формы. Как выводить и обрабатывать данные на форме из внешнего источника через API

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

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

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

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 

 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')
  

select 'apirequest' type, 'checkContragent' code, 'clientID' p1_name, cast(@clientID as nvarchar(max)) p1_value

Внешние материалы по обработке JSON и XML

• https://docs.microsoft.com/ru-ru/sql/relational-databases/json/json-data-sql-server?view=sql-server-ver15
• https://stackoverflow.com/questions/2867501/parse-json-in-tsql
• https://habr.com/ru/post/343062/
• https://habr.com/ru/post/317166/

Работа с XML в SQL Server 

• https://stackoverflow.com/questions/15680259/parse-xml-in-sql-server/15681388
• https://stackoverflow.com/questions/3989395/convert-xml-to-table-sql-server

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

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

• https://xmlgrid.net/ - просмотр XML
• https://jsoneditoronline.org/ - редактор JSON