Azure Logic Apps'ten çağırabileceğiniz özel API'ler oluşturma
Şunlar için geçerlidir: Azure Logic Apps (Tüketim)
Azure Logic Apps, mantıksal uygulama iş akışlarında kullanabileceğiniz yüzlerce bağlayıcı sunsa da bağlayıcı olarak kullanılamamış API'leri, sistemleri ve hizmetleri çağırmak isteyebilirsiniz. İş akışlarında kullanılacak eylemleri ve tetikleyicileri sağlayan kendi API'lerinizi oluşturabilirsiniz. İş akışlarından çağırabileceğiniz kendi API'lerinizi oluşturmak istemenizin diğer nedenleri şunlardır:
- Geçerli sistem tümleştirme ve veri tümleştirme iş akışlarınızı genişletin.
- Müşterilerin profesyonel veya kişisel görevleri yönetmek için hizmetinizi kullanmasına yardımcı olun.
- Hizmetiniz için erişim, bulunabilirlik ve kullanımı genişletin.
Temel olarak bağlayıcılar eklenebilir arabirimler için REST, belgeler için Swagger meta veri biçimi ve veri değişimi biçimi olarak JSON kullanan web API'leridir. Bağlayıcılar HTTP uç noktaları üzerinden iletişim kuran REST API'leri olduğundan, .NET, Java, Python veya Node.js gibi bağlayıcılar oluşturmak için herhangi bir dili kullanabilirsiniz. API barındırma için en iyi, en kolay ve en ölçeklenebilir yollardan birini sağlayan bir hizmet olarak platform (PaaS) teklifi olan Azure Uygulaması Service'te de API'lerinizi barındırabilirsiniz.
Özel API'lerin mantıksal uygulama iş akışıyla çalışması için API'niz iş akışlarında belirli görevleri gerçekleştiren eylemler sağlayabilir. API'niz, yeni veriler veya bir olay belirtilen koşulu karşıladığında iş akışı çalıştırması başlatan bir tetikleyici olarak da görev yapabilir. Bu konu başlığında, API'nizin sağlamasını istediğiniz davranışa bağlı olarak API'nizde eylem ve tetikleyici oluşturmak için izleyebileceğiniz yaygın desenler açıklanmaktadır.
API'lerinizi, yüksek oranda ölçeklenebilir ve kolay API barındırma sağlayan bir hizmet olarak platform (PaaS) teklifi olan Azure Uygulaması Service'te barındırabilirsiniz.
Bahşiş
API'lerinizi web uygulamaları olarak dağıtabilirsiniz ancak API'lerinizi API uygulamaları olarak dağıtmayı göz önünde bulundurun. Bu, bulutta ve şirket içinde API'leri oluştururken, barındırırken ve kullanırken işinizi kolaylaştırır. API'lerinizdeki herhangi bir kodu değiştirmeniz gerekmez; yalnızca kodunuzu bir API uygulamasına dağıtın. Örneğin, şu dillerle oluşturulmuş API uygulamaları oluşturmayı öğrenin:
Özel API'lerin özel bağlayıcılardan farkı nedir?
Özel API'ler ve özel bağlayıcılar eklenebilir arabirimler için REST, belgeler için Swagger meta veri biçimi ve veri değişimi biçimi olarak JSON kullanan web API'leridir. Bu API'ler ve bağlayıcılar HTTP uç noktaları üzerinden iletişim kuran REST API'leri olduğundan, özel API'ler ve bağlayıcılar oluşturmak için .NET, Java, Python veya Node.js gibi herhangi bir dili kullanabilirsiniz.
Özel API'ler bağlayıcı olmayan API'leri çağırmanıza ve HTTP + Swagger, Azure API Management veya App Services ile çağırabileceğiniz uç noktalar sağlamanıza olanak tanır. Özel bağlayıcılar özel API'ler gibi çalışır ancak şu özniteliklere de sahiptir:
- Logic Apps Bağlan veya Azure'daki kaynaklar olarak kaydedilir.
- Logic Apps Tasarım Aracı Microsoft tarafından yönetilen bağlayıcıların yanında simgelerle birlikte görünür.
- Yalnızca mantıksal uygulamaların dağıtıldığı bölgede aynı Microsoft Entra kiracısına ve Azure aboneliğine sahip bağlayıcı yazarları ve mantıksal uygulama kaynak kullanıcıları tarafından kullanılabilir.
Microsoft sertifikası için kayıtlı bağlayıcıları da aday olarak belirleyebilirsiniz. Bu işlem, kayıtlı bağlayıcıların genel kullanım ölçütlerine uygun olduğunu doğrular ve bu bağlayıcıları Power Automate ve Microsoft Power Apps'teki kullanıcılar için kullanılabilir hale getirir.
Daha fazla bilgi için aşağıdaki belgeleri gözden geçirin:
- Özel bağlayıcılara genel bakış
- Web API'lerinden özel bağlayıcılar oluşturma
- Azure Logic Apps'te özel bağlayıcıları kaydetme
Yararlı araçlar
Özel API, API'nin işlemlerini ve parametrelerini açıklayan bir Swagger belgesine de sahip olduğunda mantıksal uygulamalarla en iyi şekilde çalışır. Swashbuckle gibi birçok kitaplık Swagger dosyasını sizin için otomatik olarak oluşturabilir. Görünen adlar, özellik türleri vb. için Swagger dosyasına ek açıklama eklemek için, Swagger dosyanızın mantıksal uygulamalarla iyi çalışması için TRex'i de kullanabilirsiniz.
Eylem desenleri
Mantıksal uygulamaların görevleri gerçekleştirmesi için özel API'nizin eylemler sağlaması gerekir. API'nizdeki her işlem bir eylemle eşler. Temel eylem, HTTP isteklerini kabul eden ve HTTP yanıtları döndüren bir denetleyicidir. Örneğin, bir iş akışı web uygulamanıza veya API uygulamanıza bir HTTP isteği gönderir. Uygulamanız daha sonra iş akışının işleyebileceği içerikle birlikte bir HTTP yanıtı döndürür.
Standart bir eylem için API'nize bir HTTP isteği yöntemi yazabilir ve bu yöntemi bir Swagger dosyasında açıklayabilirsiniz. Ardından API'nizi doğrudan bir HTTP eylemi veya HTTP + Swagger eylemiyle çağırabilirsiniz. Varsayılan olarak, yanıtlar istek zaman aşımı sınırı içinde döndürülmelidir.
API'niz daha uzun süre çalışan görevleri tamamlarken iş akışının beklemesini sağlamak için, API'niz bu konuda açıklanan zaman uyumsuz yoklama desenini veya zaman uyumsuz web kancası desenini izleyebilir. Bu desenlerin farklı davranışlarını görselleştirmenize yardımcı olan bir benzetme için bir pastaneden özel pasta sipariş etme sürecini düşünün. Yoklama düzeni, pastanenin hazır olup olmadığını denetlemek için her 20 dakikada bir pastaneyi çağırdığınız davranışı yansıtır. Web kancası deseni, pastane hazır olduğunda sizi arayabilmeleri için pastanenin sizden telefon numaranızı istediği davranışı yansıtır.
Yoklama eylemi düzeniyle uzun süre çalışan görevler gerçekleştirme
API'nizin istek zaman aşımı sınırından daha uzun çalıştırabilecek görevleri gerçekleştirmesini sağlamak için zaman uyumsuz yoklama desenini kullanabilirsiniz. Bu desen, API'nizin ayrı bir iş parçacığında çalışmasını sağlar, ancak Azure Logic Apps altyapısına etkin bir bağlantı sağlar. Bu şekilde, API'niz çalışmayı bitirmeden önce iş akışı zaman aşımına uğramaz veya iş akışındaki bir sonraki adımla devam etmez.
Genel desen aşağıdadır:
- Altyapının API'nizin isteği kabul ettiğini ve çalışmaya başladığını bildiğinden emin olun.
- Altyapı iş durumu için sonraki istekleri yaptığında, API'nizin görevi tamamladığında altyapıya bunu bildirin.
- İş akışının devam edebilmesi için ilgili verileri altyapıya döndürebilirsiniz.
Şimdi yoklama desenine önceki fırın benzetmesini uygulayın ve bir fırın çağırıp teslimat için özel bir pasta sipariş ettiğinizi düşünün. Pasta yapma işlemi zaman alır ve pastane pasta üzerinde çalışırken telefonda beklemek istemezsiniz. Fırın siparişinizi onaylar ve pastanın durumu için her 20 dakikada bir aramanızı sağlar. 20 dakika geçtikten sonra pastaneyi ararsınız, ama size pastanızın yapılmadığını ve 20 dakika içinde aramanız gerektiğini söyler. Bu ileri geri işlemi siz arayana kadar devam eder ve fırın siparişinizin hazır olduğunu söyler ve pastanızı teslim eder.
Şimdi bu yoklama düzenini yeniden eşleyelim. Pastane özel API'nizi temsil ederken, siz pasta müşterisi Azure Logic Apps altyapısını temsil eder. Altyapı API'nizi bir istekle çağırdığında, API'niz isteği onaylar ve altyapının iş durumunu denetleyebileceği zaman aralığıyla yanıt verir. Altyapı, API'niz işin yapıldığına yanıt verene ve mantıksal uygulamanıza veri döndürene kadar iş durumunu denetlemeye devam eder ve ardından iş akışı devam eder.
API'nizin izlemesi gereken ve API'nin perspektifinden açıklanan belirli adımlar şunlardır:
API'niz çalışmaya başlamak için bir HTTP isteği aldığında, bu adımın
locationilerleyen bölümlerinde açıklanan üst bilgiyle hemen bir HTTP202 ACCEPTEDyanıtı döndürebilirsiniz. Bu yanıt, Azure Logic Apps altyapısının API'nizin isteği aldığını, istek yükünü (veri girişi) kabul ettiğini ve şimdi işlendiğini bilmesini sağlar.Yanıt şu
202 ACCEPTEDüst bilgileri içermelidir:Gerekli:
locationAzure Logic Apps altyapısının API'nizin iş durumunu denetleyebileceği bir URL'nin mutlak yolunu belirten üst bilgiİsteğe bağlı: İş durumunun URL'sini
retry-afterdenetlemeden önce altyapının beklemesilocationgereken saniye sayısını belirten üst bilgi.Varsayılan olarak, altyapı URL'yi
locationbir saniye sonra yoklar. Farklı bir aralık belirtmek için üst bilgiyi ve sonraki ankete kadar geçen saniye sayısını ekleyinretry-after.
Belirtilen süre geçtikten sonra Azure Logic Apps altyapısı, iş durumunu denetlemek için URL'yi yoklar
location. API'nizin bu denetimleri gerçekleştirmesi ve şu yanıtları döndürmesi gerekir:İş tamamlanırsa, yanıt yüküyle birlikte bir HTTP
200 OKyanıtı (sonraki adım için giriş) döndürin.İş hala işleniyorsa, başka bir HTTP
202 ACCEPTEDyanıtı döndür, ancak özgün yanıtla aynı üst bilgilerle.
API'niz bu deseni izlediğinde, iş durumunu denetlemeye devam etmek için iş akışı tanımında hiçbir şey yapmanız gerekmez.
Altyapı bir HTTP 202 ACCEPTED yanıtı ve geçerli location bir üst bilgi aldığında, altyapı zaman uyumsuz desene uyar ve API'niz 202 dışı bir yanıt döndürene kadar üst bilgiyi denetler location .
Bahşiş
Zaman uyumsuz bir desen örneği için GitHub'da bu zaman uyumsuz denetleyici yanıt örneğini gözden geçirin.
Web kancası eylem düzeniyle uzun süre çalışan görevler gerçekleştirme
Alternatif olarak, uzun süre çalışan görevler ve zaman uyumsuz işleme için web kancası desenini kullanabilirsiniz. Bu düzen iş akışını duraklatır ve iş akışına devam etmeden önce API'nizden bir "geri çağırma" işleminin tamamlanmasını bekler. Bu geri çağırma, bir olay gerçekleştiğinde URL'ye ileti gönderen bir HTTP POST'tır.
Şimdi web kancası desenine önceki fırın benzetmesini uygulayın ve bir fırın çağırıp teslimat için özel bir pasta sipariş ettiğinizi düşünün. Pasta yapma işlemi zaman alır ve pastane pasta üzerinde çalışırken telefonda beklemek istemezsiniz. Fırın siparişinizi onaylar, ancak bu kez, pasta bittiğinde sizi arayabilmeleri için telefon numaranızı verirsiniz. Bu kez fırın siparişinizin ne zaman hazır olduğunu söyler ve pastanızı teslim eder.
Bu web kancası desenini yeniden eşlediğimizde pastane özel API'nizi temsil ederken, siz pasta müşterisi Azure Logic Apps altyapısını temsil eder. Altyapı API'nizi bir istekle çağırır ve bir "geri çağırma" URL'si içerir. İş tamamlandığında, API'niz altyapıyı bilgilendirmek ve verileri mantıksal uygulamanıza döndürmek için URL'yi kullanır ve ardından iş akışına devam eder.
Bu düzen için denetleyicinizde iki uç nokta ayarlayın: subscribe ve unsubscribe
subscribeuç nokta: Yürütme iş akışında API'nizin eylemine ulaştığında Azure Logic Apps altyapısı uç noktayı çağırırsubscribe. Bu adım, iş akışının API'nizin depolayacağı bir geri çağırma URL'si oluşturmasına ve ardından iş tamamlandığında API'nizden geri çağırmayı beklemesine neden olur. Ardından API'niz URL'ye bir HTTP POST ile geri çağrılar ve döndürülen içeriği ve üst bilgileri mantıksal uygulamaya giriş olarak geçirir.unsubscribeuç nokta: İş akışı çalıştırması iptal edilirse Azure Logic Apps altyapısı uç noktayı çağırırunsubscribe. Ardından API'niz geri çağırma URL'sinin kaydını kaldırıp gerekli işlemleri durdurabilir.
İş akışı tasarımcısı şu anda Swagger aracılığıyla web kancası uç noktalarını bulmayı desteklememektedir. Bu nedenle bu düzen için bir Web kancası eylemi eklemeniz ve isteğiniz için URL'yi, üst bilgileri ve gövdeyi belirtmeniz gerekir. Ayrıca bkz. İş akışı eylemleri ve tetikleyicileri. Örnek bir web kancası deseni için GitHub'da bu web kancası tetikleyici örneğini gözden geçirin.
Diğer ipuçları ve notlar şunlardır:
Geri çağırma URL'sini geçirmek için, önceki alanlardan
@listCallbackUrl()herhangi birinde iş akışı işlevini gerektiği gibi kullanabilirsiniz.Hem mantıksal uygulama kaynağına hem de abone olunan hizmete sahipseniz, geri çağırma URL'si çağrıldıktan sonra uç noktayı çağırmanız
unsubscribegerekmez. Aksi takdirde Azure Logic Apps çalışma zamanınınunsubscribe, başka çağrı beklenmez ve sunucu tarafında kaynak temizlemeye izin vermek için uç noktayı çağırması gerekir.
Tetikleyici desenleri
Özel API'niz, yeni veriler veya bir olay belirtilen koşulu karşıladığında bir iş akışı çalıştırması başlatan bir tetikleyici görevi görebilir. Bu tetikleyici, hizmet uç noktanızdaki yeni verileri veya olayları düzenli olarak denetleyebilir veya bekleyip dinleyebilir. Yeni veriler veya bir olay belirtilen koşulu karşılıyorsa, tetikleyici tetikler ve bu tetikleyiciyi dinleyen mantıksal uygulamayı başlatır. Mantıksal uygulamaları bu şekilde başlatmak için API'niz yoklama tetikleyicisini veya web kancası tetikleyici desenini izleyebilir. Bu desenler, yoklama eylemleri ve web kancası eylemleri için karşılık gelenlere benzer. Ayrıca tetikleyiciler için kullanım ölçümü hakkında daha fazla bilgi edinin.
Yoklama tetikleyici düzeniyle yeni verileri veya olayları düzenli olarak denetleme
Yoklama tetikleyicisi, bu konuda daha önce açıklanan yoklama eylemine çok benzer. Azure Logic Apps altyapısı, tetikleyici uç noktasını düzenli aralıklarla çağırır ve yeni veriler veya olaylar için denetler. Altyapı yeni veriler veya belirtilen koşulunuza uyan bir olay bulursa tetikleyici tetikler. Ardından altyapı, verileri giriş olarak işleyen bir iş akışı örneği oluşturur.
Dekont
Hiçbir iş akışı örneği oluşturulmasa bile her yoklama isteği bir eylem yürütmesi olarak sayılır. Aynı verilerin birden çok kez işlenmesini önlemek için tetikleyicinizin zaten okunmuş ve mantıksal uygulamaya geçirilen verileri temizlemesi gerekir.
Aşağıda, API'nin perspektifinden açıklanan yoklama tetikleyicisi için belirli adımlar verilmiştır:
| Yeni veri veya olay mı buldunuz? | API yanıtı |
|---|---|
| Bulundu | Yanıt yüküyle bir HTTP 200 OK durumu döndür (sonraki adım için giriş). Bu yanıt bir iş akışı örneği oluşturur ve iş akışını başlatır. |
| Bulunamadı | Üst bilgi ve üst bilgi içeren bir locationretry-after HTTP 202 ACCEPTED durumu döndürür. Tetikleyiciler için üst location bilgi genellikle "zaman damgası" olan bir triggerState sorgu parametresi de içermelidir. API'niz iş akışının en son tetiklendiği zamanı izlemek için bu tanımlayıcıyı kullanabilir. |
Örneğin, hizmetinizi düzenli aralıklarla yeni dosyalar için denetlemek için şu davranışlara sahip bir yoklama tetikleyicisi oluşturabilirsiniz:
İstek şunları içerir triggerState: ? |
API yanıtı |
|---|---|
| No | Geçerli saate ve aralığı 15 saniyeye ayarlanmış bir HTTP 202 ACCEPTED durumunun retry-after yanı sıra bir location üst bilgi triggerState döndürür. |
| Evet | hizmetinden sonra DateTime eklenen dosyalar için triggerStatehizmetinizi denetleyin. |
| Bulunan dosya sayısı | API yanıtı |
|---|---|
| Tek dosya | BIR HTTP 200 OK durumu ve içerik yükü döndür, döndürülen dosya için değerine güncelleştirin triggerStateDateTime ve aralığı 15 saniye olarak ayarlayın retry-after . |
| Birden çok dosya | Bir kerede bir dosya ve BIR HTTP 200 OK durumu döndürerek güncelleştirin triggerStateretry-after ve aralığı 0 saniye olarak ayarlayın. Bu adımlar altyapıya daha fazla veri olduğunu ve altyapının üst bilgideki URL'den hemen veri istemesi location gerektiğini bildirir. |
| Dosya yok | BIR HTTP 202 ACCEPTED durumu döndür, değiştirmeyin triggerStateretry-after ve aralığı 15 saniye olarak ayarlayın. |
Bahşiş
Örnek bir yoklama tetikleyicisi deseni için GitHub'daki bu yoklama tetikleyicisi denetleyicisi örneğini gözden geçirin.
Web kancası tetikleyici deseniyle yeni verileri veya olayları bekleme ve dinleme
Web kancası tetikleyicisi, hizmet uç noktanızda yeni verileri veya olayları bekleyen ve dinleyen bir anında iletme tetikleyicisidir . Yeni veriler veya bir olay belirtilen koşulu karşılıyorsa, tetikleyici tetikler ve verileri giriş olarak işleyen bir iş akışı örneği oluşturur.
Web kancası tetikleyicileri, bu konuda daha önce açıklanan web kancası eylemlerine çok benzer ve ve unsubscribe uç noktalarıyla subscribe ayarlanır.
subscribeuç nokta: Mantıksal uygulamanıza bir web kancası tetikleyicisi ekleyip kaydettiğinizde, Azure Logic Apps altyapısı uç noktayı çağırırsubscribe. Bu adım, iş akışının API'nizin depoacağı bir geri çağırma URL'si oluşturmasına neden olur. Belirtilen koşula uyan yeni veriler veya bir olay olduğunda, API'niz URL'ye bir HTTP POST ile geri çağrır. İçerik yükü ve üst bilgiler mantıksal uygulamaya giriş olarak geçer.unsubscribeuç nokta: Web kancası tetikleyicisi veya mantıksal uygulama kaynağının tamamı silinirse, Azure Logic Apps altyapısı uç noktayı çağırırunsubscribe. Ardından API'niz geri çağırma URL'sinin kaydını kaldırıp gerekli işlemleri durdurabilir.
İş akışı tasarımcısı şu anda Swagger aracılığıyla web kancası uç noktalarını bulmayı desteklememektedir. Bu nedenle bu düzen için bir Web kancası tetikleyicisi eklemeniz ve isteğiniz için URL'yi, üst bilgileri ve gövdeyi belirtmeniz gerekir. Ayrıca bkz. HTTPWebhook tetikleyicisi. Örnek bir web kancası düzeni için GitHub'da bu web kancası tetikleyici denetleyicisi örneğini gözden geçirin.
Diğer ipuçları ve notlar şunlardır:
Geri çağırma URL'sini geçirmek için, önceki alanlardan
@listCallbackUrl()herhangi birinde iş akışı işlevini gerektiği gibi kullanabilirsiniz.Aynı verilerin birden çok kez işlenmesini önlemek için tetikleyicinizin zaten okunmuş ve mantıksal uygulamaya geçirilen verileri temizlemesi gerekir.
Hem mantıksal uygulama kaynağına hem de abone olunan hizmete sahipseniz, geri çağırma URL'si çağrıldıktan sonra uç noktayı çağırmanız
unsubscribegerekmez. Aksi takdirde Logic Apps çalışma zamanınınunsubscribe, başka çağrı beklenmez ve sunucu tarafında kaynak temizlemeye izin vermek için uç noktayı çağırması gerekir.
Mantıksal uygulamalardan API'lerinize yapılan çağrılar için güvenliği geliştirme
Özel API'lerinizi oluşturduktan sonra, api'lerinizi mantıksal uygulamalardan güvenli bir şekilde çağırabilmeniz için kimlik doğrulamasını ayarlayın. Mantıksal uygulamalardan özel API'lere yapılan çağrılar için güvenliği geliştirmeyi öğrenin.
API'lerinizi dağıtma ve çağırma
Kimlik doğrulamasını ayarladıktan sonra API'leriniz için dağıtımı ayarlayın. Mantıksal uygulamalardan özel API'leri dağıtmayı ve çağırmayı öğrenin.
Özel API'leri Azure'da yayımlama
Özel API'lerinizi diğer Azure Logic Apps kullanıcıları için kullanılabilir hale getirmek için güvenlik eklemeniz ve bunları Azure Logic Apps bağlayıcısı olarak kaydetmeniz gerekir. Daha fazla bilgi için bkz. Özel bağlayıcılara genel bakış.
Özel API'lerinizi Logic Apps, Power Automate ve Microsoft Power Apps'teki tüm kullanıcıların kullanımına açmak için güvenlik eklemeli, API'lerinizi Azure Logic Apps bağlayıcısı olarak kaydetmeli ve Bağlayıcılarınızı Microsoft Azure Sertifikalı programı için aday olarak atamalısınız.
Destek alma
Özel API'lerle ilgili belirli yardım için adresine başvurun customapishelp@microsoft.com.
Sorular için Azure Logic Apps için Microsoft Soru-Cevap soru sayfasını ziyaret edin.