Kebijakan di Azure API Management

BERLAKU UNTUK: Semua tingkatan manajemen API

Di Azure API Management, penerbit API dapat mengubah perilaku API melalui konfigurasi dengan menggunakan kebijakan. Artikel ini menjelaskan cara menggunakan kebijakan.

Kebijakan adalah kumpulan pernyataan yang dijalankan secara berurutan pada permintaan atau respons API. API Management menyediakan lebih dari 75 kebijakan bawaan yang dapat Anda konfigurasi untuk menangani skenario API umum seperti autentikasi, pembatasan laju, penyimpanan sementara, dan transformasi permintaan dan 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.
• Pemfilteran permintaan yang berasal dari alamat IP tertentu.

Kebijakan diterapkan di dalam gateway antara konsumen API dan API terkelola. Meskipun gateway menerima permintaan dan meneruskannya, tidak diubah, ke API yang mendasar, kebijakan dapat menerapkan perubahan pada permintaan masuk dan respons keluar.

Memahami konfigurasi kebijakan

Definisi kebijakan adalah dokumen XML sederhana yang menjelaskan urutan pernyataan untuk 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 mengkoding XML
• Editor kode tempat Anda dapat menyisipkan cuplikan XML atau mengedit XML secara langsung

Untuk informasi selengkapnya tentang mengonfigurasi kebijakan, lihat Mengatur atau mengedit kebijakan.

Konfigurasi XML kebijakan dibagi menjadi inbound, backend, outbound, dan bagian on-error. Rangkaian pernyataan kebijakan yang ditentukan ini dijalankan dalam urutan untuk permintaan dan tanggapan. Berikut tampilannya:

<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's 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 beralih ke pernyataan di bagian on-error.

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

• Tinjau kesalahan dengan menggunakan context.LastError properti .
• Periksa dan sesuaikan respons kesalahan menggunakan kebijakan set-body.
• Konfigurasikan apa yang terjadi jika terjadi kesalahan.

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

Ekspresi kebijakan

Kecuali kebijakan menentukan sebaliknya, ekspresi kebijakan dapat digunakan sebagai nilai atribut atau nilai teks dalam salah satu kebijakan API Management. Ekspresi kebijakan adalah salah satu hal berikut:

• Pernyataan C# tunggal yang diapit dalam @(expression)
• Blok kode C# berisi banyak pernyataan, diapit 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.

Ruang Lingkup

API Management memungkinkan Anda menentukan kebijakan pada cakupan berikut, yang disajikan di sini dari yang terluas hingga tersempit:

• 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 (satu operasi dalam API)

Saat mengonfigurasi kebijakan, Anda harus terlebih dahulu memilih cakupan tempat kebijakan diterapkan.

Hal-hal yang perlu diketahui

• Untuk kontrol halus untuk 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.

  Nota

  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:

• Mengatur atau mengedit kebijakan
• Langganan pada Manajemen API

Kebijakan resolver GraphQL

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

• Saat ini, API Management mendukung resolver GraphQL yang menentukan sumber data HTTP API, Azure Cosmos DB, atau Azure SQL. Misalnya, Anda dapat mengonfigurasi 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. Kebijakan ini juga tidak mewarisi kebijakan yang dikonfigurasi pada cakupan lain.
• Gateway mengevaluasi kebijakan yang dilingkup resolusi setelah setiap kebijakan inbound dan backend yang dikonfigurasi dalam alur eksekusi kebijakan.

Untuk informasi selengkapnya, lihat Mengonfigurasi pemecah masalah GraphQL.

Dapatkan bantuan Copilot

Anda bisa mendapatkan bantuan AI dari Copilot untuk membuat dan mengedit definisi kebijakan API Management Anda. Anda dapat menggunakan Copilot untuk membuat dan memperbarui kebijakan yang sesuai dengan persyaratan spesifik Anda tanpa perlu mengetahui sintaks XML. Anda juga bisa mendapatkan penjelasan tentang kebijakan yang ada. Dan Copilot dapat membantu Anda menerjemahkan kebijakan yang mungkin telah Anda konfigurasikan di solusi manajemen API lainnya.

• Microsoft Copilot di Azure menyediakan bantuan penulisan kebijakan dengan perintah bahasa alami di portal Microsoft Azure. Anda dapat menulis kebijakan di editor kebijakan API Management dan meminta Copilot untuk menjelaskan bagian kebijakan.
• GitHub Copilot untuk Azure di Visual Studio Code menyediakan bantuan penulisan kebijakan di Visual Studio Code, dan Anda dapat menggunakan Ekstensi Azure API Management untuk Visual Studio Code untuk mempercepat konfigurasi kebijakan. Anda dapat meminta Copilot Chat atau Copilot Edits dengan bahasa alami untuk membuat dan menyempurnakan definisi kebijakan di tempat.

Contoh perintah:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot didukung oleh AI, sehingga kejutan dan kesalahan dimungkinkan. Untuk informasi selengkapnya, lihat FAQ umum untuk Copilot.

Contoh

Menerapkan kebijakan yang ditentukan pada lingkup yang berbeda

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

Contoh definisi kebijakan di cakupan API:

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

Dalam contoh definisi kebijakan sebelumnya:

• Pernyataan cross-domain dijalankan lebih dulu.
• Kebijakanfind-and-replace ini berlangsung setelah kebijakan lainnya dalam lingkup yang lebih luas.

Nota

Jika Anda menghapus base elemen di cakupan API, hanya kebijakan yang dikonfigurasi pada cakupan API yang akan diterapkan. Kebijakan yang dikonfigurasi pada produk dan cakupan yang lebih luas tidak akan diterapkan.

Menggunakan ekspresi kebijakan untuk mengubah permintaan

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

<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 mengelola kebijakan, lihat:

• Tutorial: Mengubah dan melindungi API Anda
• Referensi Kebijakan untuk daftar lengkap pernyataan kebijakan dan pengaturannya
• Pernyataan kebijakan
• Mengatur atau mengedit kebijakan
• Gunakan ulang konfigurasi kebijakan
• Repositori cuplikan kebijakan
• Repositori taman bermain kebijakan
• Toolkit kebijakan untuk Azure API Management
• Mendapatkan bantuan Copilot untuk membuat, menjelaskan, dan memecahkan masalah kebijakan