Membuat API kustom yang dapat Anda panggil dari Azure Logic Apps

Berlaku pada: Azure Logic Apps (Konsumsi)

Meskipun Azure Logic Apps menawarkan ratusan konektor yang dapat Anda gunakan dalam alur kerja aplikasi logika, Anda mungkin ingin memanggil API, sistem, dan layanan yang tidak tersedia sebagai konektor. Anda dapat membuat API Anda sendiri yang menyediakan tindakan dan pemicu untuk digunakan di alur kerja. Berikut adalah alasan lain mengapa Anda mungkin ingin membuat API Anda sendiri yang dapat Anda panggil dari alur kerja:

• Perluas alur kerja integrasi sistem dan integrasi data Anda saat ini.
• Bantu pelanggan menggunakan layanan Anda untuk mengelola tugas profesional atau pribadi.
• Perluas jangkauan, kemudahan penemuan, dan gunakan untuk layanan Anda.

Pada dasarnya, konektor adalah API web yang menggunakan REST untuk antarmuka yang dapat dicolokkan, format metadata Swagger untuk dokumentasi, dan JSON sebagai format pertukaran data mereka. Karena konektor adalah REST API yang berkomunikasi melalui titik akhir HTTP, Anda dapat menggunakan bahasa apa pun, seperti .NET, Java, Python, atau Node.js. Anda juga dapat meng-host API di Azure App Service, penawaran platform-as-a-service (PaaS) yang menyediakan salah satu cara terbaik, termudah, dan paling dapat diskalakan untuk hosting API.

Agar API kustom berfungsi dengan aplikasi logika, API Anda dapat menyediakan tindakan yang melakukan tugas tertentu dalam alur kerja. API Anda juga dapat bertindak sebagai pemicu yang memulai alur kerja saat data baru atau peristiwa memenuhi kondisi tertentu. Topik ini menjelaskan pola umum yang dapat Anda ikuti untuk membangun tindakan dan pemicu di API Anda, berdasarkan perilaku yang Anda inginkan untuk menyediakan API Anda.

Anda dapat meng-host API Anda di Azure App Service, sebuah penawaran platform-as-a-service (PaaS) yang menyediakan hosting API yang sangat dapat diskalakan dan mudah digunakan.

Tip

Meskipun Anda dapat menerapkan API sebagai aplikasi web, pertimbangkan untuk menerapkan API sebagai aplikasi API, yang dapat mempermudah pekerjaan Anda saat membuat, menghosting, dan menggunakan API di cloud dan di tempat. Anda tidak perlu mengubah kode apa pun di API - cukup sebarkan kode Anda ke aplikasi API. Misalnya, pelajari cara membuat aplikasi API yang dibuat dengan bahasa berikut:

• ASP.NET.
• Java
• Node.js
• PHP
• Python

Bagaimana API kustom berbeda dari konektor kustom?

API Kustom dan konektor kustom adalah API web yang menggunakan REST untuk antarmuka yang dapat dicolokkan, format metadata Swagger untuk dokumentasi, dan JSON sebagai format pertukaran data mereka. Karena konektor adalah REST API yang berkomunikasi melalui titik akhir HTTP, Anda dapat menggunakan bahasa apa pun, seperti .NET, Java, Python, atau Node.js, untuk membangun konektor.

API kustom memungkinkan Anda memanggil API yang bukan konektor, dan menyediakan titik akhir yang dapat Anda panggil dengan HTTP + Swagger, Azure API Management, atau App Services. Konektor kustom berfungsi seperti API kustom tetapi juga memiliki atribut berikut:

• Terdaftar sebagai sumber daya Azure Logic Apps Connector di Azure.
• Muncul dengan ikon bersama konektor yang dikelola Microsoft di Azure Logic Apps Designer.
• Hanya tersedia untuk penulis konektor dan pengguna sumber daya aplikasi logika yang memiliki penyewa Microsoft Entra dan langganan Azure yang sama di wilayah tempat aplikasi logika disebarkan.

Anda juga dapat menominasikan konektor terdaftar untuk sertifikasi Microsoft. Proses ini memverifikasi bahwa konektor terdaftar memenuhi kriteria untuk penggunaan publik dan membuat konektor tersebut tersedia untuk pengguna di Power Automate dan Microsoft Power Apps.

Untuk informasi selengkapnya, tinjau dokumentasi berikut ini:

• Gambaran Konektor kustom
• Membuat konektor kustom dari API Web
• Daftarkan konektor kustom di Azure Logic Apps

