Zapytania do webserwisów

Podsumowanie:
Akcje zapytań do usług webservice umożliwiają API wymianę danych między nAxiom i interfejsami innych serwisów, a także między tenantami w obrębie interfejsu Public API danego środowiska nAxiom. Dane zwracane przez te akcje mogą być zapisywane w bazie danych, używane do wyboru przejścia dla bloku decyzyjnego na workflow albo wyświetlane w specjalnej kontrolce na formularzu: lista rozwijana (WebService).

☛ Menu Admin SPA > NARZĘDZIA > Akcje > Zapytania do WebSerwisów

W tym temacie

Opis akcji

Przykład 1: Komunikacja między tenantami

Przykład 2: Żądanie API do NBP

Przykład 3: Własny warunek obsługi odpowiedzi

Przykład 4: Żądanie SOAP API

Opis akcji

W ramach akcji należy zdefiniować żądanie API do zdefiniowanego osobno źródła danych oraz zapytanie SQL, które wyodrębni odpowiednie dane z odpowiedzi. W zapytaniu dostępne są następujące zmienne:

@_Response: treść (body) odpowiedzi; jeśli dla zwracanych danych określono format JSON, w zapytaniu użyj funkcji OPENJSON.
@_HTTPResponseStatusCode: status odpowiedzi (int) np. 404.
@_HTTPResponseStatusName: nazwa statusu odpowiedzi np. NotFound dla statusu 404.
@_HTTPResponseHeader: nagłówki odpowiedzi w formacie JSON o następującej strukturze:
```
{
"header_1": ["value_1"],
"header_2": ["value_2", "value_3"]
}
```
gdzie header_x to nazwa nagłówka odpowiedzi, a value_x to jego wartość. Wartości nagłówków można pozyskać używając funkcji SQL OPENJSON. W przypadku, kiedy nazwa nagłówka zawiera myślnik (-), odpowiadający mu klucz należy ująć w cudzysłów, na przykład:
```
(SELECT top(1) value
 FROM OPENJSON({@_HTTPResponseHeader}, '$."Content-Type"')
```

W przypadku żądań POST dodatkowo konieczne jest określenie danych, które mają zostać wysłane w sekcji body. Można do tego użyć zapytania SQL, które zwróci odpowiednie wartości, a następnie w wysyłanych danych odwołać się do tych wartości, używając zmiennych {@_QueryBody_SQLQueryData}, gdzie SQLQueryData to nazwa kolumny zwróconej przez zapytanie.

Oprócz właściwości wspólnych dla wszystkich akcji, w akcji zapytań do webserwisów należy określić następujące właściwości:

Źródło danych: zdefiniowane osobno źródło danych; patrz opis źródeł danych w Leksykonie nAxiom.
Metoda wywołania: metoda wywołania API; dostępne wartości: GET, POST, PUT, PATCH i DELETE.
Typ ciała żądania: określa format w jakim wysyłane są załączniki; pole dostępne dla metod typu POST, PUT i PATCH; dostępne wartości:
- RAW: (wartość domyślna) dane w body żądania są tekstem, w przypadku załącznika są kodowane jako Base64; w tym trybie można użyć parametru {@_AttachmentContent_FILEID} do zakodowania danych załącznika jako Base64; przykład użycia przedstawiono poniżej.
- MULTIPART/FORM-DATA: dla tego ustawienia zapytanie musi zwrócić następujące kolumny (w podanej kolejności):
  - Type: typ zawartości żądania. Akceptowane wartości to Text lub File
  - Key: klucz w zawartości żądania, pod którym zostanie umieszczona podana zawartość
  - Content: tekst dla zawartości typu Text
  - FileId: identyfikator załącznika z tabeli core.Attachments dla zawartości typu File
  - ContentType: format danych żądania dla zawartości o typie Text. Wartość domyślna to application/json
