FatihGörgülü

TROIA Web Service Rehberi: Session, callService, Encryption ve Response Yapısını Anlamak

TROIA Web Service, CANIAS ile dış sistemler arasında çalışan sade ama kritik bir köprü. Bu rehber; oturum açma, callService akışı, XML parametreleri, response okumayı ve şifreleme/sıkıştırma ayrımlarını sahada en çok karışan noktalar üzerinden netleştirir.

İçindekiler

TROIA Web Service'e hızlı bakış

Akışın özü basit: login ile oturum açılır, callService ile TROIA sınıf metodu çalıştırılır, CaniasResponse ile dönüş okunur. Ama sahada, küçük teknik detaylar çoğu zaman büyük entegrasyon hatalarına dönüşür.

  • login() yalnızca oturum açar; iş callService() ile yapılır.
  • callService() her çağrıda SessionId ve SecurityKey ister.
  • Response tek string değildir; CaniasResponse içinde çoklu alan vardır.
  • Encryption ve compression isteğe bağlıdır; sırayı ve flag'leri doğru yönetmek gerekir.

login(): oturum ve güvenlik anahtarı

login() başarılı olduğunda SessionId ve SecurityKey döner. SessionId oturumu, SecurityKey ise istemcinin doğrulandığını gösterir.

  • SessionId tüm callService çağrılarında taşınmalı.
  • SecurityKey her çağrıda gönderilmeli; aksi halde çağrı reddedilir.
  • Encrypted bayrağı true ise sunucu EncryptionKey üretir.
  • Compression niyetini oturumda doğru beyan etmek, sonraki çağrılarda uyumu kolaylaştırır.

callService(): servis çağrısının merkezi

callService(), kayıtlı bir TROIA sınıf metodunu çalıştırır ve CaniasResponse döner. Yanlış ServiceId, eksik güvenlik anahtarı veya hatalı Parameters XML en sık hata kaynağıdır.

  • ServiceId, hangi TROIA metodunun çalışacağını belirler.
  • Parameters, XML string olarak gönderilir.
  • Compressed ve Permanent bayrakları, davranışı etkiler.
  • ExtraVariables ve RequestId, izleme ve tanılama için kritik ipuçlarıdır.

Parameters XML: primitive, base64 ve CDATA

Parameters alanı XML string'dir. Her parametre <PARAM> ile taşınır. encoding='base64' kullanıldığında sistem değeri UTF-8 olarak çözümler. Özel karakterler için CDATA güvenli bir tercihtir.

  • Basit tiplerde type attribute gerekmez.
  • Base64 parametreler UTF-8'e çözülür.
  • CDATA, özel karakter içeren alanlarda parser sorununu azaltır.
  • Varsayılan encoding: plain.

Table ve vector parametreleri

Table veya vector geçirmek istediğinizde <PARAM> içine TYPE bilgisi eklemek gerekir. Sunucu bu XML'den uygun sembolü üretir.

  • TYPE="TABLE" kullanıldığında satır/kolon yapısı gönderilir.
  • TYPE="VECTOR" ile name/type/value üçlüsü taşınır.
  • Vector içinde primitive tipler kullanılabilir (string, long, date vb.).
  • XML hiyerarşisi bozulursa parametre parse edilemez.

CaniasResponse nasıl okunur?

callService() tek bir string değil, CaniasResponse döner. Response, SYSStatus, SYSStatusError, Messages ve ExtraVariables birlikte okunmalıdır.

  • Response alanı StringResponse tipindedir; Compressed bayrağı varsa açılmalıdır.
  • SYSStatus, TROIA tarafında son durum değerini verir.
  • Messages alanı, çalışma sırasında üretilen TROIA mesajlarını taşır.
  • ExtraVariables, istenen değişkenleri XML formatında döndürür.
  • RequestId, çağrı eşlemesi için geri döner.

Encryption: ne zaman, nasıl?

