Bagikan melalui

Backend di API Management

BERLAKU UNTUK: Semua tingkatan API Management

Sebuah backend (atau backend API) di API Management adalah layanan HTTP yang mengimplementasikan API front-end dan operasinya.

Saat Anda mengimpor API tertentu, API Management secara otomatis mengonfigurasi backend API. Misalnya, API Management mengonfigurasi layanan web backend saat mengimpor:

Untuk API lain, seperti API dari layanan Azure, Anda mengimpor sumber daya Azure tanpa menentukan layanan backend secara eksplisit. Contohnya meliputi:

API Management juga mendukung penggunaan sumber daya lain sebagai backend API, seperti:

Untuk backend ini, Anda dapat membuat entitas backend di API Management dan mereferensikannya di API Anda.

Manfaat dari backend

API Management mendukung entitas backend sehingga Anda dapat mengelola layanan backend API Anda. Entitas backend merangkum informasi tentang layanan backend, mempromosikan penggunaan kembali di seluruh API dan meningkatkan tata kelola.

Gunakan backend untuk satu atau beberapa hal berikut:

  • Mengotorisasi kredensial permintaan ke layanan backend
  • Manfaatkan fungsionalitas API Management untuk mempertahankan rahasia di Azure Key Vault jika nilai bernama dikonfigurasi untuk autentikasi parameter header atau kueri
  • Tentukan aturan pemutus sirkuit untuk melindungi backend Anda dari terlalu banyak permintaan
  • Mengalihkan atau menyeimbangkan beban permintaan ke beberapa layanan backend

Konfigurasikan dan kelola entitas backend di portal Microsoft Azure, atau dengan menggunakan API atau alat Azure.

Membuat backend

Anda dapat membuat backend di portal Microsoft Azure, atau dengan menggunakan API atau alat Azure.

Catatan

Saat Anda mengimpor API tertentu, seperti API dari Microsoft Foundry atau layanan AI lainnya, API Management secara otomatis mengonfigurasi entitas backend.

Untuk membuat backend di portal:

  1. Masuk ke portal dan buka instans API Management Anda.
  2. Di menu sebelah kiri, pilih API>Backends>+ Buat backend baru.
  3. Pada halaman Backend , selesaikan langkah-langkah berikut ini:
    1. Masukkan Nama untuk deskripsi backend dan opsional.
    2. Pilih jenis hosting Backend, seperti sumber daya Azure untuk sumber daya Azure seperti Aplikasi Fungsi atau Aplikasi Logika, URL Kustom untuk layanan kustom, atau kluster Service Fabric .
    3. Di URL Runtime, masukkan URL layanan backend tempat permintaan API diteruskan.
    4. Di bawah Tingkat Lanjut, secara opsional nonaktifkan rantai sertifikat atau validasi nama sertifikat untuk backend.
    5. Di bawah Tambahkan layanan backend ini ke kumpulan backend, secara opsional pilih atau buat kumpulan seimbang beban untuk backend.
    6. Di bawah Aturan pemutus arus, secara opsional konfigurasikan pemutus sirkuit untuk backend.
    7. Di bawah Kredensial otorisasi, konfigurasikan kredensial secara opsional untuk mengotorisasi akses ke backend. Opsi termasuk header permintaan, parameter kueri, sertifikat klien, atau identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna yang dikonfigurasi dalam instans API Management.
    8. Pilih Buat.

Setelah membuat backend, Anda dapat memperbarui pengaturan backend kapan saja. Misalnya, Anda dapat menambahkan aturan pemutus sirkuit, mengubah URL runtime, atau menambahkan kredensial otorisasi.

Mengonfigurasi identitas terkelola untuk kredensial otorisasi

Anda dapat menggunakan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna yang dikonfigurasi dalam instans API Management untuk mengotorisasi akses ke layanan backend. Untuk mengonfigurasi identitas terkelola untuk kredensial otorisasi, selesaikan langkah-langkah berikut:

  1. Di bagian Kredensial otorisasi dari konfigurasi backend, pilih tab Identitas terkelola , dan pilih Aktifkan.

  2. Di Identitas klien, pilih Identitas yang ditetapkan sistem atau identitas yang ditetapkan pengguna yang Anda konfigurasikan dalam instans Anda.

  3. Di ID Sumber Daya, masukkan layanan Azure target atau ID aplikasi aplikasi Microsoft Entra Anda sendiri yang mewakili backend. Misalnya, masukkan https://cognitiveservices.azure.com untuk layanan Azure OpenAI.

    Untuk contoh selengkapnya, lihat referensi kebijakan identitas terkelola autentikasi .

  4. Pilih Buat.

