Kebijakan dalam Manajemen API Azure

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Di Azure API Management, penerbit API dapat mengubah perilaku API melalui konfigurasi menggunakan kebijakan. Kebijakan adalah kumpulan pernyataan yang berjalan secara berurutan atas permintaan atau respons API. API Management menyediakan lebih dari 50 kebijakan di luar kotak yang dapat Anda konfigurasi untuk mengatasi skenario API umum seperti autentikasi, pembatasan laju, penembolokan, dan transformasi permintaan atau respons. Untuk daftar lengkapnya, lihat Referensi kebijakan API Management.

Kebijakan populer meliputi:

  • Konversi format dari XML ke JSON
  • Pembatasan tarif panggilan untuk membatasi jumlah panggilan masuk dari pengembang
  • Memfilter permintaan yang berasal dari alamat IP tertentu

Kebijakan diterapkan di dalam gateway yang berada di antara konsumen API dan API terkelola. Sementara gateway menerima permintaan dan meneruskannya dan tidak berubah ke API yang mendasarinya, kebijakan dapat menerapkan perubahan pada permintaan masuk dan respons keluar.

Memahami konfigurasi kebijakan

Definisi kebijakan adalah dokumen XML sederhana yang menjelaskan urutan pernyataan yang akan diterapkan pada permintaan dan respons. Untuk membantu Anda mengonfigurasi definisi kebijakan, portal menyediakan opsi ini:

  • Editor berbasis formulir yang dipandu untuk menyederhanakan konfigurasi kebijakan populer tanpa mengkodekan XML
  • Editor kode tempat Anda dapat menyisipkan cuplikan XML atau mengedit XML secara langsung

Untuk informasi selengkapnya tentang mengonfigurasi kebijakan, lihat Kebijakan dalam API Management.

Konfigurasi XML kebijakan dibagi menjadi bagian inbound, backend, outbound, dan on-error. Serangkaian pernyataan kebijakan yang ditentukan ini dijalankan untuk permintaan dan tanggapan.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Untuk contoh XML kebijakan, lihat repositori cuplikan kebijakan API Management.

Penanganan kesalahan

Jika terjadi kesalahan selama pemrosesan permintaan:

  • Setiap langkah yang tersisa di bagian inbound, backend, atau outbound dilewati.
  • Eksekusi melompat ke pernyataan di on-error bagian.

Dengan menempatkan pernyataan kebijakan di on-error bagian tersebut, Anda dapat:

  • Tinjau kesalahan menggunakan context.LastError properti.
  • Memeriksa dan menyesuaikan respons kesalahan menggunakan set-body kebijakan.
  • Konfigurasikan apa yang terjadi jika terjadi kesalahan.

Untuk informasi selengkapnya, lihat Penanganan kesalahan dalam kebijakan API Management.

Ekspresi kebijakan

Kecuali jika kebijakan menentukan lain, ekspresi kebijakan dapat digunakan sebagai nilai atribut atau nilai teks di salah satu kebijakan API Management. Ekspresi kebijakan adalah:

  • satu pernyataan C# yang terlampir dalam @(expression), atau
  • blok kode C# multi-pernyataan, terlampir dalam @{expression}, yang mengembalikan nilai

Setiap ekspresi memiliki akses ke variabel context yang disediakan secara implisit dan subset yang diizinkan dari jenis .NET Framework.

Ekspresi kebijakan menyediakan cara canggih untuk mengontrol lalu lintas dan memodifikasi perilaku API tanpa mengharuskan Anda menulis kode khusus atau memodifikasi layanan backend. Beberapa kebijakan didasarkan pada ekspresi kebijakan, seperti Alur kontrol dan Atur variabel.

Cakupan

API Management memungkinkan Anda menentukan kebijakan pada cakupan berikut, dari yang paling luas hingga paling sempit:

  • Global (semua API)
  • Ruang kerja (semua API yang terkait dengan ruang kerja yang dipilih)
  • Produk (semua API yang terkait dengan produk yang dipilih)
  • API (semua operasi dalam API)
  • Operasi (operasi tunggal dalam API)

Ketika mengonfigurasi kebijakan, Anda harus terlebih dahulu memilih cakupan penerapan kebijakan.

Cakupan kebijakan

