Bekerja dengan proksi lama

Artikel
06/01/2023

Penting

Proksi Azure Functions adalah fitur warisan untuk versi 1.x hingga 3.x dari runtime Azure Functions. Dukungan untuk proksi dapat diaktifkan kembali di versi 4.x agar Anda berhasil meningkatkan aplikasi fungsi ke versi runtime terbaru. Sesegera mungkin, Anda harus beralih untuk mengintegrasikan aplikasi fungsi Anda dengan Azure API Management. Azure API Management memungkinkan Anda memanfaatkan serangkaian fitur yang lebih lengkap untuk menentukan, mengamankan, mengelola, dan memonetisasi API berbasis Functions Anda. Untuk informasi selengkapnya, lihat Integrasi API Management.

Untuk mempelajari cara mengaktifkan kembali dukungan proksi di Functions versi 4.x, lihat Mengaktifkan kembali proksi di Functions v4.x.

Untuk membantu mempermudah migrasi dari implementasi proksi yang ada, artikel ini ditautkan ke konten API Management yang setara, jika tersedia.

Artikel ini menjelaskan cara mengonfigurasi dan bekerja dengan Proksi Azure Functions. Dengan fitur ini, Anda dapat menentukan titik akhir pada aplikasi fungsi yang diimplementasikan oleh sumber lain. Anda dapat menggunakan proksi ini untuk memecah API besar menjadi beberapa aplikasi fungsi (seperti dalam arsitektur layanan mikro), sambil tetap menyajikan satu permukaan API untuk klien.

Penagihan Fungsi Standar berlaku untuk eksekusi proksi. Untuk informasi selengkapnya, lihat Harga Azure Functions.

Mengaktifkan kembali proksi di Functions v4.x

Setelah memigrasikan aplikasi fungsi Anda ke versi 4.x dari runtime Functions, Anda harus secara khusus mengaktifkan kembali proksi. Anda masih harus beralih untuk mengintegrasikan aplikasi fungsi Anda dengan Azure API Management sesegera mungkin, dan tidak hanya mengandalkan proksi.

Mengaktifkan kembali proksi mengharuskan Anda untuk mengatur bendera dalam AzureWebJobsFeatureFlags pengaturan aplikasi dengan salah satu cara berikut:

AzureWebJobsFeatureFlags Jika pengaturan belum ada, tambahkan pengaturan ini ke aplikasi fungsi Anda dengan nilai EnableProxies.
Jika pengaturan ini sudah ada, tambahkan ,EnableProxies ke akhir nilai yang ada.

AzureWebJobsFeatureFlags adalah array bendera yang dibatasi koma yang digunakan untuk mengaktifkan pratinjau dan fitur sementara lainnya. Untuk mempelajari selengkapnya tentang cara membuat dan mengubah pengaturan aplikasi, lihat Bekerja dengan pengaturan aplikasi.

Catatan

Bahkan ketika diaktifkan kembali menggunakan EnableProxies bendera, Anda tidak dapat bekerja dengan proksi di portal Azure. Sebagai gantinya , Anda harus bekerja langsung dengan file proxies.json untuk aplikasi fungsi Anda. Untuk informasi lebih lanjut, lihat Konfigurasi tingkat lanjut.

Membuat proksi

Penting

Untuk konten yang setara menggunakan API Management, lihat Mengekspos API tanpa server dari titik akhir HTTP menggunakan Azure API Management.

Proksi didefinisikan dalam file proxies.json di akar aplikasi fungsi Anda. Langkah-langkah di bagian ini menunjukkan cara menggunakan portal Azure untuk membuat file ini di aplikasi fungsi Anda. Tidak semua bahasa dan kombinasi sistem operasi mendukung pengeditan dalam portal. Jika Anda tidak dapat memodifikasi file aplikasi fungsi di portal, Anda dapat membuat dan menyebarkan file proxies.json yang setara dari akar folder proyek lokal Anda. Untuk mempelajari selengkapnya tentang dukungan pengeditan portal, lihat Detail dukungan bahasa.

Buka portal Microsoft Azure, lalu masuk ke aplikasi fungsi Anda.
Di panel kiri, pilih Proxy lalu pilih +Tambahkan.
Berikan nama untuk proksi Anda.
Konfigurasikan titik akhir yang terekspos pada aplikasi fungsi ini dengan menentukan templat rute dan metode HTTP. Parameter ini berperilaku sesuai dengan aturan untuk pemicu HTTP.
Atur URL backend ke titik akhir lain. Titik akhir ini bisa menjadi fungsi di aplikasi fungsi lain, atau bisa jadi API lainnya. Nilainya tidak harus statis, dan dapat mereferensikan pengaturan aplikasi dan parameter dari permintaan klien yang asli.
Pilih Buat.

Proksi Anda sekarang ada sebagai titik akhir baru di aplikasi fungsi Anda. Dari perspektif klien, demikian sama dengan HttpTrigger di Functions. Anda dapat mencoba proksi baru Anda dengan menyalin URL Proksi dan mengujinya dengan klien HTTP favorit Anda.

Mengubah permintaan dan respons

Penting

API Management memungkinkan Anda mengubah perilaku API melalui konfigurasi menggunakan kebijakan. Kebijakan adalah kumpulan pernyataan yang berjalan secara berurutan atas permintaan atau respons API. Untuk informasi selengkapnya tentang kebijakan API Management, lihat Kebijakan di Azure API Management.

Dengan proxy, Anda dapat mengubah permintaan dan respons dari back-end. Transformasi ini dapat menggunakan variabel seperti yang didefinisikan dalam Gunakan variabel.

Mengubah permintaan back-end

Secara default, permintaan back-end diinisialisasi sebagai salinan permintaan asli. Selain mengatur URL back-end, Anda dapat membuat perubahan pada metode HTTP, header, dan parameter untai kueri. Nilai yang diubah dapat mereferensikan pengaturan aplikasi danparameter dari permintaan klien asli.

Permintaan back-end dapat diubah di portal dengan memperluas bagian timpa respons dari halaman detail proksi.

Mengubah respons

Secara default, respons klien diinisialisasi sebagai salinan respons back-end. Anda dapat membuat perubahan pada kode status respons, frasa alasan, header, dan isi. Nilai yang diubah dapat mereferensikan pengaturan aplikasi, parameter dari permintaan klien asli, dan parameter dari respons back-end.

Respons back-end dapat diubah di portal dengan memperluas bagian timpa respons dari halaman detail proksi.

Menggunakan variabel

Konfigurasi untuk proksi tidak memerlukan statik. Anda dapat mengkondisikannya untuk menggunakan variabel dari permintaan klien asli, respons back-end, atau pengaturan aplikasi.

Referensi fungsi lokal

Anda dapat menggunakan localhost untuk mereferensikan fungsi di dalam aplikasi fungsi yang sama secara langsung, tanpa permintaan proksi dua arah.

"backendUri": "https://localhost/api/httptriggerC#1" akan mereferensikan fungsi yang dipicu HTTP lokal di rute /api/httptriggerC#1

Catatan

Jika fungsi Anda menggunakan tingkat otorisasi fungsi, admin, atau sys, Anda harus memberikan kode dan clientId, sesuai URL fungsi asli. Dalam hal ini referensi akan terlihat seperti: "backendUri": "https://localhost/api/httptriggerC#1?code=<keyvalue>&clientId=<keyname>" Kami sarankan menyimpan kunci ini dalam pengaturan aplikasi dan mereferensikannya di proksi Anda. Ini menghindari menyimpan rahasia dalam kode sumber Anda.

Referensi parameter permintaan

Anda dapat menggunakan parameter permintaan sebagai input ke properti URL back-end atau sebagai bagian dari mengubah permintaan dan respons. Beberapa parameter dapat terikat dari templat rute yang ditentukan dalam konfigurasi proksi dasar, dan parameter lainnya dapat berasal dari properti permintaan yang masuk.

Parameter templat rute

Parameter yang digunakan dalam templat rute tersedia untuk direferensikan berdasarkan nama. Nama parameter diapit dalam kurung kurawal ({}).

Misalnya, jika proksi memiliki templat rute, seperti /pets/{petId}, URL back-end dapat menyertakan nilai {petId}, seperti dalam https://<AnotherApp>.azurewebsites.net/api/pets/{petId}. Jika templat rute berakhir dalam wildcard, seperti /api/{*restOfPath}, nilainya {restOfPath} adalah representasi string dari segmen jalur yang tersisa dari permintaan masuk.

Parameter permintaan tambahan

Selain parameter templat rute, nilai berikut ini dapat digunakan dalam nilai konfigurasi:

{request.method}: Metode HTTP yang digunakan pada permintaan asli.
{request.headers.<HeaderName>}: Header yang dapat dibaca dari permintaan asli. Ganti <HeaderName> dengan nama header yang ingin Anda baca. Jika header tidak disertakan pada permintaan, nilainya akan menjadi string kosong.
{request.querystring.<ParameterName>}: Parameter string kueri yang dapat dibaca dari permintaan asli. Ganti <ParameterName> dengan nama parameter yang ingin Anda baca. Jika parameter tidak disertakan pada permintaan, nilainya akan menjadi string kosong.

Referensi parameter respons back-end

Parameter respons dapat digunakan sebagai bagian dari mengubah respons terhadap klien. Nilai berikut ini dapat digunakan dalam nilai konfigurasi:

{backend.response.statusCode}: Kode status HTTP yang dikembalikan pada respons back-end.
{backend.response.statusReason}: Frasa alasan HTTP yang dikembalikan pada respons back-end.
{backend.response.headers.<HeaderName>}: Header yang dapat dibaca dari respons back-end. Ganti <HeaderName> dengan nama header yang ingin Anda baca. Jika header tidak disertakan pada respons, nilainya akan menjadi string kosong.

Referensi pengaturan aplikasi

Anda juga dapat mereferensikan pengaturan aplikasi yang ditentukan untuk aplikasi fungsi dengan mengelilingi nama pengaturan dengan tanda persen (%).

Misalnya, URL back-end https://%ORDER_PROCESSING_HOST%/api/orders akan memiliki "%ORDER_PROCESSING_HOST%" diganti dengan nilai pengaturan ORDER_PROCESSING_HOST.

Tip

Gunakan pengaturan aplikasi untuk host back-end saat Anda memiliki beberapa penyebaran atau lingkungan pengujian. Dengan begitu, Anda dapat memastikan bahwa Anda selalu berbicara dengan back-end yang tepat untuk lingkungan itu.

Memecahkan masalah Proksi

Dengan menambahkan bendera "debug":true ke proksi apa pun di proxies.json Anda, Anda akan mengaktifkan pembuatan log debug. Log disimpan di D:\home\LogFiles\Application\Proxies\DetailedTrace dan dapat diakses melalui alat canggih (kudu). Setiap respons HTTP juga akan berisi Proxy-Trace-Location header dengan URL untuk mengakses file log.

Anda dapat men-debug proksi dari sisi klien dengan menambahkan Proxy-Trace-Enabled header yang diatur ke true. Ini juga akan mencatat jejak ke sistem file, dan mengembalikan URL jejak sebagai header dalam respons.

Memblokir jejak proksi

Untuk alasan keamanan, Anda mungkin tidak ingin mengizinkan siapa pun yang menghubungi layanan Anda untuk membuat jejak. Mereka tidak akan dapat mengakses konten jejak tanpa kredensial masuk Anda, tetapi menghasilkan jejak akan mengonsumsi sumber daya dan memperlihatkan Anda sedang menggunakan Proksi Fungsi.

Nonaktifkan jejak sama sekali dengan menambahkan "debug":false ke proksi tertentu di proxies.json Anda.

Konfigurasi tingkat lanjut

Proksi yang Anda konfigurasi disimpan dalam file proxies.json, yang terletak di akar direktori aplikasi fungsi. Anda dapat mengedit file ini secara manual dan menyebarkannya sebagai bagian dari aplikasi saat menggunakan salah satu metode penyebaran yang didukung Functions.

Tip

Jika Anda belum menyiapkan salah satu metode penyebaran, Anda juga dapat bekerja dengan file proxies.json di portal. Buka aplikasi fungsi Anda, pilih Fitur platform, lalu pilih Penyunting Azure App Service. Dengan demikian, Anda dapat melihat seluruh struktur file aplikasi fungsi Anda lalu membuat perubahan.

Proxies.json ditentukan oleh objek proksi, yang terdiri dari proksi bernama beserta definisinya. Secara opsional, jika penyunting Anda mendukungnya, Anda dapat mereferensikan skema JSON untuk penyelesaian kode. Contoh file mungkin terlihat seperti berikut ini:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Setiap proksi memiliki nama yang mudah, seperti proxy1 pada contoh sebelumnya. Objek definisi proksi yang sesuai ditentukan oleh properti berikut ini:

matchCondition: Diperlukan--objek mendefinisikan permintaan yang memicu eksekusi proksi ini. Ini berisi dua properti yang dibagikan dengan pemicu HTTP:
- metode: Larik metode HTTP yang direspons proksi. Jika tidak ditentukan, proksi merespons semua metode HTTP pada rute tersebut.
- rute: Diperlukan--mendefinisikan templat rute, mengontrol URL permintaan mana yang direspons proksi Anda. Tidak seperti pemicu HTTP, tidak ada nilai default.
backendUri: URL sumber back-end yang permintaannya harus diproksikan. Nilai ini dapat mereferensikan pengaturan aplikasi dan parameter dari permintaan klien asli. Jika properti ini tidak disertakan, Azure Functions merespons dengan HTTP 200 OK.
requestOverrides: Objek yang mendefinisikan transformasi ke permintaan back-end. Lihat Menentukan objek requestOverrides.
responseOverrides: Objek yang mendefinisikan transformasi ke respons klien. Lihat Menentukan objek responseOverrides.

Catatan

