Cara mengelola konfigurasi Manajemen API dengan APIOps CLI

BERLAKU UNTUK: Semua tingkatan manajemen API

APIOps CLI adalah alat konfigurasi-sebagai-kode untuk Azure API Management. Dalam artikel ini, Anda menggunakannya untuk mengekstrak konfigurasi Manajemen API ke dalam artefak lokal, meninjau artefak di Git, melihat pratinjau perubahan, dan mempublikasikan artefak yang disetujui ke instance Manajemen API. CLI juga dapat membuat file GitHub Actions atau Azure Pipelines untuk alur kerja APIOps.

Langkah-langkah tersebut menyediakan alur kerja minimal yang dapat Anda validasi dengan instance Manajemen API nonproduksi. Untuk panduan arsitektur dan desain, lihat Penerapan API otomatis dengan APIOps.

Gunakan alur kerja ini untuk:

  • Tinjau definisi API, kebijakan, dan konfigurasi Manajemen API lainnya melalui pull request.
  • Simpan riwayat yang dapat diaudit dari perubahan konfigurasi yang disetujui.
  • Promosikan artefak yang telah ditinjau antar lingkungan Manajemen API.
  • Mulailah dengan konfigurasi yang diekstrak dari instans yang sudah ada atau tulis artefak yang kompatibel dengan CLI di dalam kode.

APIOps CLI melengkapi pendekatan API DevOps yang dijelaskan dalam Menggunakan DevOps dan CI/CD untuk menerbitkan API. Evaluasilah CLI dan alur kerja artefak yang ingin Anda gunakan di lingkungan nonproduksi sebelum Anda menggunakannya untuk penerapan produksi.

Prasyarat

  • Node.js versi 22 atau yang lebih baru.
  • Azure CLI, untuk langkah-langkah autentikasi lokal dalam artikel ini.
  • Langganan Azure dan instance Manajemen API nonproduksi yang sudah ada.
  • Repositori Git untuk artefak Manajemen API Anda.
  • Sebuah identitas dengan akses ke instance API Management. Panduan memulai APIOps CLI mencantumkan peran Kontributor Layanan Manajemen API dan Pembaca pada cakupan sumber daya API Management untuk alur kerja ekstraksi dan publikasi.

Untuk otomatisasi produksi, gunakan identitas terpisah dengan hak istimewa paling rendah jika memungkinkan. Identitas ekstraksi memerlukan akses baca ke instance sumber. Identitas penerbit hanya memerlukan izin yang diperlukan untuk memperbarui instans target.

Instal APIOps CLI

@azure-tools/apiops-cli Install paket npm tersebut:

npm install -g @azure-tools/apiops-cli

Verifikasi versi yang diinstal:

apiops --version

Catat dan sematkan versi yang Anda setujui untuk alur CI/CD Anda. Tinjau changelog APIOps CLI sebelum Anda melakukan peningkatan.

Mengautentikasi ke Azure

Untuk penggunaan lokal, masuk dengan Azure CLI dan pilih langganan yang berisi instance Manajemen API nonproduksi Anda:

az login
az account set --subscription <subscription-id>

APIOps CLI menggunakan DefaultAzureCredential. Selain kredensial Azure CLI, aplikasi ini mendukung kredensial lingkungan, identitas beban kerja, identitas terkelola, kredensial Azure PowerShell, dan Azure Developer CLI.

Untuk CI/CD, sebaiknya gunakan federasi identitas beban kerja atau identitas terkelola alih-alih rahasia klien. Jangan pernah memasukkan kredensial, token akses, kunci langganan, atau nilai rahasia bernama dalam kontrol sumber. Untuk opsi autentikasi yang didukung, lihat panduan autentikasi APIOps CLI.

Siapkan repositori artefak

Jalankan perintah APIOps CLI dari root repositori Git yang berisi artefak Manajemen API Anda.

Untuk membuat struktur awal pipeline dan templat konfigurasi untuk GitHub Actions, jalankan:

apiops init --ci github-actions --environments dev,prod --non-interactive

Untuk Azure Pipelines, gunakan:

apiops init --ci azure-devops --environments dev,prod --non-interactive