Encryption varsayılan değildir; login sırasında talep edilmelidir. EncryptionKey sunucudan gelir, UTF-8 byte dizisine çevrilir ve AES/CBC/PKCS7/128 yapılandırmasıyla kullanılır.

  • Encrypted bağlantıda Parameters string'i şifrelenir.
  • Response çözmek için Base64 → byte → decrypt → UTF-8 adımları gerekir.
  • EncryptionKey'i byte dizisine çevirmeden kullanmak sık hata kaynağıdır.
  • Şifreleme istemiyorsanız Encrypted=false bırakılmalıdır.

Compression: eşik ve sıraya dikkat

Compression, yanıt uzunluğu eşik değeri aştığında devreye girer. Sistem, şifreli veriye compression uygulamaz. Hem encryption hem compression kullanılıyorsa istemci sıralamayı doğru kurgulamalıdır.

  • Compressed=true ise Base64 → byte → decompress → UTF-8 adımı gerekir.
  • Yanıt 4000 karakter üzerindeyse sıkıştırma devreye girebilir.
  • Şifreli bağlantıda parametre sıkıştırılıyorsa önce şifrele, sonra sıkıştır.
  • Sunucu şifreli response'u sıkıştırmaz.

Hızlı referans: alanlar ve işaretler

Saha için kısa kontrol listesi. En çok unutulan alanları tek yerde özetler.

  • login response: Success, SessionId, SecurityKey, ErrorMessage, EncryptionKey.
  • callService input: SessionId, SecurityKey, ServiceId, Parameters, Compressed, Permanent, ExtraVariables, RequestId.
  • CaniasResponse: Response (Value/Compressed), SYSStatus, SYSStatusError, Messages, ExtraVariables, RequestId.
  • Parameters XML: <PARAMETERS><PARAM encoding="base64">...</PARAM></PARAMETERS>.
  • ExtraVariables/Messages dönüşleri XML formatındadır.

XML template pack (kısa şablonlar)

Kopyala-uyarla kullanımı için kısa iskeletler.

  • Basic: <PARAMETERS><PARAM>value</PARAM></PARAMETERS>
  • Base64: <PARAM encoding="base64">cGFyYW0x</PARAM>
  • Table: <PARAM TYPE="TABLE"><TABLE_NAME><ROW><COL1>...</COL1></ROW></TABLE_NAME></PARAM>
  • Vector: <PARAM TYPE="VECTOR"><VECTOR_NAME><ITEM><NAME>...</NAME><TYPE>STRING</TYPE><VALUE>...</VALUE></ITEM></VECTOR_NAME></PARAM>
  • ExtraVariables isteği: "VAR1,VAR2,VAR3" (virgülle).

İlgili sayfalar:

Bu sayfa kime daha anlamlı

  • TROIA Web Service ile çalışan entegrasyon geliştiricisi
  • Session, callService ve response yapısına ilk bakan teknik ekip
  • Canias dışı sistemden TROIA tarafına geçen mimar

Konuşmak ne zaman mantıklı

Aşağıdakilerden biri tanıdık geliyorsa, kısa bir konuşma okumaktan daha yararlı olabilir.

  • Entegrasyon yazıldı ama çerçeve hâlâ dağınık hissediyor.
  • Session, encryption veya compression kararları tekrar tekrar konuşuluyor.
  • Teknik ekip ile iş tarafı aynı dili bulmakta zorlanıyor.

TROIA rehberinden sonra

Teknik rehberden sonra en faydalı devam, ilgili teknik insight ve talep halinde paylaşılabilecek kaynaklardır.

İlgili okuma

TROIA callService()

Session, parametreler ve response mantığını daha hızlı okumak için.

Devam et →

İlgili okuma

TROIA encryption & compression

Sahada en çok karışan teknik başlığı ayrı okumak için.

Devam et →

İlgili kaynak

Kaynaklar ve checklistler

Checklist, cheat sheet veya paylaşılabilir teknik materyal gerekiyorsa kaynaklar yüzeyine geçin.

Devam et →

İlgili yazılar ve kaynaklar

İlgili yazılar burada listelenecek.

TROIA Web Service Rehberi: Session, callService, Encryption ve Response Yapısı | Fatih Görgülü