Properti rute di Proksi Azure Functions tidak terpengaruh properti routePrefix dari konfigurasi host Aplikasi Fungsi. Jika Anda ingin menyertakan prefiks seperti /api, harus disertakan dalam properti rute.

Menonaktifkan proksi individual

Anda dapat menonaktifkan proksi individual dengan menambahkan "disabled": true ke proksi dalam file proxies.json. Langkah ini akan menyebabkan permintaan apa pun memenuhi matchCondition untuk mengembalikan 404.

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "Root": {
            "disabled":true,
            "matchCondition": {
                "route": "/example"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>"
        }
    }
}

Pengaturan Aplikasi

Perilaku proksi dapat dikontrol oleh beberapa pengaturan aplikasi. Semuanya diuraikan dalam referensi Pengaturan Aplikasi Fungsi

Karakter Yang Dipesan (pemformatan string)

Proksi membaca semua string dari file JSON, menggunakan \ sebagai simbol escape. Proksi juga menafsirkan tanda kurung kurawal. Lihat contoh lengkap di bawah ini.

karakter	Karakter yang Lolos	Contoh
{ atau }	{{ atau }}	`{{ example }}` -->`{ example }`
\	\\	`example.com\\text.html` -->`example.com\text.html`
"	\"	`\"example\"` -->`"example"`

Menentukan objek requestOverrides

Objek requestOverrides menentukan perubahan yang dilakukan pada permintaan ketika sumber back-end dipanggil. Objek ditentukan oleh properti berikut:

backend.request.method: Metode HTTP yang digunakan untuk memanggil back-end.
backend.request.querystring.<ParameterName>: Parameter string kueri yang dapat diatur untuk panggilan ke back-end. Ganti <ParameterName> dengan nama parameter yang ingin Anda atur. Jika string kosong disediakan, parameter masih disertakan pada permintaan back-end.
backend.request.headers.<HeaderName>: Header yang dapat diatur untuk panggilan ke back-end. Ganti <HeaderName> dengan nama header yang ingin Anda atur. Jika string kosong disediakan, parameter masih disertakan pada permintaan back-end.

Nilai dapat mereferensikan pengaturan aplikasi dan parameter dari permintaan klien asli.

Contoh konfigurasi mungkin terlihat seperti berikut ini:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "backendUri": "https://<AnotherApp>.azurewebsites.net/api/<FunctionName>",
            "requestOverrides": {
                "backend.request.headers.Accept": "application/xml",
                "backend.request.headers.x-functions-key": "%ANOTHERAPP_API_KEY%"
            }
        }
    }
}

Menentukan objek responseOverrides

Objek requestOverrides menentukan perubahan yang dibuat pada respons yang diteruskan kembali ke klien. Objek ditentukan oleh properti berikut:

response.statusCode: Kode status HTTP yang akan dikembalikan ke klien.
response.statusReason: Frasa alasan HTTP untuk dikembalikan ke klien.
response.body: Representasi untai isi yang akan dikembalikan ke klien.
response.headers.<HeaderName>: Header yang dapat diatur untuk respons terhadap klien. Ganti <HeaderName> dengan nama header yang ingin Anda atur. Jika Anda memberikan untai kosong, header tidak disertakan pada respons.

Nilai dapat mereferensikan pengaturan aplikasi, parameter dari permintaan klien asli, dan parameter dari respons back-end.

Contoh konfigurasi mungkin terlihat seperti berikut ini:

{
    "$schema": "http://json.schemastore.org/proxies",
    "proxies": {
        "proxy1": {
            "matchCondition": {
                "methods": [ "GET" ],
                "route": "/api/{test}"
            },
            "responseOverrides": {
                "response.body": "Hello, {test}",
                "response.headers.Content-Type": "text/plain"
            }
        }
    }
}

Catatan

Dalam contoh ini, isi respons diatur secara langsung, jadi tidak ada backendUri properti yang diperlukan. Contoh menunjukkan bagaimana Anda dapat menggunakan Proksi Azure Functions untuk mengimitasi API.

Bagikan melalui

Bekerja dengan proksi lama

Mengaktifkan kembali proksi di Functions v4.x

Membuat proksi

Mengubah permintaan dan respons

Mengubah permintaan back-end

Mengubah respons

Menggunakan variabel

Referensi fungsi lokal

Referensi parameter permintaan

Parameter templat rute

Parameter permintaan tambahan

Referensi parameter respons back-end

Referensi pengaturan aplikasi

Memecahkan masalah Proksi

Memblokir jejak proksi

Konfigurasi tingkat lanjut

Menonaktifkan proksi individual

Pengaturan Aplikasi

Karakter Yang Dipesan (pemformatan string)

Menentukan objek requestOverrides

Menentukan objek responseOverrides

Sumber Daya Tambahan: