Tutorial: Menggunakan revisi untuk membuat perubahan API yang tidak pecah dengan aman

BERLAKU UNTUK: Semua tingkatAN API Management

Saat API Anda siap digunakan dan digunakan oleh pengembang, pada akhirnya Anda perlu membuat perubahan pada API tersebut dan pada saat yang sama tidak mengganggu pemanggil API Anda. Itu juga berguna untuk memberi tahu pengembang tentang perubahan yang Anda buat.

Di Azure API Management, gunakan revisi untuk membuat perubahan API yang tidak pecah sehingga Anda dapat memodelkan dan menguji perubahan dengan aman. Setelah siap, Anda dapat memberlakukan revisi dan mengganti API Anda saat ini.

Untuk latar belakang, lihat Versi dan Revisi.

Tip

Tim API dapat menggunakan fitur ini di ruang kerja. Ruang kerja menyediakan akses administratif terisolasi ke API dan lingkungan runtime API mereka sendiri.

Dalam tutorial ini, Anda akan mempelajari cara:

• Menambahkan revisi baru
• Membuat perubahan yang tidak terpecah pada revisi Anda
• Memberlakukan revisi Anda saat ini dan menambahkan entri log perubahan
• Menelusuri portal pengembang untuk melihat perubahan dan mengubah log
• Mengakses revisi API

Prasyarat

• Mempelajari terminologi Azure API Management.
• Menyelesaikan mulai cepat berikut: Membuat instans Azure API Management.
• Selain itu, selesaikan tutorial berikut: Mengimpor dan menerbitkan API pertama Anda.

Menambahkan revisi baru

1. Masuk ke portal Azure, dan buka instans API Management Anda.

2. Di menu sebelah kiri, di bawah API, pilih API.

3. Pilih Swagger Petstore dari daftar API (atau API lain yang ingin Anda tambahkan revisinya).

4. Pilih tab Revisi.

5. Pilih + Tambahkan revisi.

   

   Tip

   Anda juga dapat memilih Tambahkan revisi di menu pintasan (...) API.

6. Berikan deskripsi untuk revisi baru Anda, untuk membantu mengingat untuk apa revisi tersebut digunakan.

7. Pilih Buat.

8. Revisi baru Anda sekarang dibuat.

   Catatan

   API asli Anda tetap berada di Revisi 1. Ini adalah revisi yang terus dipanggil pengguna Anda, sampai Anda memilih untuk membuat revisi baru yang berbeda.

Membuat perubahan yang tidak terpecah pada revisi Anda

1. Pilih Swagger Petstore dari daftar API.

2. Pilih tab Desain di dekat bagian atas layar.

3. Perhatikan bahwa pemilih revisi (tepat di atas tab desain) menunjukkan Revisi 2 seperti yang saat ini dipilih.

   Tip

   Menggunakan pemilih revisi untuk beralih antar revisi yang ingin Anda kerjakan.

4. Pilih + Tambahkan Operasi.

5. Atur operasi baru Anda ke POST, dan Nama tampilan, Nama, dan URL operasi sebagai pengujian.

6. Simpan operasi baru Anda.

   

7. Anda sekarang telah membuat perubahan pada Revisi 2. Gunakan pemilih revisi di dekat bagian atas halaman untuk beralih kembali ke Revisi 1.

8. Perhatikan bahwa operasi baru Anda tidak muncul di Revisi 1.

Memberlakukan revisi Anda saat ini dan menambahkan entri log perubahan

Portal

1. Pilih tab Revisi dari menu di dekat bagian atas halaman.

2. Buka menu pintasan (...) untuk Revisi 2.

3. Pilih Berlakukan.

4. Pilih kotak centang Posting ke Perubahan Publik untuk API ini, jika Anda ingin memposting catatan tentang perubahan ini. Berikan deskripsi untuk perubahan Anda yang dapat dilihat oleh pengembang, misalnya: Menguji revisi. Menambahkan operasi "pengujian" baru.

5. Revisi 2 sekarang berlaku.

   

Azure CLI

Untuk mulai menggunakan Azure CLI:

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Gunakan prosedur ini untuk membuat dan memperbarui rilis.

1. Jalankan perintah az api list untuk melihat ID API Anda:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   ID API yang akan digunakan di perintah berikutnya adalah nilai Name. Revisi API ada di kolom ApiRevision.

2. Untuk membuat rilis, dengan catatan rilis, jalankan perintah buat rilis api az apim:

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   Revisi yang Anda rilis menjadi revisi saat ini.

3. Untuk melihat rilis Anda, gunakan perintah daftar rilis api apim az:

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --service-name apim-hello-world --output table
   

   Catatan yang Anda tentukan muncul di log perubahan. Anda dapat melihatnya di output perintah sebelumnya.

4. Saat Anda membuat sebuah rilis, parameter --notes bersifat opsional. Anda dapat menambahkan atau mengubah catatan nanti menggunakan perintah az apim api release update:

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Gunakan nilai dalam kolom Name untuk ID rilis.

Anda dapat menghapus rilis apa pun dengan menjalankan perintah hapus rilis api az apim:

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Menelusuri portal pengembang untuk melihat perubahan dan mengubah log

Jika Anda sudah mencoba portal pengembang, Anda dapat meninjau perubahan API dan mengubah log di sana.

1. Di portal Microsoft Azure, navigasikan ke instans API Management Anda.
2. Di menu sebelah kiri, di bawah API, pilih API.
3. Pilih Portal Pengembang dari menu atas.
4. Di portal pengembang, pilih API, lalu pilih Swagger Petstore.
5. Perhatikan operasi pengujian baru Anda sekarang tersedia.
6. Pilih Changelog di dekat nama API.
7. Perhatikan bahwa entri log perubahan Anda muncul dalam daftar.

Mengakses revisi API

Setiap revisi ke API Anda dapat diakses menggunakan URL yang dibentuk khusus. Tambahkan ;rev={revisionNumber} di akhir jalur URL API Anda, tetapi sebelum string kueri, untuk mengakses revisi tertentu dari API tersebut. Misalnya, Anda mungkin menggunakan URL yang mirip dengan yang berikut ini untuk mengakses revisi 2 api Swagger Petstore:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

Anda dapat menemukan jalur URL untuk revisi API Anda pada tab Revisi di portal Azure.

Tip

Anda dapat mengakses revisi API saat ini menggunakan jalur API tanpa ;rev string, selain URL lengkap yang ditambahkan ;rev={revisionNumber} ke jalur API Anda.

Ringkasan

Dalam tutorial ini, Anda mempelajari cara:

• Menambahkan revisi baru
• Membuat perubahan yang tidak terpecah pada revisi Anda
• Memberlakukan revisi Anda saat ini dan menambahkan entri log perubahan
• Menelusuri portal pengembang untuk melihat perubahan dan mengubah log
• Mengakses revisi API

Langkah berikutnya

Melanjutkan ke tutorial berikutnya:

Memublikasikan beberapa versi API Anda