Catatan

Tetapkan juga identitas terkelola dengan memberikan izin yang sesuai atau peran RBAC untuk mengakses layanan backend. Misalnya, jika backend adalah layanan Azure OpenAI, tetapkan peran identitas terkelola Cognitive Services User .

Mengonfigurasi sertifikat untuk kredensial otorisasi

Anda dapat mengamankan akses gateway ke layanan backend dengan menggunakan autentikasi TLS bersama dengan sertifikat klien atau sertifikat otoritas sertifikat kustom (CA).

Mengonfigurasi sertifikat klien

Jika layanan backend diamankan dengan sertifikat yang dikeluarkan oleh CA terkenal, Anda dapat menambahkan sertifikat klien di entitas backend:

  1. Tambahkan sertifikat ke instans API Management. Anda dapat mereferensikan sertifikat yang dikelola di Azure Key Vault atau mengunggah file PFX.
  2. Di bagian Kredensial otorisasi dari konfigurasi backend, pilih tab Sertifikat klien .
  3. Di menu dropdown, pilih sertifikat klien yang ingin Anda gunakan.
  4. Pilih Buat.

Mengonfigurasi sertifikat CA

Jika layanan backend menggunakan sertifikat CA kustom, Anda dapat mereferensikan sertifikat CA kustom di entitas backend. Anda mungkin perlu melakukan langkah ini untuk membangun kepercayaan untuk sertifikat server backend - misalnya, dengan sertifikat yang ditandatangani sendiri, sertifikat akar yang tidak tepercaya, atau rantai sertifikat parsial.

Catatan

Saat ini, Anda hanya dapat mengonfigurasi detail sertifikat CA di entitas backend di tingkat v2.

Untuk menambahkan detail sertifikat CA, ikuti langkah-langkah berikut:

  1. Di bagian Kredensial otorisasi dari konfigurasi backend, pilih Sertifikat CA.
  2. Pilih + Tambahkan detail sertifikat CA.
  3. Di panel Tambahkan sertifikat CA , pilih salah satu opsi berikut ini:
    • Sidik jari sertifikat - Masukkan sidik jari (hash SHA-1, SHA-256, atau SHA-512) dari sertifikat CA yang disesuaikan.
    • Nama subjek dan thumbprint penerbit - Masukkan nama subjek yang secara unik mengidentifikasi CA dan thumbprint dari CA.
  4. Pilih Tambahkan.
  5. Pilih Buat.

Cuplikan layar mengonfigurasi detail sertifikat CA untuk backend di portal.

Catatan

Saat Anda mengonfigurasi detail sertifikat CA kustom di entitas backend, API Management selalu memvalidasi nama sertifikat dan rantai sertifikat, terlepas dari apakah Anda mengaktifkan atau menonaktifkan pengaturan validasi di backend backendTlsProperties.

Petunjuk / Saran

Anda juga dapat mengonfigurasi detail sertifikat CA secara terprogram dengan menggunakan API Management REST API. Atur backendTlsProperties pada entitas backend.

Mengacu pada backend menggunakan kebijakan set-backend-service

Setelah membuat backend, Anda dapat mereferensikan pengidentifikasi backend (nama) di API Anda. set-backend-service Gunakan kebijakan untuk mengarahkan permintaan API masuk ke backend. Jika Anda sudah mengonfigurasi layanan web backend untuk API, Anda dapat menggunakan set-backend-service kebijakan untuk mengalihkan permintaan ke entitas backend sebagai gantinya. Contoh:

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

Catatan

Atau, Anda dapat menggunakan base-url. Biasanya, formatnya adalah https://backend.com/api. Hindari menambahkan garis miring (/) di akhir untuk mencegah kesalahan konfigurasi. Biasanya, nilai titik akhir HTTP(S) dan nilai di backend harus cocok untuk memungkinkan integrasi yang mulus antara frontend dan backend. Perhatikan bahwa instans API Management menambahkan nama layanan backend ke base-url.

Anda dapat menggunakan logika kondisional dengan kebijakan set-backend-service untuk mengubah backend yang efektif berdasarkan lokasi, gateway yang digunakan, atau ekspresi lainnya.

Misalnya, berikut adalah kebijakan untuk merutekan lalu lintas ke backend lain berdasarkan gateway yang dipanggil:

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

Petunjuk / Saran

