Kullanıcı Kılavuzu İptal

Acrobat Sign Web Kancasına genel bakış

 İçindekiler

Adobe Acrobat Sign Kılavuzu

Yenilikler

Başlayın

Yönetim

Sözleşmeleri Gönderme, İmzalama ve Yönetme

Gelişmiş Sözleşme Özellikleri ve İş Akışları

Diğer ürünlerle entegrasyon

Acrobat Sign Developer

Destek ve Sorun Giderme

Genel Bakış

Web kancası, kaynak sitede (bu durumda Adobe Acrobat Sign) belirli bir olay meydana geldiğinde tetiklenen kullanıcı tanımlı bir HTTPS isteğidir.

Web kancası, veri veya veri akışını kabul eden bir REST hizmetidir.

Web kancaları, bir PUSH modelinde hizmetten hizmete iletişime yöneliktir.

Acrobat Sign, abone olunan olay tetiklendiğinde JSON gövdesine sahip bir HTTPS POST oluşturur ve bunu belirtilen URL'ye gönderir.

Web kancalarını yapılandırmadan önce ağınızın işlevsellik için gereken IP aralıklarını kabul ettiğinden emin olun.

 13.3 Genel

Web kancaları, önceki geri çağırma yöntemine kıyasla pek çok avantaj sunar. Bunlardan bazıları şunlardır:

  • Yöneticiler, geri çağırma URL'sini listelemek için Acrobat Sign desteğini dahil etmek zorunda kalmadan kendi web kancalarını etkinleştirebilir
  • Web kancaları veri "tazeliği, iletişim verimliliği ve güvenlik açısından daha iyidir. Sorgulama gerekmez
  • Web kancaları, farklı kapsam düzeylerine (Hesap/Grup/Kullanıcı/Kaynak) kolayca izin verir. 13.3 Genel
  • Web kancaları, modern uygulamalara daha kolay yapılandırma sağlayan daha anlaşılır bir API çözümüdür
  • Geri Çağırmaların benzersiz olması gereken kapsam (Hesap/Grup/Kullanıcı/Kaynak) başına birden fazla web kancası yapılandırılabilir
  • Geri çağırmaların "ya hep ya hiç" çözümü olduğu yerde web kancaları, döndürülecek verilerin seçimine izin verir
  • Web kancası ile taşınan meta veriler yapılandırılabilir (Temel veya Ayrıntılı)
  • Kullanıcı arabirimi tamamen yöneticinin kontrolünde olduğundan web kancalarını oluşturmak, düzenlemek veya devre dışı bırakmak çok daha kolaydır.
Not:

Bu belge, özellikle Acrobat Sign web uygulamasındaki (önceki adıyla Adobe Sign) Web Kancalarının kullanıcı arabirimine odaklanır.

API ayrıntılarını öğrenmek isteyen geliştiriciler daha fazla bilgiyi burada bulabilir:

Ön koşullar

Hizmetin çalışması için ağ güvenliğiniz aracılığıyla web kancalarına yönelik IP aralıklarına izin vermeniz gerekir.

REST v5'teki eski geri çağırma URL hizmeti, web kancası hizmetiyle aynı IP aralıklarını kullanır.

Yöneticiler, kullanıcı eklemek için Adobe Admin Console'da oturum açabilir. Oturum açtıktan sonra yönetici menüsüne gidin ve Web Kancaları
öğesine ilerleyin.

Nasıl kullanılır?

Yöneticiler öncelikle Acrobat Sign'dan gelen push'u kabul etmeye hazır bir web kancası hizmetine sahip olmalıdır. Bu konuda pek çok seçenek vardır. İlgili hizmet POST ve GET isteklerini kabul edebildiği sürece web kancası başarılı olur.

Acrobat Sign yöneticisi, hizmet başlatıldıktan sonra Acrobat Sign sitesinin Hesap menüsündeki Web Kancası arabiriminden yeni bir web kancası oluşturabilir.

Yöneticiler, web kancasını Sözleşme, Web formu (Widget) veya Toplu Halde Gönderme (MegaSign) olaylarını tetikleyecek şekilde yapılandırabilir. Kitaplık Şablonu (Kitaplık Belgesi) kaynağı API aracılığıyla da yapılandırılabilir.

Web kancasının kapsamı, yönetici arabirimi aracılığıyla tüm hesabı veya bireysel grupları içerebilir. API, KULLANICI veya KAYNAK kapsamları tercihleri sayesinde daha fazla ayrıntılı seçim olanağı sağlar.

URL'ye gönderilen veri türü yapılandırılabilir ve Sözleşme Bilgileri, Katılımcı Bilgileri, Belge Bilgileri vb. öğeleri içerebilir.

Web kancası yapılandırılıp kaydedildikten sonra Acrobat Sign, abone olunan olayı her tetiklendiğinde tanımlanan URL'ye yeni bir JSON nesnesi gönderir. Olay tetikleme kriterlerini veya JSON yükünü değiştirmek istemediğiniz sürece web kancasının sürekli olarak değiştirilmesi gerekmez.

Web kancası URL'sinin amacını doğrulama

Acrobat Sign, bir web kancasını başarıyla kaydetmeden önce kayıt isteğinde sağlanan web kancası URL'sinin bildirim almayı isteyip istemediğini doğrular. Bu amaçla, Acrobat Sign yeni bir web kancası kayıt isteği aldığında, ilk olarak web kancası URL'sine bir doğrulama isteği gönderir. Bu doğrulama isteği, web kancası URL'sine gönderilen bir HTTPS GET isteğidir. Bu istekte özel bir HTTP üstbilgisi olan X-AdobeSign-ClientId vardır. Bu üstbilgideki değer, web kancasını oluşturmak/kaydetmek isteyen API uygulamasının istemci kimliği (Uygulama Kimliği) olarak ayarlanır. Web kancasını başarıyla kaydetmek için web kancası URL'sinin bu doğrulama isteğine 2XX yanıt koduyla karşılık vermesi VE ayrıca, aynı istemci kimliği değerini aşağıdaki iki yoldan biriyle geri göndermesi:

  • Yanıt üstbilgisinde X-AdobeSign-ClientId. Bu, istekte iletilen ve yanıt olarak tekrar yansıtılan üstbilgiyle aynıdır.
  • Alternatif olarak, xAdobeSignClientId anahtarına ve istekte gönderilen istemci kimliğiyle aynı değere sahip olacak şekilde JSON yanıt gövdesinde iletilir.

Web kancası, yalnızca başarılı bir yanıtta (2XX yanıt kodu) ve üstbilgide ya da yanıt gövdesinde müşteri kimliğinin doğrulanmasında başarıyla kaydedilecektir. Bu doğrulama isteğinin amacı, web kancası URL'nizin o URL'de bildirim almak istediğini göstermektir. Yanlış URL girdiğinizde URL, amaç isteğinin doğrulanmasına doğru şekilde yanıt veremez ve Acrobat Sign bu URL'ye hiçbir bildirim göndermez. Ayrıca web kancası URL'si, yalnızca belirli bir uygulamanın kaydettiği web kancaları aracılığıyla bildirim alacağını da doğrulayabilir. Bu işlem, X-AdobeSign-ClientId üstbilgisinde iletilen uygulamanın istemci kimliğini doğrulayarak yapılabilir. Web kancası URL'si bu istemci kimliğini tanımazsa başarılı yanıt koduyla yanıt vermemesi GEREKİR ve Acrobat Sign, URL'nin bir web kancası olarak kaydedilmemesine dikkat eder.

Web kancası URL çağrısının doğrulaması aşağıdaki senaryolarda gerçekleştirilir:

  • Web Kancasını Kaydetme: Web kancası URL çağrısının bu doğrulaması başarısız olursa web kancası oluşturulmaz.
  • Web Kancasını Güncelleme: ETKİN DEĞİL-ETKİN: Web kancası URL çağrısının bu doğrulaması başarısız olursa web kancası durumu ETKİN olarak değiştirilmez.

Web kancası bildirimine yanıt verme

Acrobat Sign, web kancası URL'sine gönderilen her web kancası bildirim isteğinde örtük bir amaç doğrulaması gerçekleştirir. Bu nedenle, her web kancası bildirimi HTTPS isteği, X-AdobeSign-ClientId adlı özel HTTP üstbilgisini de içerir. Bu üstbilginin değeri, web kancasını oluşturan uygulamanın istemci kimliğidir (Uygulama Kimliği). Web kancası bildiriminin başarılı bir şekilde teslim edildiğini ancak ve ancak, bir başarılı yanıt (2XX yanıt kodu) döndürülürse ve istemci kimliği, HTTP üstbilgisinde (X-AdobeSign-ClientId) veya JSON yanıt gövdesi aracılığıyla xAdobeSignClientId anahtarına ve müşteri kimliğiyle aynı değere sahip şekilde gönderilirse kabul ederiz. Aksi takdirde, yeniden denemeler bitene kadar bildirimi web kancası URL'sine göndermeyi yeniden deneriz.

Etkinleştirme veya devre dışı bırakma

Web Kancaları özelliğine erişim, işletme düzeyi hesaplar için varsayılan olarak etkindir.

Grup düzeyindeki yöneticiler yalnızca kendi gruplarında çalışan Web Kancalarını oluşturabilir veya kontrol edebilir.

Web Kancaları sayfasına erişim, Yönetici menüsünün sol tarafında bulunabilir.

Web kancaları sekmesine gitme

Eş zamanlı işlem tabanlı hız sınırlaması

Web kancası (ve geri çağırma) oluşturma ve bildirim olayları, Acrobat Sign sisteminden müşteriye etkin bir şekilde gönderilen eş zamanlı bildirimlerin sayısıyla sınırlıdır. Bu sınır, hesap içindeki tüm grupları kapsayacak şekilde hesap için geçerlidir.
Bu hız sınırlama türü, kötü tasarlanmış bir hesabın orantısız miktarda sunucu kaynağı kullanmasını ve dolayısıyla bu sunucu ortamındaki diğer tüm müşterilerin olumsuz etkilenmesini engeller.

Hesap başına düşen eş zamanlı olay sayısı, iyi davranan web kancalarına sahip hesapların bildirimlerini en kısa sürede almasını ve çok fazla istek nedeniyle bildirimlerin geciktiği durumlarla nadiren karşılaşmasını sağlamak için hesaplanmıştır. Mevcut eşikler şunlardır:

Eylem
(Olay)

Maksimum
eş zamanlı
olay

Açıklama

Web kancası oluşturma

10

Hesap başına en fazla 10 eş zamanlı web kancası oluşturma isteğine izin verilir.
Bu sınırı aşan istekler 429 TOO_MANY_REQUESTS yanıt kodu ile sonuçlanır.
 

Web kancası/geri çağırma bildirimi

30

Hesap başına en fazla 30 eş zamanlı web kancası ve geri çağırma bildirimine izin verilir.
Bu sınırı aşan bildirimler, teslim edilene kadar üstel geri çekilmeye göre tekrar denenir.

En İyi Uygulamalar

  • Sunucuya giden HTTPS taleplerinin sayısını sınırlamak için belirli, gerekli olaylara abone olun. Web kancalarınızı ne kadar spesifik hâle getirirseniz incelemeniz gereken hacim de o kadar azalır.
  • Yinelemelere karşı dirençli olun: Aynı web kancası URL'sini paylaşan birden fazla uygulamanız varsa ve aynı kullanıcı her uygulamayla eşlenmişse aynı olay, web kancanıza birden fazla kez gönderilir (uygulama başına bir kez). Bazı durumlarda web kancanız yinelenen olaylar alabilir. Web kancası uygulamanız buna karşı toleranslı olmalı ve olay kimliğine göre veri tekilleştirmesi yapılmalıdır.
  • Web kancalarına her zaman hızlıca yanıt verin: Uygulamanızın, web kancası isteklerine yanıt vermesi için yalnızca beş saniyesi vardır. Uygulamanızın yanıt vermek için gerçek bir iş yapması gerekmediğinden, doğrulama isteği için bu nadiren sorun teşkil eder. Ancak bildirim istekleri söz konusu olduğunda, uygulamanız bu isteğe yanıt olarak genellikle zaman alan bir işlem gerçekleştirir. Beş saniye içinde yanıt verebilmeniz için ayrı bir iş parçacığı üzerinde veya bir kuyruk kullanarak eşzamanlı olmayan bir şekilde çalışmanız önerilir
  • Eş zamanlı kullanımı yönetin: Bir kullanıcı arka arkaya birkaç değişiklik yaptığında, uygulamanızın aynı kullanıcı için neredeyse aynı anda birden fazla bildirim alması muhtemeldir. Eş zamanlı kullanımı yönetme konusunda dikkatli olmazsanız uygulamanız, aynı kullanıcı için aynı değişiklikleri birden fazla kez işleyebilir. Acrobat Sign web kancalarından yararlanmak için bilgilerin kullanımına dair net bir anlayış edinilmesi gerekir. Aşağıdaki gibi sorular sorduğunuzdan emin olun:
    • Yükte hangi verileri döndürmek istiyorsunuz?
    • Bu bilgilere kimler erişecek?
    • Hangi kararlar veya raporlar oluşturulacak?
  • İmzalanan belgeyi almayla ilgili öneriler: Belge yönetim sisteminizde, imzalanan PDF'yi Acrobat Sign'dan nasıl alacağınızı belirlerken göz önünde bulundurmanız gereken birkaç faktör vardır.

