3.16.3.3.1. Verwendung der Webservice-Schnittstelle

Voraussetzungen für die Verwendung der Webservice-Schnittstelle

Die Webservice-Schnittstelle muss einen Webservice ansprechen, dessen Antwort-Mapping sich in eine der folgenden Klasse serialisieren lässt:

Für Webservices, die mehrere Zeilen zurückliefern können:

public class DiwInboundModel 
{
    /// <summary>
    /// Row model
    /// </summary>
    public Dictionary<string, object>[] Rows { get; set; }
}

Die rows Property enthält je Zeile ein Dictionary mit dem Key als Spaltenname und dem Value des Spaltenwerts.

Für Webservices, die immer nur eine Zeile zurückliefern:

public class DiwSingleRowInboundModel : Dictionary<string, object>
{
}

Beispielimplementierung von Webservices, die vom Datentintegrationswidget unterstützt werden.

Für Webservices, die mehrere Zeilen zurückliefern können:

Dieses Beispiel zeigt einen Webservice, der mehrere Datensätze zurückliefern kann und selbst Parameter als Body übergeben bekommt.
Diese Body-Parameter werden bei der Konfiguration des Datenintegrationswidgets genau wie alle anderen Parameter erfasst und im Falle von POST-Services in den Body übertragen.
Wenn die Zugangsdaten nicht stimmen, wird ein NotFound Fehler zurückgegeben. Das Widget wird dann also mit Fehler dargestellt und nicht mit leerer Menge.

C# Code:

using System.Collections.Generic;
using System.Web.Http;
using static BA.Controllers.ApiControllers.AuthController;

namespace BA.CRM.DEV.Controllers
{
    /// <summary>
    /// Api controller for developer samples
    /// </summary>
    [RoutePrefix("api/dev")]
    public class WSDevApiController : ApiController
    {
        /// <summary>
        /// Sample class for api webservices, to be called with admin / admin1 
        /// Is called for data integration widget sample
        /// </summary>
        /// <param name="login"></param>
        /// <returns>json or null</returns>
        [AllowAnonymous]
        [HttpPost]
        [Route("getusers")]
        public IHttpActionResult GetUsers([FromBody] LoginModel login)
        {
            if (login != null && login.Username == "admin" && login.Password == "admin1")
            {
                Dictionary<string, object> tina = new Dictionary<string, object>();
                tina["FirstName"] = "Tina";
                tina["LastName"] = "Müller";
                Dictionary<string, object> hans = new Dictionary<string, object>();
                hans["FirstName"] = "Hans";
                hans["LastName"] = "Meiner";
                Dictionary<string, object> timo = new Dictionary<string, object>();
                timo["FirstName"] = "Timo";
                timo["LastName"] = "Schmidt";

                GetUsersModel res = new GetUsersModel();
                res.Rows = new Dictionary<string, object>[] { tina, hans, timo };

                return Ok(res);
            }
            else
                return NotFound();
        }

        /// <summary>
        /// Sample users model
        /// </summary>
        public class GetUsersModel
        {
            /// <summary>
            /// Row model
            /// </summary>
            public Dictionary<string, object>[] Rows { get; set; }
        }
    }
}

XML-Mapping-Code:

<?xml version="1.0" encoding="utf-8" ?>
<BAWebServiceDefinitions xmlns="https://www.business-app.com/WebServices" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<MappingTemplate id="Diw.LoginTemplate" sourceType="Newtonsoft.Json.Linq.JToken" targetType="System.Collections.Generic.Dictionary`2[[System.String],[System.Object]]">
		<Mapping>
			<From>$.FirstName</From>
			<To>FirstName</To>
		</Mapping>
		<Mapping>
			<From>$.LastName</From>
			<To>LastName</To>
		</Mapping>
	</MappingTemplate>
	<WebService id="getusers" displayName="Sample logins" inboundModelType="BA.DataIntegration.WebServices.DiwEndpoints.Models.DiwInboundModel">
		<Method>POST</Method>
		<Url>https://servername.org/api/dev/getusers</Url>
		<InboundMappings>
			<MultiValueMapping templateRef="Diw.LoginTemplate">
				<From>$.Rows</From>
				<To>Rows</To>
			</MultiValueMapping>
		</InboundMappings>
	</WebService>
</BAWebServiceDefinitions>

Für Webservices, die immer nur eine Zeile zurückliefern:

Dieses Beispiel zeigt einen Webservice, der keinen oder einen Datensatz zurückliefern kann und selbst Parameter als in der URL übergeben bekommt.
Die Url-Parameter müssen ins Mapping aufgenommen werden, wie hier dargestellt.
Wenn die Id nicht stimmt, wird eine leere Menge zurückgegeben. Das Widget wird dann also ohne Datensätze dargestellt, es gibt aber keinen Fehler.

C# Code:

       /// <summary>
        /// Sample class for api webservices to get a single user by id
        /// </summary>
        /// <param name="id"></param>
        /// <returns>json or null</returns>
        [AllowAnonymous]
        [HttpPost]
        [Route("getuserbyid")]
        public IHttpActionResult GetUserById(int id)
        {
            if (id == 42)
            {
                Dictionary<string, object> tina = new Dictionary<string, object>();
                tina["FirstName"] = "Tina";
                tina["LastName"] = "Müller";

                return Ok(tina);
            }
            else
                return Ok("");
        }

XML-Mapping-Code:

<WebService id="getuserbyid" displayName="Get user by id" 
			inboundModelType="BA.DataIntegration.WebServices.DiwEndpoints.Models.DiwSingleRowInboundModel"
			outboundModelType="Newtonsoft.Json.Linq.JToken">
	<Method>POST</Method>
	<Url>https://servername.org/api/dev/getuserbyid?id={ id }</Url> <!-- remove whitespaces next to id!  -->
	<UrlMappings>
		<Mapping>
			<From>$.id</From>
			<To>id</To>
		</Mapping>
	</UrlMappings>
	<InboundMappings>
		<Mapping>
			<From>$.FirstName</From>
			<To>FirstName</To>
		</Mapping>
		<Mapping>
			<From>$.LastName</From>
			<To>LastName</To>
		</Mapping>
	</InboundMappings>
</WebService>