API Management juga secara otomatis mendeteksi dan menggunakan entitas backend saat menerima permintaan API. Pada runtime, jika ada entitas backend yang cocok dengan URL layanan backend tempat API Management mengirim permintaan, api management akan menggunakan entitas backend. Anda tidak perlu secara eksplisit menggunakan set-backend-service.

Pemutus sirkuit

API Management mengekspos properti pemutus sirkuit di sumber daya backend untuk melindungi layanan backend agar tidak kewalahan oleh terlalu banyak permintaan.

  • Properti pemutus arus menentukan aturan untuk melakukan perjalanan pemutus sirkuit, seperti jumlah atau persentase kondisi kegagalan selama interval waktu yang ditentukan dan rentang kode status yang menunjukkan kegagalan.
  • Ketika pemutus sirkuit memutus, API Management berhenti mengirim permintaan ke layanan backend untuk sementara waktu, dan mengembalikan respons 503 Layanan Tidak Tersedia kepada klien.
  • Setelah durasi perjalanan yang dikonfigurasi, sirkuit mengatur ulang dan lalu lintas dilanjutkan ke backend.

Pemutus sirkuit backend adalah implementasi pola pemutus sirkuit untuk memungkinkan backend pulih dari situasi kelebihan beban. Ini menambah kebijakan pembatasan tarif umum dan pembatasan konkurensi yang dapat Anda terapkan untuk melindungi gateway API Management dan layanan backend Anda.

Catatan

  • Saat ini, pemutus sirkuit backend tidak didukung di tingkat Konsumsi API Management.
  • Karena sifat arsitektur API Management yang didistribusikan, aturan tripping pemutus arus adalah perkiraan. Instans gateway yang berbeda tidak menyinkronkan dan menerapkan aturan pemutus arus berdasarkan informasi pada instans yang sama.
  • Saat ini, Anda hanya dapat mengonfigurasi satu aturan untuk pemutus arus backend.

Caution

Jika Anda mengonfigurasi layanan Azure OpenAI sebagai backend dan layanan menerima terlalu banyak permintaan, layanan mengembalikan 429 Too Many Requests kode status respons dan Retry-After header dengan nilai yang bisa besar (misalnya, 1 hari). Dengan backend Azure OpenAI, terapkan aturan pemutus sirkuit untuk menangani 429 respons serta menerima durasi Retry-After.

Contoh

Gunakan portal Microsoft Azure, API Management REST API, atau templat Bicep atau ARM untuk mengonfigurasi pemutus sirkuit di backend. Dalam contoh berikut, pemutus sirkuit di myBackend dalam perjalanan myAPIM instans API Management ketika ada tiga atau beberapa 5xx kode status yang menunjukkan kesalahan server dalam 1 jam.

Pemutus sirkuit dalam contoh ini diatur ulang setelah 1 jam. Jika header Retry-After ada dalam respons, pemutus rangkaian menerima nilai tersebut dan menunggu selama waktu yang telah ditentukan sebelum mengirim permintaan ke backend lagi.

  1. Di portal Microsoft Azure, buka instans API Management Anda.
  2. Di menu sebelah kiri, pilih API>Backends> backend Anda.
  3. Di halaman backend, pilih Pengaturan>Pengaturan Pemutus Sirkuit>Tambahkan baru.
  4. Di halaman Buat pemutus sirkuit baru , konfigurasikan aturan:
    • Nama aturan: Masukkan nama untuk aturan, seperti myBackend.
    • Jumlah kegagalan: Masukkan 3.
    • Interval kegagalan: Biarkan nilai default 1 jam.
    • Rentang kode status kegagalan: Pilih 500 - 599.
    • Durasi perjalanan: Biarkan nilai default 1 jam.
    • Periksa header 'Coba Lagi-Setelah' dalam respons HTTP: Pilih Benar (Terima).

Kumpulan server dengan penyeimbang beban

API Management mendukung kumpulan backend saat Anda ingin menerapkan beberapa backend untuk API dan menyeimbangkan beban permintaan di antara backend-backend tersebut. Grup adalah sekumpulan backend yang diperlakukan sebagai satu entitas untuk penyeimbangan beban.

Gunakan kumpulan backend untuk skenario seperti skenario berikut:

  • Sebarkan beban ke beberapa backend, yang mungkin memiliki pemutus sirkuit backend individual.
  • Geser beban dari satu set backend ke set lain untuk peningkatan (penyebaran biru-hijau).

