Ana içeriğe geç

API Proxy SOAP Metod Konfigürasyonu

SOAP Metod Konfigürasyonu​

Bu sekmede, seçilen API Proxy için
politikalar, protokol dönüşümü ayarları ve SOAP metod yönetimi işlemleri yapılabilir.

SOAP Metod Konfigürasyonu sekmesi

SOAP Metod İşlemleri​

Her API Proxy, önüne koyulduğu Backend API'nin metodları için vekil olarak çalışan kendi metodlarına sahiptir.

Eğer API Proxy, bir WSDL dosyası adresi verilerek ya da bu dosya yüklenerek oluşturulmuşsa, WSDL içerisinde tanımlı olan her metod için API Proxy üzerinde aynı isimde bir metod otomatik olarak oluşturulur.

SOAP Metot ve endpoint listesinin görüntülendiği ekran

Kullanıcılar aşağıdaki nedenlerle metodlara müdahale etmek isteyebilir:

  • Backend API'ye yeni metod(lar) eklenmesi
  • Backend API'den mevcut metod(lar)ın silinmesi
  • Backend API metod adlarının istemcilerden gizlenmek istenmesi
  • Backend API metodlarının tamamen ya da geçici olarak erişime kapatılmak istenmesi

SOAP Metod Seçme​

Metod listesinde herhangi bir metodun adına tıklandığında ilgili metod seçilir ve arayüz buna göre güncellenir:

  1. Seçilen metod listede renk değişimi ile vurgulanır.
  2. Üst orta bölümde seçili metod bilgisi gösterilir.
  3. Alt orta bölümde metod için yapılabilecek işlemler listelenir.
  4. Sağ bölümde seçilen metodun Backend API’de karşılık geldiği metod görüntülenir.
SOAP metot ve endpoint seçme ekranı

SOAP Metod Ayarları Güncelleme​

SOAP tipindeki API Proxy’lerde yalnızca metod güncelleme işlemi yapılabilir.

SOAP metodlarına ait ayarlar, REST metod ayarlarından farklıdır. Aşağıda SOAP metodlarına özel ayar alanları gösterilmektedir:

SOAP metod ayarları ekranı

SOAP Metod Ayarları Alanları​

AlanAçıklama
SOAP ActionWSDL ayrıştırılırken elde edilen SOAPAction değeri. İstenirse manuel olarak değiştirilebilir.
İndirmeyi EtkinleştirYanıt Byte Array tipinde ise dosya olarak indirilmesini sağlar.
Compressed Response için Base64 KullanSıkıştırılmış yanıtlar için Base64 encode edilmiş text kullanımını sağlar.
Re-Parse'da YoksayRe-parse işlemlerinde bu metodun güncellenmemesini sağlar.
WSA AyarıWS-Addressing ayarlarının metod bazlı aktif edilmesini sağlar.
Must UnderstandSOAP mustUnderstand alanının ayarlanmasını sağlar.
VersiyonKullanılacak WS-Addressing versiyonunu belirtir.
Add Default ActionWSDL’den gelen varsayılan action değerini kullanır.
ActionSOAP mesajına özel action eklenmesini sağlar.
Add Default ToVarsayılan To bilgisinin eklenmesini sağlar.
ToSOAP mesajına özel To alanı eklenir.
Reply ToSOAP mesajına özel yanıt adresi eklenir.
Generate Message IDHer mesaj için otomatik Message ID üretir.
Message IDSabit bir Message ID kullanır.
FromSOAP mesajına özel From bilgisi ekler.
Fault ToSOAP hata mesajları için özel adres tanımlar.
Relates ToHata mesajları için ilişki bilgisi ekler.
Cache SettingsMetod bazlı önbellek ayarlarını aktif eder.
Cache Key TypeÖnbellek anahtarının nasıl oluşturulacağını belirler.
Variable ListÖzel önbellek anahtarı oluşturmak için kullanılır.
CapacityÖnbellekte tutulabilecek maksimum yanıt sayısı.
TTLÖnbellek geçerlilik süresi (saniye).
Cache Null ValueBoş yanıtların önbelleğe alınmasını sağlar.

MTOM / Ekler Ayarları​

Metot ayarları penceresi dört bölümden oluşur: Genel, WS-Addressing, MTOM / Ekler ve Önbellek. MTOM / Ekler bölümü, MTOM biçimindeki (multipart/related; dosya gibi ikili parçaları olan SOAP mesajı) istek ve yanıtları denetler. Bölüm yalnız SOAP tipindeki API Proxy'lerde görünür. Ayarları değiştirmediğiniz sürece davranış öncekiyle aynı kalır.

AlanAçıklama
İlk ayraçtan önceki metni (MIME preamble) silVarsayılan olarak kapalıdır. Bazı istemciler MTOM gövdesinde ilk ayraçtan önce bir MIME başlık bloğu yazar ve bazı backend'ler bu bloğu okuyamaz. Ayar açıkken ilk ayraçtan önceki metin istekten silinir, kalan byte'lar değişmez. Ayraç gövdenin ilk 32 KB'ında aranır. Ayraç bulunamazsa gövde olduğu gibi gider. Gövdeyi imzalayan istemcilerde bu ayarı açmayın.
MTOM ZorunluluğuMetodun hangi istekleri kabul ettiğini belirler. Hepsi (varsayılan): düz SOAP ve MTOM istekler. MTOM zorunlu: multipart/related olmayan istek ERR-320 hatasını (HTTP 400) alır. MTOM reddet: multipart/related istek ERR-321 hatasını (HTTP 400) alır. Kontrol, istemcinin isteği üzerinde ve istek politikalarından önce çalışır.
MTOM İstek İşlemeGateway'in istek gövdesine ne yapacağını belirler: Koru (varsayılan), Çöz (MTOM → düz SOAP) veya Kodla (düz SOAP → MTOM).
MTOM Yanıt İşlemeGateway'in backend yanıt gövdesine ne yapacağını belirler: Koru (varsayılan), Çöz (MTOM → düz SOAP) veya Kodla (düz SOAP → MTOM).
Ek Olarak Gönderilecek Elemanlar (XPath, her satıra bir tane)Kodla için kullanılır. Her satır, Base64 metni ek olacak bir elemanın XPath'idir. En az bir XPath girin.
En Küçük Ek Boyutu (byte)Kodla için kullanılır. Çözülmüş boyutu bu değerden küçük olan eleman, mesajın içinde Base64 metin olarak kalır. Boş veya 0: seçilen her eleman ek olur.

Koru​

Mesaj olduğu gibi gider. Hiçbir politikanın değiştirmediği gövde orijinal byte'larıyla gönderilir; böylece ikili parçalar bozulmaz. Bu kural sıkıştırılmış (gzip, deflate, br, zstd) gövdeler için de geçerlidir.

Metotta aktif bir istek politikası (yanıt için aktif bir yanıt politikası) varsa gateway mesajı politikalara düz SOAP olarak gösterir, sonra yeniden MTOM paketi olarak gönderir:

  • Politikalardan önce her xop:Include elemanının yerine ekin Base64 metni konur ve Content-Type SOAP tipi olur. XML Schema Validation, XSLT, WS-Security ve script normal XML okur.
  • Hiçbir politika mesajı değiştirmediyse orijinal paket byte byte gönderilir.
  • Bir politika mesajı değiştirdiyse paketin yalnız kök parçası değişir. Aynen kalan Base64 metin yeniden xop:Include olur ve eki orijinal byte'larıyla gider. Politikanın değiştirdiği, biçimlendirdiği, şifrelediği veya sildiği Base64 metin mesajda metin olarak kalır; bu metnin orijinal eki paketten çıkarılır, böylece orijinal byte'ları gönderilmez.
  • İstemci veya backend orijinal MTOM Content-Type değerini alır.
  • Değişen mesaj XML değilse veya bir politika paketteki hiçbir parçayı göstermeyen bir xop:Include yazarsa istek ERR-322 hatasını (HTTP 400) alır; yanıtta istemci ERR-323 hatasının metnini alır.
  • Script akışı SUCCESS sonucuyla keserse (stopFlowAsSuccess) istemci politikaların yazdığı mesajı MTOM paketi olarak alır.
  • Maksimum Mesaj Boyutu politikası orijinal paketi ölçer.

Paket okunamıyorsa, kök parça Base64 kodlu ise veya Content-Length başlığı taşıyorsa, gövde gateway'in en büyük açılmış gövde boyutunu aşıyorsa ya da metot byte array modunda çalışıyorsa gateway mesajı politikalara düz SOAP olarak göstermez. Bu durumda politikalar paketi geldiği gibi alır.

Çöz (MTOM → düz SOAP)​

Gateway, MTOM mesajını tek parça düz SOAP mesajına çevirir. Her xop:Include elemanını ekin Base64 metniyle değiştirir. Bundan sonra XML Schema Validation, XSLT, WS-Security ve script gibi XML politikaları normal XML okur.

  • İstekte Çöz, istek politikalarından önce çalışır. Yanıtta, yanıt politikalarından önce çalışır.
  • Yeni Content-Type, UTF-8 karakter setiyle text/xml veya application/soap+xml olur.
  • MTOM olmayan mesaj değişmeden devam eder.
  • Gateway paketi doğrular. Her Content-ID benzersiz olmalı, her cid: referansı paketteki bir parçayı göstermeli ve kök parça geçerli XML olmalıdır. Sonucun boyutu gateway'in en büyük açılmış gövde boyutu ayarıyla sınırlanır.
  • Doğrulama başarısız olursa istek ERR-322 hatasını (HTTP 400) alır. Backend yanıtı ERR-323 hatasını (HTTP 502) alır.
  • Maksimum Mesaj Boyutu politikasının limitleri istemcinin orijinal isteğinden okunur; bu yüzden Çöz bu limitleri aşmaz.

Kodla (düz SOAP → MTOM)​

Gateway, düz SOAP mesajında seçilen Base64 elemanlarını MTOM eklerine çevirir.

  • İstekte Kodla, istek politikalarından sonra ve gateway isteği backend'e göndermeden önce çalışır. Yanıtta, yanıt politikalarından sonra çalışır.
  • Yalnız metni kanonik Base64 olan (boşluk veya satır sonu içermeyen) ve çözülmüş boyutu en küçük boyuta ulaşan eleman taşınır. Diğer elemanlar mesajın içinde kalır.
  • Zaten MTOM olan mesaj değişmez.
  • Mesaj XML değilse veya bir XPath çalışmazsa gateway loga uyarı yazar ve mesajı değiştirmeden gönderir. Base64 metinli düz SOAP mesajı geçerli bir mesajdır.
  • XPath listesi boşsa veya metotta WS-Addressing açıksa Kodla seçeneğini kaydedemezsiniz.
XPath ifadeleri

Bu XPath ifadelerinde namespace önekleri tanımlı değildir. local-name() veya Q{namespace}ad biçimini kullanın. Örnek: //*[local-name()='Content'].

Bilinen sınırlar​

  • Koru seçeneğinde, mesajı XML dışı bir biçime çeviren politika (örneğin XML'den JSON'a) ERR-322 veya ERR-323 hatasını alır, çünkü gateway MTOM paketi göndermek zorundadır. Bu metotlarda Çöz seçeneğini seçin.
  • Koru seçeneğinde, Maksimum Mesaj Boyutu politikasından önce çalışan bir politika gövdeyi büyütürse bu politika yine orijinal paketi ölçer.
  • Çöz, hiçbir xop:Include elemanının göstermediği parçayı (SOAP with Attachments parçası) atar.
  • Koru seçeneğinde ikili ek byte'ları içeren yanıt, yanıt önbelleğine yazılmaz; sonraki çağrı aynı byte'ları backend'den alır. Bu yanıtları önbelleğe alma 2027.01.0 sürümü için planlanmıştır.
  • WS-Addressing ve MTOM birlikte çalışmaz. WS-Addressing ayarları başlıklarını MTOM paketine ekleyemez ve WS-Addressing açıkken Kodla seçeneği kaydedilemez.
  • Çöz ve Kodla, stream veya indirme olarak gönderilen yanıtta uygulanmaz.
  • Backend'in MTOM yanıtı geçerli değilse istemci ERR-323 metnini alır. Backend kendi 4xx/5xx durumunu döndürdüyse bu durum kalır; aksi hâlde durum HTTP 502 olur.

Hata kodları için Hata Mesajları sayfasına bakın. Trafik logundaki MTOM kayıtları için API Trafiği sayfasına bakın.

SOAP Metod Silme​

SOAP API Proxy'lerinde metodlar silinemez. Bir metodu erişime kapatmak için aşağıdaki devre dışı bırakma işlemi kullanılır.

SOAP Metod Geçici Olarak Kullanımdan Kaldırma​

Bir metod silinmeden erişime kapatılabilir. Bunun için Endpoint'i Devre Dışı Bırak seçeneği kullanılır.

Bu işlem sonrası:

  1. Metod simgesi devre dışı durumunu gösterecek şekilde değişir.
  2. Endpoint'i aktifleştir seçeneği görünür hale gelir.
SOAP metodun devre dışı bırakılması ekranı

SOAP Metod Test Etme​

  1. Endpointler Görüntülenir
    (Test Method) kullanılarak ilgili SOAP endpoint’leri görüntülenebilir ve test edilebilir.
SOAP endpoint listesinin görüntülendiği Test Method ekranı
  1. Test Method
    Test Method kullanılarak ilgili SOAP servisleri XML (SOAP Envelope) formatında manuel olarak test edilebilir.
SOAP servislerinin XML request ile manuel olarak test edildiği ekran

Bir API Proxy en az bir ortama yüklenmişse, metodlar bu sekme üzerinden kolayca test edilebilir.
Metodu Test Et (Test Method) bağlantısına tıklandığında ilgili metod için Test Konsolu açılır.

Sonraki Adımlar​