Custom API Geliştirme

Giriş

Dataverse, Create, Update, Delete, Retrieve ve RetrieveMultiple gibi standart mesajların yanı sıra, geliştiricilerin kendi özel mesajlarını tanımlamasına da izin verir. Bu özel mesajlara Custom API denir. Bir Custom API, belirli bir iş mantığını kapsayan, parametre alabilen ve yanıt dönebilen, standart Dataverse mesajları gibi davranan bir uç noktadır. Plugin ile desteklendiğinde, dış sistemlerden veya Power Automate’ten tek bir çağrıyla karmaşık işlemleri tetiklemek mümkün olur. Bu yazıda, Custom API’nin yapısı, parametre tanımlama, plugin ile bağlama ve API’yi çağırma adımları ele alınmaktadır.

Custom API Nedir?

Custom API, Dataverse’te customapi tablosunda bir kayıt olarak tanımlanan özel bir mesajdır. Standart bir Dataverse mesajı gibi bir adı (Unique Name), parametreleri ve bağlı olduğu bir plugin’i vardır. API çağrıldığında, bağlı plugin tetiklenir ve iş mantığı çalışır.

Custom API’ler, aşağıdaki senaryolarda standart mesajlara göre avantaj sağlar:

Bir Custom API çağrısı, standart bir Dataverse mesajı gibi Organization Service üzerinden, Web API üzerinden veya Power Automate’in "Perform an unbound action" adımıyla yapılabilir.

Custom API Kaydı Oluşturma

Bir Custom API, Maker Portal’dan veya doğrudan Dataverse tablolarına kayıt eklenerek oluşturulabilir. Maker Portal’da, Çözümler bölümünde bir çözümün içine girilip "Yeni > Daha Fazla > Custom API" yolu izlenir. Açılan formda şu alanlar doldurulur:

Form kaydedildiğinde, Dataverse’te bir customapi kaydı oluşur. Bu kayıt, API’nin iskeletidir; henüz bir iş mantığı içermez.

Parametre Tanımlama

Bir Custom API, isteğe bağlı olarak giriş (input) ve çıkış (output) parametreleri alabilir. Her parametre, customapirequestparameter veya customapiresponseproperty tablosunda bir kayıttır.

Giriş parametresi tanımlamak için, Custom API kaydının altındaki "Custom API Request Parameters" alt listesine yeni bir kayıt eklenir:

Çıkış parametresi (response property) tanımlamak için benzer şekilde "Custom API Response Properties" alt listesine kayıt eklenir. Plugin, bu parametreye bir değer yazar ve çağrıyı yapan taraf bu değeri okuyabilir.

Plugin ile Bağlama

Custom API’nin iş mantığını yürütecek plugin, standart bir plugin ile aynı şekilde yazılır. Farkı, Plugin Registration Tool’da step kaydederken mesaj olarak Custom API’nin adının seçilmesidir.

Aşağıdaki örnek, iki sayıyı toplayıp sonucu dönen bir Custom API plugin’idir:

using System;
using Microsoft.Xrm.Sdk;

namespace SamplePlugin
{
    public class HesaplaIndirimPlugin : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            IPluginExecutionContext context =
                (IPluginExecutionContext)serviceProvider.GetService(
                    typeof(IPluginExecutionContext));

            // Giriş parametrelerini oku
            decimal indirimOrani = (decimal)context.InputParameters["IndirimOrani"];
            decimal tutar = (decimal)context.InputParameters["Tutar"];

            // İş mantığı
            decimal indirimTutari = tutar * (indirimOrani / 100);
            decimal netTutar = tutar - indirimTutari;

            // Çıkış parametrelerini yaz
            context.OutputParameters["IndirimTutari"] = indirimTutari;
            context.OutputParameters["NetTutar"] = netTutar;
        }
    }
}

Bu plugin yazılıp derlendikten sonra, Plugin Registration Tool ile Dataverse’e kaydedilir. Step oluşturulurken şu değerler seçilir:

Custom API’ler için Pre-Validation ve Pre-Operation aşamaları da kullanılabilir. Pre-Operation’ta plugin, işlem veri tabanına yazılmadan önce çalışır ve işlemi iptal edebilir. Post-Operation’ta ise işlem çoktan tamamlanmıştır; çıkış parametreleri yazılabilir.

Custom API mesajına plugin kaydedildikten sonra, API kullanıma hazırdır.

Custom API’yi Çağırma

Custom API, çeşitli yollarla çağrılabilir. En yaygın yöntemler şunlardır:

OrganizationRequest request = new OrganizationRequest("crmserisi_HesaplaIndirim");
request["IndirimOrani"] = 15m;
request["Tutar"] = 1000m;

OrganizationResponse response = service.Execute(request);

decimal indirimTutari = (decimal)response["IndirimTutari"];
decimal netTutar = (decimal)response["NetTutar"];

POST /api/data/v9.2/crmserisi_HesaplaIndirim HTTP/1.1
Content-Type: application/json

{
    "IndirimOrani": 15,
    "Tutar": 1000
}

{
    "IndirimTutari": 150,
    "NetTutar": 850
}

Sınırlar

Custom API, plugin yazılabilecek her türlü senaryoyu destekler; ancak bazı sınırları vardır:

Sonuç

Custom API, Dataverse’te kendi özel mesajlarınızı tanımlamanıza ve bunları plugin ile destekleyerek karmaşık iş mantığını tek bir çağrıya kapsüllemenize olanak tanır. Giriş ve çıkış parametreleriyle zenginleştirilebilen bu yapı, dış sistemler, Power Automate akışları ve diğer plugin’ler için temiz bir arayüz sağlar. Standart mesajların yetersiz kaldığı her noktada, Custom API güçlü bir alternatiftir. Bir sonraki yazıda, plugin’lerin performans optimizasyonu konusu ele alınacaktır.