Catatan

  • Anda dapat menyertakan hingga 30 backend dalam kumpulan.
  • Karena sifat terdistribusi dari arsitektur API Management, penyeimbangan beban pada backend dilakukan secara mendekati. Instans gateway yang berbeda tidak menyinkronkan dan menyeimbangkan beban berdasarkan informasi pada instans yang sama.

Opsi penyeimbangan muatan

API Management mendukung opsi penyeimbangan beban berikut untuk kumpulan backend:

Opsi penyeimbangan beban Deskripsi
Round-robin Permintaan didistribusikan secara merata di seluruh backend di kumpulan secara default.
Tertimbang Tetapkan bobot ke backend di kumpulan, dan distribusikan permintaan berdasarkan bobot relatif setiap backend. Berguna untuk skenario seperti penyebaran biru-hijau.
Berbasis prioritas Atur backend ke dalam grup prioritas. Kirim permintaan ke grup prioritas yang lebih tinggi terlebih dahulu; dalam grup, distribusikan permintaan secara merata atau sesuai dengan bobot yang ditetapkan.

Catatan

Layanan API Management menggunakan backend dalam grup prioritas yang lebih rendah hanya ketika semua backend dalam grup prioritas yang lebih tinggi tidak tersedia karena aturan pemutus arus tersandung.

Pemantauan sesi

Dengan salah satu opsi penyeimbangan beban sebelumnya, Anda dapat mengaktifkan pengenalan sesi (afinitas sesi) untuk memastikan bahwa semua permintaan dari pengguna tertentu selama sesi dialihkan ke backend yang sama dalam pool. API Management menetapkan cookie ID sesi untuk mempertahankan status sesi. Opsi ini berguna, misalnya, dalam skenario dengan backend seperti asisten obrolan AI atau agen percakapan lainnya untuk merutekan permintaan dari sesi yang sama ke titik akhir yang sama.

Catatan

Kemampuan mengenali sesi dalam pool dengan pembagian beban akan dirilis pertama kali ke Kelompok Pembaruan AwalGateway AI.

Mengelola cookie untuk pemantauan sesi

Ketika Anda menggunakan pemahaman sesi, klien harus menangani cookie dengan tepat. Klien perlu menyimpan Set-Cookie nilai header dan mengirimkannya dengan permintaan berikutnya untuk mempertahankan status sesi.

Anda dapat menggunakan kebijakan API Management untuk membantu mengatur cookie untuk kesadaran sesi. Misalnya, untuk kasus Assistants API (fitur Azure OpenAI di Microsoft Foundry Models), klien perlu menyimpan ID sesi, mengekstrak ID thread dari isi, dan mempertahankan kombinasi serta mengirimkan cookie yang sesuai untuk setiap panggilan. Selain itu, klien perlu tahu kapan harus mengirim cookie atau kapan tidak mengirim header cookie. Persyaratan ini dapat ditangani dengan tepat dengan menentukan contoh kebijakan berikut:

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Contoh

Gunakan portal, API Management REST API, atau templat Bicep atau ARM untuk mengonfigurasi kumpulan backend. Dalam contoh berikut, backend myBackendPool dalam instans API Management myAPIM dikonfigurasi dengan kumpulan backend. Contoh backend di kumpulan diberi nama backend-1 dan backend-2. Kedua backend berada dalam grup prioritas tertinggi; dalam grup, backend-1 memiliki bobot yang lebih besar daripada backend-2.

  1. Di portal Microsoft Azure, buka instans API Management Anda.
  2. Di menu sebelah kiri, pilih API>Backends> backend Anda.
  3. Di halaman Backend , pilih tab Load balancer .
  4. Pilih + Buat kumpulan baru.
  5. Di halaman Buat kumpulan seimbang beban baru , masukkan informasi berikut ini:
    • Nama: Masukkan nama untuk kumpulan seperti myBackendPool.
    • Deskripsi: Secara opsional masukkan deskripsi.
    • Menambahkan backend ke kumpulan: Pilih satu atau beberapa backend untuk ditambahkan ke kumpulan.
    • Berat dan prioritas backend: Pilih Sesuaikan berat dan prioritas untuk mengonfigurasi berat dan prioritas setiap backend di kumpulan. Misalnya, jika Anda menambahkan dua backend bernama backend-1 dan backend-2, atur berat backend-1 ke 3 dan berat backend-2 ke 1, dan atur prioritas kedua backend menjadi 1.
    • Pilih Buat.

Batasan

Konten terkait

  • Last updated on