Dynamics 365 CE, wirtualne encje i protokół OData v4

Dynamics 365, Virtual Entities, Web API

W dzisiejszym wpisie chciałbym zaprezentować Wam, w jaki sposób zbudować usługę sieciową (web service) ODAta v4, która będzie działać z dostępnym w „pudełkowym” systemie Dynamics 365 providerem danych dla wirtualnych encji. W sieci znajdziecie całą masę poradników opisujących konfigurację domyślnego lub tworzenie niestandardowego dostawcy danych. W tym miejscu postaram się natomiast ugryźć temat z drugiej strony i opisać w jaki sposób zbudować usługę sieciową, którą będzie mogła być „skonsumowana” przez dostępnego w systemie, domyślnego providera danych, udostępnianych za pomocą protokołu OData v4.

Oczywiście, poniższe kroki nie są jedynym, możliwym sposobem na osiągnięcie zakładanego celu. Możecie potraktować je jako wprowadzenie dla osób, które chciałyby skorzystać z możliwości oferowanych przez mechanizm wirtualnych encji, nie chcąc jednocześnie (z różnych przyczyn) budować własnego data providera.

Usługa

Do budowy pożądanej usługi wykorzystamy framework ASP.NET Web API wraz z rozszerzeniem Microsoft.AspNet.OData.  Klasy kontrolerów budujemy w podobny sposób jak w przypadku „klasycznego” Web API. Podstawową różnicą w tym przypadku jest fakt, że będą one dziedziczyć po klasie ODataController.

public class ItemsController : ODataController
{
    //TODO: Implementation…
}

Ważną kwestią jest konieczność wykorzystania modelu danych w formacie EDM, który został stworzony w celu wsparcia komunikacji naszego, implementowanego API („front-end” aplikacji) z repozytoriami danych („back-end”). W tym celu w metodzie Register w pliku WebApiConfig.cs umieszczamy następujący kod.

ODataConventionModelBuilder modelBuilder = new ODataConventionModelBuilder();
modelBuilder.EntitySet<Item>("items");
config.MapODataServiceRoute("items", "odata", modelBuilder.GetEdmModel());

W powyższym przykładzie klasa Item opisuje obiekt, który jest zwracany przez repozytorium danych.

W to właściwie już wszystko. Po wykonaniu ww. czynności możemy przejść do implementacji konkretnych metod odpowiadających komunikatom protokołu HTTP (GET, POST, itp.).

Dokładny opis tego w jaki sposób w oparciu o framework ASP.NET Web API budować usługi sieciowe, które korzystają z protokołu OData v4, znajdziecie pod adresem: http://odata.github.io/WebApi/

Klucze

Pierwszą kwestią na której „przejechałem się” projektując model danych był wybór typu danych unikalnego identyfikatora zwracanego rekordu. Na początku zdecydowałem się na liczbę całkowitą (integer). Niestety, nie była to dobra decyzja. Virtual Entities OData 4 Provider wspiera tylko  modele w których klucz główny rekordu jest GUID-em. Spowodowane jest to faktem, że unikalny identyfikator obiektu z zewnętrznego źródła danych musi być zmapowany na identyfikator rekordu Dynamics 365 CE, który to jak powszechnie wiadomo, jest właśnie GUID-em. Implementując usługę, możemy oczywiście utworzyć dedykowany model dla zwracanych przez projektowane API danych i dokonać konwersji typu klucza. Przykładowa metoda, który możemy wykorzystać w tym celu, może wyglądać w następujący sposób:

Błędy

Konfiguracja źródła danych, adaptera ODAta v4 oraz wirtualnej encji w systemie Dynamics 365 wykracza poza zakres tego artykułu. Nie powinniście mieć jednak żadnych problemów ze znalezieniem w sieci stosownych informacji na powyższy temat. Ja natomiast przejdę od razu do tematu pierwszego wyświetlenia widoku danych w systemie Dynamics 365. Moja wirtualna encja „Item” wykorzystuje źródło, którego implementacja została opisana powyżej. Jak się domyślacie – pierwsze uruchomienie aplikacji zakończyło się wyświetleniem komunikatu błędu. Przedstawiał się on następująco:

The query specified in the URI is not valid. The limit of ‚0’ for Top query has been exceeded. The value from the incoming request is ‚250’

Powyższy błąd związany jest on ze sposobem pobierania danych udostępnianych za pomocą opisanego powyżej interfejsu przez system Dynamics 365. System ten stara się odczytać pierwsze 250 rekordów za pomocą operatora TOP. Tymczasem domyślna konfiguracja kontrolera OData4 nie wspiera użycia tego operatora. Aby umożliwić systemowi Dynamics 365 prawidłowe pobieranie danych musimy odblokować taką możliwość. Możemy zrobić to w następujących miejscach (wystarczy jedno z nich):

Definicja klasy modelu danych zwracanego przez kontroler:

[Page(MaxTop = XXX)]
public class Item
{
 //TODO…
}

WebApiConfig.cs:

config.MaxTop(XXX);

Gdzie wartość XXX powinna być liczbą całkowitą równą lub większą od 250.

Kolejny błąd, który pojawił się po naniesieniu powyższej poprawki wyglądał następująco:

The query specified in the URI is not valid. The property cannot be used in the query option

W tym przypadku sprawa wygląda bardzo podobnie. Po stronie naszego API wymagane jest odblokowanie filtrowania, sortowania i innych operacji, które są wykorzystywane przez klienta.
Robimy to ponownie w pliku WebApiConfig.cs.

config
 .Count()
 .Filter()
 .OrderBy()
 .Expand()
 .Select()

Pełen kod kontrolera przedstawia się następująco:

Natomiast konfiguracja w klasie WebConfigApi:

Oto efekty naszych prac:

Dane zwracane przez web service

 

Widok na dane w postaci wirtualnej encji systemu Dynamics 365

Na koniec ogólna uwaga: wszelkie problemy z korzystaniem z tworzonego API po stronie CRM najłatwiej jest diagnozować uruchamiając logowanie błędów po stronie serwera. Problemy związane z pobieraniem danych za pomocą „końcówki” ODAta 4 będą widoczne jako błędy pluginów dla zdarzeń Retrieve i RetrieveMultiple. Zgłaszane nieprawidłowości są najczęściej związane z niepoprawnymi mapowaniami pól, typami danych, ogólną konfiguracją lub brakującymi funkcjonalnościami po stronie zaimplementowanego API.


To na razie wszystko w tym temacie. Artykuł celowo pomija wiele istotnych kwestii takich jak np. wdrożenie usługi, uwierzytelnianie użytkowników, czy też kwestie związane z bezpieczeństwem udostępnianych danych. Mam jednak nadzieję, że będzie on jednak przydatnym punktem startowym dla osób implementujących własne API ODAta v4, które będzie później wykorzystywane przez mechanizm wirtualnych encji systemu Dynamics 365 CE.

Total Views: 264 ,

One thought on “Dynamics 365 CE, wirtualne encje i protokół OData v4

Dodaj komentarz