Bir web kancası oluştururken Sözleşme İmzalı Belge'nin seçilmesi tamamen kabul edilebilir olsa da tetikleyici bir olay (Sözleşme durumu tamamlandı gibi) söz konusu olduğunda belgeleri almak için Acrobat Sign API'yi kullanmayı düşünebilirsiniz.

Dikkate alınması gereken noktalar...

JSON boyut sınırlaması

JSON yük boyutu 10 MB ile sınırlıdır.

Bir olay daha büyük bir yük oluşturduğunda web kancası tetiklenir ancak koşullu parametre nitelikleri istekte mevcutsa yükün boyutunu azaltmak için kaldırılır. 

"ConditionalParametersTrimmed", bu gerçekleştiğinde istemciye conditionalParameters bilgisinin kaldırıldığını bildirmek için yanıt olarak döndürülür.

"conditionalParametersTrimmed" kırpılan anahtarlarla ilgili bilgilerin olduğu bir dizi nesnesidir.

Kesme işlemi aşağıdaki sırayla yapılır:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

İmzalanan belgeler önce kesilecek, ardından katılımcı bilgileri, belge bilgileri ve son olarak ayrıntılı bilgiler verilecektir.

Bu durum, örneğin imzalı belgeyi (taban 64 kodlu) de içeriyorsa bir sözleşme tamamlama olayında veya birden çok form alanı içeren bir sözleşmede olabilir.

Web kancası bildirimleri

Acrobat Sign web kancaları, sözleşmeyi gönderen kişiye ve sözleşmenin gönderildiği grup içinde yapılandırılan tüm web kancalarına bildirim gönderir. Hesap kapsamındaki web kancaları tüm olayları alır.

Dinleme hizmeti kapalı olduğunda tekrar deneyin

Web kancası için hedef URL herhangi bir nedenle kapanırsa Acrobat Sign, JSON'yi sıraya alır ve 72 saat boyunca aşamalı bir döngüde yeniden gerçekleştirmeyi dener.

Teslim edilmeyen olaylar tekrar deneme kuyruğunda kalır ve sonraki 72 saat içinde bildirimler mümkün olduğunca gerçekleştikleri sırayla teslim edilmeye çalışılır.

Bildirimleri yeniden teslim etmeye çalışmak için denemeler arasındaki sürenin sürekli olarak iki katına çıkarıldığı bir strateji uygulanır. Denemelere 1 dakikalık aralıklarla başlanır, daha sonra bu aralık 12 saatte bir yükselir ve böylece 72 saat içinde 15 kez yeniden deneme yapılmış olur.

Web kancası alıcısı 72 saat içinde yanıt vermezse ve son yedi gün içinde başarılı bir bildirim gönderimi gerçekleşmediyse web kancası devre dışı bırakılır. Web kancası tekrar etkinleştirilene kadar bu URL'ye bildirim gönderilmez.

Web kancasının devre dışı bırakıldığı ve ardından tekrar etkinleştirildiği zaman arasındaki tüm bildirimler kaybolur.

Daha hızlı ve daha kolay yardım alın

Yeni kullanıcı mısınız?