Alat yang bermanfaat

API kustom berfungsi paling baik dengan aplikasi logika ketika API juga memiliki dokumen Swagger yang menjelaskan operasi dan parameter API. Banyak perpustakaan, seperti Swashbuckle, dapat secara otomatis menghasilkan file Swagger untuk Anda. Untuk membuat anotasi file Swagger untuk nama tampilan, jenis properti, dan lainnya, Anda juga dapat menggunakan TRex agar file Swagger berfungsi baik dengan aplikasi logika.

Pola aksi

Agar aplikasi logika dapat melakukan tugas, API kustom Anda harus menyediakan tindakan. Setiap operasi di peta API Anda ke tindakan. Tindakan dasar adalah pengontrol yang menerima permintaan HTTP dan mengembalikan respons HTTP. Jadi misalnya, alur kerja mengirim permintaan HTTP ke aplikasi web atau aplikasi API Anda. Aplikasi Anda kemudian mengembalikan respons HTTP, bersama dengan konten yang dapat diproses oleh alur kerja.

Untuk tindakan standar, Anda dapat menulis metode permintaan HTTP di API Anda dan menjelaskan metode itu dalam file Swagger. Anda kemudian dapat memanggil API Anda secara langsung dengan tindakan HTTP atau tindakan HTTP + Swagger. Secara default, respons harus dikembalikan dalam batasan batas waktu permintaan.

Untuk membuat alur kerja menunggu sementara API Anda menyelesaikan tugas yang berjalan lebih lama, API Anda dapat mengikuti pola polling asinkron atau pola webhook asinkron yang dijelaskan dalam topik ini. Untuk analogi yang membantu Anda memvisualisasikan perilaku pola-pola ini yang berbeda, bayangkan proses untuk memesan kue khusus dari toko roti. Pola polling mencerminkan perilaku di mana Anda memanggil toko roti setiap 20 menit untuk memeriksa apakah kue sudah siap. Pola webhook mencerminkan perilaku di mana toko roti meminta nomor telepon Anda sehingga mereka dapat menghubungi Anda ketika kue siap.

Jalankan tugas jangka panjang menggunakan pola tindakan polling

Agar API Anda melakukan tugas yang dapat berjalan lebih lama dari batasan waktu habis permintaan, Anda dapat menggunakan pola polling asinkron. Pola ini membuat API Anda berfungsi di utas terpisah, tetapi tetap memiliki koneksi aktif ke mesin Azure Logic Apps. Dengan begitu, alur kerja tidak kehabisan waktu atau melanjutkan langkah berikutnya dalam alur kerja sebelum API Anda selesai berfungsi.

Berikut pola umumnya:

1. Pastikan bahwa mesin tahu bahwa API Anda menerima permintaan dan mulai bekerja.
2. Ketika mesin membuat permintaan berikutnya untuk status pekerjaan, beri tahu mesin saat API Anda menyelesaikan tugas.
3. Kembalikan data yang relevan ke mesin sehingga alur kerja dapat dilanjutkan.

Sekarang terapkan analogi toko roti sebelumnya ke pola pemungutan suara, dan bayangkan bahwa Anda memanggil toko roti dan memesan kue khusus untuk pengiriman. Proses pembuatan kue membutuhkan waktu, dan Anda tidak ingin menunggu di telepon saat toko roti membuat kue. Toko roti mengonfirmasi pesanan Anda dan meminta Anda menelepon setiap 20 menit untuk status kue. Setelah 20 menit berlalu, Anda memanggil toko roti, tetapi mereka memberi tahu Anda bahwa kue Anda belum selesai dan bahwa Anda harus menelepon dalam 20 menit lagi. Proses bolak-balik ini berlanjut sampai Anda menelepon, dan toko roti memberi tahu Anda bahwa pesanan Anda sudah siap dan mengirimkan kue Anda.

Jadi mari kita petakan kembali pola polling ini. Toko roti mewakili API kustom Anda, sementara Anda, pelanggan kue, mewakili mesin Azure Logic Apps. Saat mesin memanggil API Anda dengan permintaan, API Anda mengonfirmasi permintaan dan merespons dengan interval waktu saat mesin dapat memeriksa status pekerjaan. Mesin terus memeriksa status pekerjaan hingga API Anda merespons bahwa pekerjaan telah selesai dan mengembalikan data ke aplikasi logika Anda, yang kemudian melanjutkan alur kerja.

Berikut adalah langkah-langkah spesifik untuk diikuti oleh API Anda, yang dijelaskan dari perspektif API:

1. Ketika API Anda mendapatkan permintaan HTTP untuk mulai bekerja, segera kembalikan respons HTTP 202 ACCEPTED dengan header location yang dijelaskan nanti dalam langkah ini. Respons ini memungkinkan mesin Azure Logic Apps mengetahui bahwa API Anda mendapatkan permintaan, menerima payload permintaan (input data), dan sekarang sedang diproses.

   Respons 202 ACCEPTED harus menyertakan header ini:

   • Diperlukan: Header location yang menentukan jalur absolut ke URL di mana mesin Logic Apps dapat memeriksa status pekerjaan API Anda

   • Opsional: retry-after Header yang menentukan jumlah detik yang harus ditunggu mesin sebelum memeriksa URL location untuk status pekerjaan.

     Secara default, mesin melakukan polling location URL setelah satu detik. Untuk menentukan interval yang berbeda, sertakan header retry-after dan jumlah detik hingga polling berikutnya.

2. Setelah waktu yang ditentukan berlalu, mesin Azure Logic Apps melakukan polling URL location untuk memeriksa status pekerjaan. API Anda harus melakukan pemeriksaan ini dan mengembalikan respons ini:

   • Jika pekerjaan selesai, kembalikan respons 200 OK HTTP, bersama dengan muatan respons (input untuk langkah berikutnya).

   • Jika tugas masih diproses, kembalikan respons HTTP 202 ACCEPTED lain, tetapi dengan header yang sama dengan respons asli.

Saat API Anda mengikuti pola ini, Anda tidak perlu melakukan apa pun dalam definisi alur kerja untuk terus memeriksa status pekerjaan. Ketika mesin mendapatkan respons 202 ACCEPTED HTTP dan header location yang valid, mesin menghargai pola asinkron, dan memeriksa header location hingga API Anda mengembalikan respons non-202.

Tip

Sebagai contoh pola asinkron, tinjau sampel respons pengontrol asinkron ini di GitHub.

Jalankan tugas jangka panjang menggunakan pola tindakan polling

Sebagai alternatif, Anda dapat menggunakan pola webhook untuk tugas yang berjalan lama dan pemrosesan asinkron. Pola ini menjeda alur kerja dan menunggu "callback" dari API Anda selesai diproses sebelum melanjutkan alur kerja. Panggilan balik ini adalah HTTP POST yang mengirim pesan ke URL saat peristiwa terjadi.

Sekarang terapkan analogi toko roti sebelumnya ke pola webhook, dan bayangkan bahwa Anda memanggil toko roti dan memesan kue khusus untuk pengiriman. Proses pembuatan kue membutuhkan waktu, dan Anda tidak ingin menunggu di telepon saat toko roti membuat kue. Toko roti mengkonfirmasi pesanan Anda, tetapi kali ini, Anda memberi mereka nomor telepon Anda sehingga mereka dapat menghubungi Anda ketika kue selesai. Kali ini, toko roti memberi tahu Anda ketika pesanan Anda siap dan mengirimkan kue Anda.

Ketika kami memetakan pola webhook ini kembali, toko roti mewakili API kustom Anda, sementara Anda, pelanggan kue, mewakili mesin Azure Logic Apps. Mesin akan memanggil API Anda dengan permintaan dan menyertakan URL "callback". Setelah pekerjaan selesai, API Anda menggunakan URL untuk memberi tahu mesin dan mengembalikan data ke aplikasi logika Anda, yang kemudian melanjutkan alur kerja.

Untuk pola ini, siapkan dua titik akhir pada pengontrol Anda: subscribe dan unsubscribe

• Titik akhir subscribe: Saat eksekusi mencapai tindakan API Anda di alur kerja, mesin Azure Logic Apps memanggil titik akhir subscribe. Langkah ini menyebabkan alur kerja membuat URL callback yang disimpan API Anda lalu menunggu callback dari API Anda saat pekerjaan selesai. API Anda kemudian memanggil kembali dengan POST HTTP ke URL dan meneruskan konten dan header yang dikembalikan sebagai input ke aplikasi logika.

• Titik akhir unsubscribe: Jika alur kerja yang dijalankan dibatalkan, mesin Azure Logic Apps akan memanggil titik akhir unsubscribe. API Anda kemudian dapat membatalkan pendaftaran URL panggilan balik dan menghentikan proses apa pun jika diperlukan.

Saat ini, desainer alur kerja tidak mendukung penemuan titik akhir webhook melalui Swagger. Jadi untuk pola ini, Anda harus menambahkan tindakan Webhook dana menentukan URL, header, dan isi untuk permintaan Anda. Lihat juga Tindakan alur kerja dan pemicu. Misalnya pola webhook, tinjau sampel pemicu webhook ini di GitHub.

Berikut adalah beberapa tips dan catatan lainnya:

• Untuk meneruskan URL panggilan balik, Anda dapat menggunakan fungsi alur kerja @listCallbackUrl() di salah satu bidang sebelumnya jika diperlukan.

• Jika Anda memiliki sumber daya aplikasi logika dan layanan berlangganan, Anda tidak perlu menghubungi titik akhir unsubscribe setelah URL callback balik dipanggil. Jika tidak, runtime Azure Logic Apps perlu memanggil titik akhir unsubscribe untuk memberi sinyal bahwa tidak ada lagi panggilan yang diharapkan dan memungkinkan pembersihan sumber daya di sisi server.

Pola pemicu

API Anda juga dapat bertindak sebagai pemicu yang memulai alur kerja saat data atau peristiwa baru memenuhi kondisi tertentu. Pemicu ini dapat memeriksa secara teratur, atau menunggu dan mendengarkan, untuk data atau peristiwa baru di titik akhir layanan Anda. Jika data atau peristiwa baru memenuhi kondisi yang ditentukan, pemicu akan menembak dan memulai aplikasi logika, yang mendengarkan pemicu tersebut. Untuk memulai aplikasi logika dengan cara ini, API Anda dapat mengikuti pemicu polling atau pola pemicu webhook. Pola-pola ini mirip dengan rekanan untuk tindakan polling dan tindakan webhook. Selain itu, pelajari lebih lanjut tentang pengukuran penggunaan untuk pemicu.

Periksa data atau peristiwa baru secara berkala menggunakan pola pemicu polling

Pemicu polling bertindak seperti tindakan polling yang sebelumnya dijelaskan dalam topik ini. Mesin Azure Logic Apps secara berkala memanggil dan memeriksa titik akhir pemicu untuk data atau peristiwa baru. Jika mesin menemukan data baru atau kejadian yang memenuhi kondisi yang ditentukan, pemicu akan dijalankan. Kemudian, mesin membuat instans alur kerja yang memproses data sebagai input.

Catatan

Setiap permintaan polling dihitung sebagai eksekusi tindakan, bahkan ketika tidak ada instans alur kerja yang dibuat. Untuk mencegah pemrosesan data yang sama beberapa kali, pemicu Anda harus membersihkan data yang sudah dibaca dan diteruskan ke aplikasi logika.

Berikut adalah langkah-langkah khusus untuk pemicu polling, yang dijelaskan dari perspektif API:

Menemukan data atau peristiwa baru?	Respons API
Ditemukan	Mengembalikan status HTTP 200 OK dengan muatan respons (input untuk langkah berikutnya). Respons ini membuat instans alur kerja dan memulai alur kerja.
Tidak ditemukan	Mengembalikan status HTTP 202 ACCEPTED dengan header location dan header retry-after. Untuk pemicu, header location juga harus berisi parameter kueri triggerState, yang biasanya berupa "stempel waktu". API Anda dapat menggunakan pengidentifikasi ini untuk melacak kapan terakhir kali alur kerja dipicu.

Misalnya, untuk memeriksa file baru secara berkala, Anda dapat membuat pemicu polling yang memiliki perilaku berikut:

Permintaan termasuk triggerState?	Respons API
No	Kembalikan status 202 ACCEPTED HTTP ditambah header location dengan triggerState diatur ke waktu saat ini dan interval retry-after ke 15 detik.
Ya	Periksa layanan Anda untuk file yang ditambahkan setelah DateTime untuk triggerState.

Jumlah file yang ditemukan	Respons API
File tunggal	Kembalikan status HTTP 200 OK dan muatan konten, perbarui triggerState ke DateTime untuk file yang dikembalikan, dan atur interval retry-after menjadi 15 detik.
Beberapa file	Kembalikan satu file dalam sekali waktu dan status 200 OK HTTP, perbarui triggerState, dan atur interval retry-after menjadi 0 detik. Langkah-langkah ini memberi tahu mesin bahwa lebih banyak data tersedia, dan bahwa mesin harus segera meminta data dari URL di location header.
Tidak ada file	Kembalikan status 202 ACCEPTED HTTP, jangan ubah triggerState, dan atur interval retry-after menjadi 15 detik.

Tip

Misalnya pola pemicu polling, tinjau sampel pengontrol pemicu polling ini di GitHub.

Tunggu dan dengarkan data atau peristiwa baru dengan pola pemicu webhook

Pemicu webhook adalah pemicu dorongan yang menunggu dan mendengarkan data atau peristiwa baru di titik akhir layanan Anda. Jika data atau peristiwa baru memenuhi kondisi yang ditentukan, pemicu akan mengaktifkan dan membuat instans alur kerja, yang kemudian memproses data sebagai input. Pemicu webhook bertindak seperti tindakan webhook yang sebelumnya dijelaskan dalam topik ini, dan diatur dengan subscribe dan titik akhir unsubscribe.

• Titik akhir subscribe: Saat Anda menambahkan dan menyimpan pemicu webhook di aplikasi logika Anda, mesin Azure Logic Apps akan memanggil titik akhir subscribe. Langkah ini menyebabkan alur kerja membuat URL callback yang disimpan API Anda. Ketika ada data baru atau peristiwa yang memenuhi kondisi yang ditentukan, API Anda akan kembali dengan POST HTTP ke URL. Muatan konten dan header lulus sebagai input ke aplikasi logika.

• Titik akhir unsubscribe: Jika pemicu webhook atau seluruh sumber daya aplikasi logika dihapus, mesin Azure Logic Apps akan memanggil titik akhir unsubscribe. API Anda kemudian dapat membatalkan pendaftaran URL panggilan balik dan menghentikan proses apa pun jika diperlukan.

Saat ini, desainer alur kerja tidak mendukung penemuan titik akhir webhook melalui Swagger. Jadi untuk pola ini, Anda harus menambahkan pemicu Webhook dana menentukan URL, header, dan isi untuk permintaan Anda. Lihat juga pemicu HTTPWebhook. Untuk contoh pola webhook, tinjau sampel pemicu webhook ini di GitHub.

Berikut adalah beberapa tips dan catatan lainnya:

• Untuk meneruskan URL panggilan balik, Anda dapat menggunakan fungsi alur kerja @listCallbackUrl() di salah satu bidang sebelumnya jika diperlukan.

• Untuk mencegah pemrosesan data yang sama beberapa kali, pemicu Anda harus membersihkan data yang sudah dibaca dan diteruskan ke aplikasi logika.

• Jika Anda memiliki sumber daya aplikasi logika dan layanan berlangganan, Anda tidak perlu menghubungi titik akhir unsubscribe setelah URL callback balik dipanggil. Jika tidak, runtime Azure Logic Apps perlu memanggil titik akhir unsubscribe untuk memberi sinyal bahwa tidak ada lagi panggilan yang diharapkan dan memungkinkan pembersihan sumber daya di sisi server.

Meningkatkan keamanan untuk panggilan ke API Anda dari aplikasi logika

Setelah membuat API khusus, siapkan autentikasi untuk API Anda sehingga Anda dapat memanggilnya dengan aman dari aplikasi logika. Pelajari cara meningkatkan keamanan untuk panggilan ke API Anda dari aplikasi logika.

Menyebarkan dan memanggil API Anda

Setelah menyiapkan autentikasi, siapkan penyebaran untuk API Anda. Pelajari cara menyebarkan dan memanggil API kustom dari aplikasi logika.

Menerbitkan API kustom ke Azure

Untuk membuat API kustom Anda tersedia untuk pengguna Azure Logic Apps lainnya, Anda harus menambahkan keamanan dan mendaftarkannya sebagai konektor Azure Logic Apps. Untuk informasi selengkapnya, lihat Gambaran konektor kustom.

Untuk membuat API kustom Anda tersedia untuk semua pengguna di Logic Apps, Power Automate, dan Microsoft Power Apps, Anda harus menambahkan keamanan, mendaftarkan API Anda sebagai konektor Azure Logic Apps, dan menominasikan konektor Anda untuk program Bersertifikat Microsoft Azure.

Mendapatkan dukungan

• Untuk bantuan khusus dengan API kustom, hubungi customapishelp@microsoft.com.

• Untuk pertanyaan, buka Halaman pertanyaan Microsoft Q&A untuk Azure Logic Apps.

Langkah berikutnya

• Menangani kesalahan umum dan pengecualian
• Panggil, picu, atau sarangkan aplikasi logika dengan titik akhir HTTP
• Pengukuran penggunaan untuk tindakan dan pemicu