Dynamics 365’te Xrm.WebApi ile Temel Kayıt Sorgulama

Web resource’larda kayıt sorgulama için en çok Xrm.WebApi.retrieveMultiple kullanılıyor ama filtreleme ($filter), alan seçimi ($select) ve ilişkili kayıt çekme ($expand) syntax’ı başta kafa karıştırabiliyor. Bu yazıda temel kalıplara ve sık yapılan hatalara göz atıyoruz.

Temel Sorgu Yapısı

Xrm.WebApi.retrieveMultipleRecords(
  "contact",
  "?$select=fullname,emailaddress1&$filter=statecode eq 0"
).then(function (result) {
  result.entities.forEach(function (contact) {
    console.log(contact.fullname);
  });
});

• İlk parametre entity’nin logical name‘i (şema adı değil — Contact değil, contact).
• Query string mutlaka ? ile başlar.
• $select yazmazsan tüm alanlar döner — performans için gereksiz.

Filtreleme Örnekleri

Belirli bir account’a bağlı aktif contact’lar:

"?$select=fullname&$filter=_parentcustomerid_value eq " + accountId + " and statecode eq 0"

• Lookup alanları filtrelerken alan adının başına _ ve sonuna _value eklenir: parentcustomerid → _parentcustomerid_value.
• GUID’ler tırnak içine alınmaz, doğrudan yazılır.

Tarih bazlı filtreleme:

"?$filter=createdon ge 2026-01-01T00:00:00Z"

İlişkili Kayıt Çekme ($expand)

"?$select=fullname&$expand=parentcustomerid_account($select=name,accountnumber)"

Bu, her contact ile birlikte bağlı olduğu account’un adını ve numarasını tek istekte getirir — ayrı bir retrieveRecord çağrısına gerek kalmaz.

Sık Yapılan Hatalar

• Schema name ile logical name’i karıştırmak. Entity ismi her zaman küçük harf logical name olmalı (Account değil account).
• $filter içinde string değerleri tırnak içine almamak. Metin alanları için eq 'Aktif' gibi tek tırnak şart; sayısal ve GUID alanlarda tırnak kullanılmaz.
• Büyük veri setlerinde $top kullanmamak. WebAPI varsayılan olarak sayfa başına genelde 5000 kayıtla sınırlı (Prefer: odata.maxpagesize header’ı ile bu değiştirilebilir); $top ile sınırlamazsan gereksiz veri çekilir.
• _value son ekini unutmak. Lookup alan filtrelemede en sık yapılan syntax hatası budur — sorgu hata vermez ama sonuç boş döner.