Perintah ini membuat definisi alur, templat filter ekstraksi, templat penimpaan lingkungan, panduan penyiapan identitas, dan direktori apim-artifacts. Tinjau setiap file yang dihasilkan sebelum Anda melakukan commit atau mengaktifkan pipeline. Jangan gunakan --force dalam repositori yang sudah berisi file kecuali jika Anda meninjau file-file yang akan ditimpa oleh perintah tersebut.

Jika Anda sudah memiliki desain repositori dan pipeline, Anda dapat membuat atau memilih direktori artefak dan menggunakan perintah ekstrak dan publikasi secara langsung.

Buat artefak awal

Pilih salah satu pendekatan berikut untuk menetapkan artefak yang dimiliki repositori Anda.

Ekstrak konfigurasi yang sudah ada

Untuk membuat baseline dari instance API Management yang sudah ada, ekstrak konfigurasinya:

apiops extract \
  --subscription-id <source-subscription-id> \
  --resource-group <source-resource-group> \
  --service-name <source-apim-name> \
  --output ./apim-artifacts

Perintah ini membuat file informasi JSON, file kebijakan XML, dan file spesifikasi API dalam hierarki di bawah .apim-artifacts Untuk instance besar, konfigurasikan filter ekstraksi sehingga repositori hanya mengelola sumber daya yang diinginkan.

Mulailah dengan artefak berbasis kode

Untuk alur kerja code-first, tambahkan spesifikasi OpenAPI serta file informasi dan kebijakan API Management yang diperlukan dengan menggunakan format artefak CLI APIOps. Jangan berasumsi bahwa tata letak repositori aplikasi yang sudah ada atau file OpenAPI sendiri sudah siap untuk apiops publish.

Jika Anda baru mengenal format artefak, ekstrak terlebih dahulu API referensi berukuran kecil dari instans nonproduksi. Gunakan file hasil sebagai template, dan tinjau panduan alur kerja code-first.

Tinjau artefak

Sebelum Anda menerbitkan:

  1. Periksa file yang dihasilkan atau dibuat dan pastikan repositori hanya berisi sumber daya yang ingin Anda kelola.
  2. Tinjau spesifikasi API, kebijakan, backend, nilai bernama, produk, dan ketergantungannya.
  3. Hapus nilai spesifik lingkungan yang seharusnya tidak dipindahkan ke lingkungan lain. Gunakan file penggantian lingkungan yang telah ditinjau atau referensi Azure Key Vault jika sesuai.
  4. Cari kredensial dan nilai rahasia. Ekstraksi menyamarkan field rahasia yang didukung dan pola kebijakan yang dikenali, tetapi mungkin tidak mendeteksi setiap rahasia yang disematkan. Jangan menyimpan rahasia atau nilai-nilai yang belum terselesaikan *** REDACTED *** .
  5. Komitkan artefak ke cabang dan gunakan pull request untuk validasi dan persetujuan.

Pratinjau publikasi

Jalankan uji coba terhadap instance target nonproduksi. Dry run menampilkan pembuatan, pembaruan, dan penghapusan yang direncanakan tanpa benar-benar menerapkannya:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts \
  --dry-run

Tinjau output dan selesaikan perubahan tak terduga atau ketergantungan yang hilang. Dry run yang sukses tidak menggantikan pengujian perilaku API, kebijakan, izin, atau konektivitas backend.

Caution

Jangan menambah --delete-unmatched ke alur kerja pertama Anda. Opsi itu menghapus sumber daya di instance target yang tidak direpresentasikan dalam artefak sumber.

Publikasikan artefak yang telah ditinjau

Setelah pull request disetujui dan uji coba berhasil, publikasikan artefak yang sama yang sudah ditinjau ke target nonproduksi:

apiops publish \
  --subscription-id <target-subscription-id> \
  --resource-group <target-resource-group> \
  --service-name <target-apim-name> \
  --source ./apim-artifacts

Validasi API dan kebijakan dalam instance target setelah dipublikasikan. Saat Anda mengotomatisasi alur kerja ini, konfigurasikan pipeline untuk mempublikasikan commit yang disetujui dan lindungi lingkungan deployment dengan pemeriksaan dan persetujuan yang diperlukan oleh organisasi Anda.

Langkah berikutnya

  • Terakhir diperbarui pada