Az előző bejegyzésben megismerkedtünk a custom action létrehozásának lehetőségével, amivel egyedi „message” alapján futtathatunk egyedi üzleti logikát. A Microsoft egy újabb és jobban testreszabhatóbb eszközt is adott a fejlesztők kezébe, amivel akár kiválthatók a custom action-ök, ez pedig a Custom API létrehozása Dataverse-ben.

Főbb különbségek

Mivel a lényege ugyanaz, így célszerű a custom action-höz hasonlítani a custom API-t, az előre megemlítendő eltérések:

• A custom API beállítható privátnak vagy publikusnak,
• A típusa lehet „Function” vagy „Action” („Is Function” switch),
• Korlátozható a workflow-ban használhatósága,
• Egyszerű plugin regisztráció elég hozzá, nem kell a step létrehozása, így akár meglévő plugin is „API-sítható” és
• Nem „process” rekordot kell létrehoznunk, mert erre van egy külön „Custom API” tábla.

Custom API létrehozása

Most pedig nézzük meg, hogy hogyan tudnánk a korábban custom action-ként regisztrált logikát custom api-ként implementálni.

Plugin

A korábbi kódunkban beadtunk egy szöveget, amit nagy betűssé konvertáltunk:

using Microsoft.Xrm.Sdk;
using System;

namespace kogerohu.Actions
{
    public class TextToUpperCase : IPlugin
    {
        /// <summary>
        /// Action to convert an input text to upper case and return
        /// </summary>
        public void Execute(IServiceProvider serviceProvider)
        {
            IPluginExecutionContext executionContext = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

            var inputText = (string)executionContext.InputParameters["inputText"];

            if (string.IsNullOrWhiteSpace(inputText)) return;

            var outputText = inputText.ToUpper();

            executionContext.OutputParameters["outputText"] = outputText;
        }
    }
}

A kód és a VS projekt megtalálható a GitHub-omon.

Custom API rekord létrehozása

Lássunk hozzá a létrehozáshoz a maker portálon, egy solution-t kiválasztva navigáljunk végig a „New > More > Other > Custom API” pontra:

A kiválasztását követően új fülön megnyílik a következő űrlap, amit töltsünk ki ügyelve arra, hogy a kötelező mezők megfeleljenek a kritériumoknak:

1. A „Unique Name” jelenleg egy egyszerű szöveges mező, de tartalmaznia kell egy publisher prefix-et!
2. Jelen esetben a „Bindig Type” legyen „Global” (hasonlóan az custom action-höz).
3. „Plugin Type” kereső mezőben állítsuk be a plugin-t, amit futtatni szeretnénk.

A „PluginType” mezőben az assembly-ra hivatkozás következtében létrehozza a rendszer nekünk a kapcsoldó plugin step-ünket:

Főbb tulajdonságok és limitációk

Unique Name	Logikai név, elején egy valós publisher prefix-szel
Binding type	Global / Entity / Entity collection Az action-höz hasonlóan szintén hozzáköthető egy táblához vagy lehet globális.
Bound entity Logical Name	Ha a „Bindig type” nem „Global”, akkor a kiválasztott tábla logikai neve.
Is Function	Yes / No Function: HTTP GET metódussal hívható meg, adatváltoztatás nem történik, query parameter-ekkel az URL-ben passzolhatók át a bemenő adatok, ha vannak. Korlátok: – Az URL max. 2000 karakter hosszú lehet. Túllépés esetén érdemes Action-t használni. – Nem használható Workflow-khoz – Nem használható Power Automate-ben (unbound / bound action művelettel) – Kimenő paraméter beállítása nélkül nem használható Action: HTTP POST-tal hívható meg, body-ban küldhetők a paraméterek.
Is Private	Yes / No Bekapcsolva csak az Owner számára elérhető. Teszteléshez hasznos vagy fejlesztés során, később átállítható Yes-re.
Enabled for Workflow	Yes / No Workflow-ban meghívható step-ként, mint a custom action. „Yes” esetén nem lehet function!
Allowed Custom Processing step Type	None / Async Only / Sync and Async Korlátozható, hogy milyen módon legyen futtatható.
Execute Privilege Name	Jogosultsághoz köthető a futtatása. Létező jogosultságok használhatók jelenleg vagy egyedi táblát létrehozva annak a jogosultságához köthető. (Security role-oknál ezeket állítjuk, a sajtokkal / torta szeletekkel.) Tehát például, ha van egy „koger_license” táblánk akkor, ha annak a read jogára állítanánk a „prvReadkogero_license” kerülne beállításra.
Plugin Type	Itt tallózhatjuk ki a logikát, azaz a plugin-t, amit meg szeretnénk futtatni.

Paraméterek létrehozása

A be- és kimenő paramétereket külön rekordokként kell létrehozni a custom API-nkhoz.

Bemenő paraméter

A bemenő paramétert a „Custom API Request Parameter” táblán kell bejegyeznünk, ami a mi esetünkben az „inputText” lesz. Ügyeljünk rá, hogy a „Unique Name” egyezzen azzal, amit az „InputParameters”-ből nyerünk ki a kódban.

Kimenő paraméter

A kimenő paramétert a „Custom API Response Property” táblán kell bejegyeznünk, ami a mi esetünkben az „outputText” lesz. Ügyeljünk rá, hogy a „Unique Name” egyezzen azzal, amit az „OutputParameters”-hez adunk hozzá a a kódunk végén.

Tesztelés

Mivel egy „function” típusú custom API-nk van, ezért HTTP GET hívással meg tudjuk futtatni böngészőből. Az URL az én környezetemmel:

https://org2b160094.crm4.dynamics.com/api/data/v9.2/koger_convert_to_uppercase(inputText=’PowerApps’)

Figyeljük meg, hogy hogyan passzoltam át a paramétert a zárójelben. Több paraméter esetén vesszővel elválasztva kell őket felsorolni a zárójelen belül.

A kapott válasz:

{
"@odata.context": "https://org2b160094.crm4.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.koger_convert_to_uppercaseResponse",
"outputText": "POWERAPPS"
}

Sikeresen visszakaptuk a nagy betűsre konvertált szövegünket az „outputText” property-ben.

Összefoglalás

Sikeresen készítettünk egy Custom API-t, ami egy plugin-t hív meg. Áttekintettük a lehetséges konfigurációkat és megnéztük, hogy hogyan lehet meghívni egy funkció típusú custom API-t böngészőből. Így most már újrahasználható API-nk lehet, amit elérhetővé tehetünk akár minden fejlesztő számára!

Forrás

1. https://learn.microsoft.com/en-us/power-apps/developer/data-platform/custom-api