W przypadku źródła danych typu Tenant w środowisku nAxiom pole Rodzaj zawartości jest wyświetlane w trybie tylko do odczytu z domyślną wartością RAW. W tym przypadku również możliwe jest korzystanie z parametru {@_AttachmentContent_FILEID}.
Identyfikator tenanta: identyfikator tenanta, do którego ma zostać wysłane zapytanie; pole wyświetlane tylko w przypadku wyboru źródła danych typu Tenant w środowisku nAxiom ; w polu obsługiwane są referencje smart numbers, zmienne formularza oraz zapytania SQL. Patrz także przykład poniżej.
Ścieżka żądania: specyfikacja punktu końcowego (endpoint) i parametrów żądania; jako parametrów można używać zmiennych typu {@PoleFormularza}. W przypadku żądania SOAP API ścieżka jest pobierana z definicji źródła i jest tylko do odczytu, a samo żądanie definiuje się osobno.
Content-Type: pole dostępne w przypadku, gdy Typ ciała żądania to RAW; określa format danych tekstowych; w przypadku źródła danych typu Tenant… pole jest tylko do odczytu i zawiera wartość domyślną application/json.
Nagłówki żądania: dodatkowa specyfikacja nagłówków żądania; kliknij przycisk Nowy nagłówek i wpisz nazwę nagłówka i jego wartość (może być zwracana przez zapytanie SQL).
SQL wysyłanych danych: (tylko żądania SOAP API i żądania REST API typu POST, PUT i PATCH) zapytanie SQL zwracające dane do wysłania w żądaniu, w zapytaniu są dostępne parametry z kontekstu bieżącego formularza w przypadku akcji wykonywanych po kliknięciu przycisku.
Wysyłane dane: (tylko żądania SOAP API i żądania REST API typu POST, PUT i PATCH) dane wysyłane w żądaniu; w treści można korzystać z wartości z modelu formularza oraz wartości zwróconych przez zapytanie SQL; w tym drugim przypadku nazwę kolumny zwróconej przez zapytanie należy poprzedzić przedrostkiem _QueryBody_. Na przykład jeśli zapytanie zwraca kolumnę o nazwie Name, w wysyłanych danych można się do tej kolumny odwołać parametrem {_QueryBody_Name}

Tryb obsługi odpowiedzi: dostępne wartości:
- domyślny: zapytanie SQL określone jako procedura obsługi odpowiedzi jest wykonywane w przypadku, gdy zostanie zwrócony status HTTP z zakresu 200-299; w przeciwnym razie akcja zwróci wyjątek.
- własny warunek obsługi odpowiedzi: w ramach procedury odpowiedzi możesz obsłużyć każdy status HTTP odpowiedzi; patrz przykład poniżej.

Procedura obsługi odpowiedzi: w przypadku akcji na formularzu zapytanie SQL UPDATE, które wyodrębnia dane z odebranej odpowiedzi i zapisuje je w odpowiednich polach tabeli źródłowej; w przypadku akcji użytej we właściwościach bloku decyzyjnego na workflow, zapytanie SQL SELECT, które zwróci nazwę przejścia. W zapytaniu można korzystać ze zmiennych {@_Response}, {@_HTTPResponseStatusCode}, {@_HTTPResponseStatusName} i {@_HTTPResponseHeader}.

Przykład 1: Komunikacja między tenantami

W środowisku wielu tenantów można używać akcji zapytań do webservice do wysyłania żądań do serwisu PublicAPI dowolnego tenanta. Jeśli w akcji zostanie użyte źródło danych typu Tenant w środowisku nAxiom . Wystarczy podać identyfikator docelowego tenanta oraz określić ścieżkę, parametry i treść żądania. Dzięki zastosowaniu uwierzytelniania opartego o tokeny TOTP, nie trzeba osobno obsługiwać uwierzytelniania.

Poniżej podano przykład żądania do punktu końcowego Document/CreateWithAttachments, który obsługuje tworzenie dokumentu wraz z zapisaniem załączników.

Źródło danych: typu Tenant w środowisku nAxiom
Metoda wywołania: POST

Ścieżka żądania:

Document/CreateWithAttachments?documentDefinitionId=631FF...&skipWorkflowActions=true

SQL Wysyłanych danych:
```
SELECT CONCAT('{@_AttachmentContent_', {@AttachmentId}, '}') AS [AttachmentContent]
```
gdzie {@AttachmentId} to identyfikator załącznika z tabeli core.Attachments.

Wysyłane dane:

{
  "Model": {
      "Id": 0,
      "Temat": "<treść tematu>",
      "Pismo": "<treść pisma>"
  },
  "Attachments": [
      {
          "Base64Content": "{@_QueryBody_AttachmentContent}",
          "FileName": "<nazwa pliku załącznika>",
          "Description": "<opis pliku załącznika>",
          "AttachmentCategoryId": "<rowGuid kategorii załączników>"
      }
  ]
}

Zmienna {@_QueryBody_AttachmentContent} zawiera dane załącznika zakodowane jako Base64.

Przykład 2: Żądanie API do NBP

Źródło danych: http://api.nbp.pl/

Ścieżka żądania: api/exchangerates/rates/a/{@Waluta}/{@Data}/?format=json

Żądanie zwraca średni kurs wymiany z tabeli A Narodowego Banku Polskiego dla waluty o symbolu przekazanym zmienną {@Waluta} na dzień określony wartością zmiennej {@Data}. Odpowiedź jest przesyłana w formacie JSON. Przykładowa odpowiedź dla waluty USD na dzień 2021-11-16 to:

{
"table":"A",
"currency":"dolar amerykański",
"code":"USD",
"rates":[
        {
          "no":"221/A/NBP/2021",
          "effectiveDate":"2021-11-16",
          "mid":4.1061
        }
        ]
}

Procedura obsługi odpowiedzi:

aktualizacja pola formularza:

 UPDATE [dbo].[Rozliczenia]
 SET Kurs = (SELECT [mid] FROM OPENJSON({@_Response}, '$.rates')
 WITH ([no] varchar(20),
     [effectiveDate] varchar(20),
     [mid] varchar(20)))
 WHERE Id={@Id}

wybór nazwy przejścia dla bloku decyzyjnego:

SELECT 
 CASE
 WHEN (
   SELECT [mid]*{@Kwota} from openjson({@_Response}, '$.rates')
      WITH ([no] varchar(20), [effectiveDate] varchar(20), [mid] decimal(18,4))
      ) > 300
 THEN 'do kontroli'
 ELSE 'zatwierdź automatycznie'
 END

Literały do kontroli i zatwierdź automatycznie to wartości właściwości Nazwa przejścia określone dla przejść wychodzących z bloku decyzyjnego.

Przykład 3: Własny warunek obsługi odpowiedzi

Przykładowa procedura obsługi odpowiedzi z własnym warunkiem.

DECLARE @msg AS nvarchar(1000)
IF({@_HTTPResponseStatusCode} >= 200 AND {@_HTTPResponseStatusCode} <= 299)
update [dbo].[testy_WS]
set [Odp] = (SELECT * FROM OPENJSON({@_Response})
    WITH (requestedValue nvarchar(4000) '$.description')),
[StatusOdp] = concat({@_HTTPResponseStatusCode}, ' ',
                                        {@_HTTPResponseStatusName}),
[Naglowki] = {@_HTTPResponseHeader},
[ContentType] = (SELECT top(1) value FROM OPENJSON({@_HTTPResponseHeader}, '$."Content-Type"'))
where Id = {@_Id}
ELSE
BEGIN
SELECT @msg = concat('[MSG] ERROR ', {@_HTTPResponseStatusCode},' ',
                                         {@_HTTPResponseStatusName});
RAISERROR(@msg,11,1);
END

Przykład 4: Żądanie SOAP API

Przykład uzyskania wartości z żądania dla SoapApi za pomocą metody nodes():

https://www.dataaccess.com/webservicesserver/NumberConversion.wso

DECLARE @xmlRes XML =
  REPLACE(ISNULL({@_Response},'ERROR'),'<?xml version="1.0" encoding="utf-8"?>',''); 
DECLARE @result NVARCHAR(MAX) = (
SELECT n.value('.','NVARCHAR(MAX)') as CODE
FROM @xmlRes.nodes('declare namespace s="http://schemas.xmlsoap.org/soap/envelope/";
declare namespace x="http://www.dataaccess.com/webservicesserver/";
/s:Envelope/s:Body/x:NumberToWordsResponse/x:NumberToWordsResult') as a(n)
);
UPDATE [dbo].[Invoice]
SET [PriceInWords] = ISNULL(@result,' Pusta'),     
WHERE Id={@_Id}   

|← Przypisywanie zadań |↑ Do góry |→ SQL do bazy systemowej |