Hal-hal yang perlu diketahui

  • Untuk kontrol mendetail bagi konsumen API yang berbeda, Anda dapat mengonfigurasi definisi kebijakan pada lebih dari satu cakupan

  • Tidak semua kebijakan didukung di setiap cakupan dan bagian kebijakan

  • Saat mengonfigurasi definisi kebijakan pada lebih dari satu cakupan, Anda mengontrol pewarisan kebijakan dan urutan evaluasi kebijakan di setiap bagian kebijakan berdasarkan penempatan base elemen

  • Kebijakan yang diterapkan pada permintaan API juga dipengaruhi oleh konteks permintaan, termasuk ada atau tidaknya kunci langganan yang digunakan dalam permintaan, API atau cakupan produk kunci langganan, dan apakah API atau produk memerlukan langganan.

    Catatan

    Jika Anda menggunakan langganan tercakup API, langganan semua API, atau langganan semua akses bawaan, kebijakan yang dikonfigurasi pada cakupan produk tidak diterapkan ke permintaan dari langganan tersebut.

Untuk informasi selengkapnya, lihat:

Kebijakan penyelesai GraphQL

Di API Management, pemecah masalah GraphQL dikonfigurasi menggunakan kebijakan yang dilingkup ke jenis dan bidang operasi tertentu dalam skema GraphQL.

  • Saat ini, API Management mendukung pemecah masalah GraphQL yang menentukan SUMBER data HTTP API, Cosmos DB, atau Azure SQL. Misalnya, konfigurasikan satu http-data-source kebijakan dengan elemen untuk menentukan permintaan ke (dan respons opsional dari) sumber data HTTP.
  • Anda tidak dapat menyertakan kebijakan resolver dalam definisi kebijakan di cakupan lain seperti API, produk, atau semua API. Ini juga tidak mewarisi kebijakan yang dikonfigurasi pada cakupan lain.
  • Gateway mengevaluasi kebijakan yang dilingkup pemecah masalah setelah setiap kebijakan dan backend yang dikonfigurasi inbound dalam alur eksekusi kebijakan.

Untuk informasi selengkapnya, lihat Mengonfigurasi pemecah masalah GraphQL.

Mendapatkan bantuan dalam membuat kebijakan menggunakan Microsoft Copilot for Azure (pratinjau)

Microsoft Copilot for Azure (pratinjau) menyediakan kemampuan penulisan kebijakan untuk Azure API Management. Gunakan Copilot for Azure dalam konteks editor kebijakan API Management untuk membuat kebijakan yang sesuai dengan persyaratan spesifik Anda tanpa mengetahui sintaks, atau telah mengonfigurasi kebijakan yang dijelaskan kepada Anda.

Anda dapat meminta Copilot for Azure untuk menghasilkan definisi kebijakan, lalu menyalin hasilnya ke editor kebijakan dan membuat penyesuaian yang diperlukan. Ajukan pertanyaan untuk mendapatkan wawasan tentang berbagai opsi, memodifikasi kebijakan yang disediakan, atau mengklarifikasi kebijakan yang sudah Anda miliki. Pelajari lebih lanjut

Penting

Microsoft Copilot for Azure (pratinjau) memerlukan pendaftaran dan saat ini hanya tersedia untuk pelanggan dan mitra perusahaan yang disetujui. Untuk informasi selengkapnya, lihat Akses terbatas ke Microsoft Copilot for Azure (pratinjau).

Contoh

Menerapkan kebijakan yang ditentukan pada lingkup yang berbeda

Jika Anda memiliki kebijakan di tingkat global dan kebijakan yang dikonfigurasi untuk API, kedua kebijakan akan diterapkan setiap kali API tertentu tersebut digunakan. API Management memungkinkan pemesanan deterministik dari pernyataan kebijakan gabungan melalui elemen base.

Contoh definisi kebijakan di cakupan API:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Dalam contoh definisi kebijakan di atas:

  • Pernyataan cross-domain akan dijalankan terlebih dahulu.
  • find-and-replace kebijakan akan dijalankan setelah kebijakan apa pun pada cakupan yang lebih luas.

Catatan

Jika Anda menghapus elemen base di cakupan API, hanya kebijakan yang dikonfigurasi di cakupan API lah yang akan diterapkan. Baik kebijakan lingkup produk maupun global tidak akan diterapkan.

Menggunakan ekspresi kebijakan untuk mengubah permintaan

Contoh berikut menggunakan ekspresi kebijakan dan kebijakan set-header untuk menambahkan data ke permintaan masuk. Header yang ditambahkan termasuk ID pengguna yang terkait dengan kunci langganan dalam permintaan, dan wilayah yang merupakan tempat hosting gateway yang memproses permintaan.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Konten terkait

Untuk informasi selengkapnya tentang bekerja dengan kebijakan, lihat: