Bagikan melalui


Mulai cepat: Menyebarkan aplikasi RESTful API ke Azure Spring Apps

Catatan

50 jam vCPU pertama dan memori 100 GB gratis setiap bulan. Untuk informasi selengkapnya, lihat Pengurangan Harga - Azure Spring Apps melakukan lebih banyak, biaya lebih murah! pada Aplikasi di Blog Azure.

Catatan

Azure Spring Apps adalah nama baru untuk layanan Azure Spring Cloud. Meskipun layanan memiliki nama baru, Anda akan melihat nama lama di beberapa tempat untuk sementara saat kami berupaya memperbarui aset seperti cuplikan layar, video, dan diagram.

Artikel ini menjelaskan cara menyebarkan aplikasi RESTful API yang dilindungi oleh MICROSOFT Entra ID ke Azure Spring Apps. Proyek sampel adalah versi yang disederhanakan berdasarkan aplikasi web Simple Todo , yang hanya menyediakan layanan backend dan menggunakan ID Microsoft Entra untuk melindungi API RESTful.

API RESTful ini dilindungi dengan menerapkan kontrol akses berbasis peran (RBAC). Pengguna anonim tidak dapat mengakses data apa pun dan tidak diizinkan untuk mengontrol akses untuk pengguna yang berbeda. Pengguna anonim hanya memiliki tiga izin berikut:

  • Baca: Dengan izin ini, pengguna dapat membaca data ToDo.
  • Tulis: Dengan izin ini, pengguna dapat menambahkan atau memperbarui data ToDo.
  • Hapus: Dengan izin ini, pengguna dapat menghapus data ToDo.

Setelah penyebaran berhasil, Anda dapat melihat dan menguji API melalui antarmuka pengguna Swagger.

Cuplikan layar antarmuka pengguna Swagger yang memperlihatkan dokumen API.

Diagram berikut menunjukkan arsitektur sistem:

Diagram yang memperlihatkan arsitektur aplikasi web Spring.

Artikel ini menjelaskan opsi berikut untuk membuat sumber daya dan menyebarkannya ke Azure Spring Apps:

  • Opsi plugin portal Azure + Maven menyediakan cara yang lebih konvensional untuk membuat sumber daya dan menyebarkan aplikasi langkah demi langkah. Opsi ini cocok untuk pengembang Spring yang menggunakan layanan cloud Azure untuk pertama kalinya.
  • Opsi Azure Developer CLI adalah cara yang lebih efisien untuk membuat sumber daya secara otomatis dan menyebarkan aplikasi melalui perintah sederhana. Azure Developer CLI menggunakan templat untuk menyediakan sumber daya Azure yang diperlukan dan untuk menyebarkan kode aplikasi. Opsi ini cocok untuk pengembang Spring yang terbiasa dengan layanan cloud Azure.

Artikel ini menjelaskan opsi berikut untuk membuat sumber daya dan menyebarkannya ke Azure Spring Apps:

  • Opsi plugin portal Azure + Maven menyediakan cara yang lebih konvensional untuk membuat sumber daya dan menyebarkan aplikasi langkah demi langkah. Opsi ini cocok untuk pengembang Spring yang menggunakan layanan cloud Azure untuk pertama kalinya.
  • Opsi Azure CLI menggunakan alat baris perintah yang kuat untuk mengelola sumber daya Azure. Opsi ini cocok untuk pengembang Spring yang terbiasa dengan layanan cloud Azure.

1. Prasyarat

  • Langganan Azure. Jika Anda tidak memiliki langganan Azure, buat akun gratis Azure sebelum memulai.

  • Salah satu peran berikut:

    • Administrator Global atau Administrator Peran Istimewa, untuk memberikan perizinan bagi aplikasi yang meminta izin apa pun, untuk API apa pun.
    • Administrator Aplikasi Cloud atau Administrator Aplikasi, untuk memberikan persetujuan untuk aplikasi yang meminta izin apa pun untuk API apa pun, kecuali peran aplikasi Microsoft Graph (izin aplikasi).
    • Peran direktori kustom yang menyertakan izin untuk memberikan izin ke aplikasi, untuk izin yang diperlukan oleh aplikasi.

    Untuk informasi selengkapnya, lihat Memberikan persetujuan admin di seluruh penyewa untuk aplikasi.

  • Jika Anda menyebarkan instans paket Azure Spring Apps Enterprise untuk pertama kalinya dalam langganan target, lihat bagian Persyaratan paket Enterprise di Marketplace Azure.

  • Git.

  • Java Development Kit (JDK), versi 17.

  • Penyewa Microsoft Entra. Untuk instruksi tentang membuatnya, lihat Mulai Cepat: Membuat penyewa baru di ID Microsoft Entra.

  • Langganan Azure, Jika Anda tidak memiliki langganan Azure, buat akun gratis Azure sebelum Memulai.

  • Salah satu peran berikut:

    • Administrator Global atau Administrator Peran Istimewa, untuk memberikan perizinan bagi aplikasi yang meminta izin apa pun, untuk API apa pun.
    • Administrator Aplikasi Cloud atau Administrator Aplikasi, untuk memberikan persetujuan untuk aplikasi yang meminta izin apa pun untuk API apa pun, kecuali peran aplikasi Microsoft Graph (izin aplikasi).
    • Peran direktori kustom yang menyertakan izin untuk memberikan izin ke aplikasi, untuk izin yang diperlukan oleh aplikasi.

    Untuk informasi selengkapnya, lihat Memberikan persetujuan admin di seluruh penyewa untuk aplikasi.

  • Git.

  • Java Development Kit (JDK), versi 17.

  • Penyewa Microsoft Entra. Untuk instruksi tentang membuatnya, lihat Mulai Cepat: Membuat penyewa baru di ID Microsoft Entra.

2. Siapkan proyek Spring

Untuk menyebarkan aplikasi RESTful API, langkah pertama adalah menyiapkan proyek Spring agar berjalan secara lokal.

Gunakan langkah-langkah berikut untuk mengkloning dan menjalankan aplikasi secara lokal:

  1. Gunakan perintah berikut untuk mengkloning proyek sampel dari GitHub:

    git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
    
  2. Jika Anda ingin menjalankan aplikasi secara lokal, selesaikan langkah-langkah dalam Ekspos API RESTful dan Perbarui bagian konfigurasi aplikasi terlebih dahulu, lalu gunakan perintah berikut untuk menjalankan aplikasi sampel dengan Maven:

    cd ASA-Samples-Restful-Application
    ./mvnw spring-boot:run
    

3. Siapkan lingkungan cloud

Sumber daya utama yang diperlukan untuk menjalankan aplikasi sampel ini adalah instans Azure Spring Apps dan instans Azure Database for PostgreSQL. Bagian berikut menjelaskan cara membuat sumber daya ini.

3.1. Masuk ke portal Microsoft Azure.

Buka portal Azure dan masukkan kredensial Anda untuk masuk ke portal. Tampilan default adalah dasbor layanan Anda.

3.2. Membuat instans Azure Spring Apps

Gunakan langkah-langkah berikut untuk membuat instans layanan Azure Spring Apps:

  1. Pilih Buat sumber daya di sudut portal Azure.

  2. Pilih Komputasi >Azure Spring Apps.

  3. Isi formulir Dasar dengan informasi berikut:

    Pengaturan Nilai yang disarankan Deskripsi
    Langganan Nama berlangganan Anda. Langganan Azure yang ingin Anda gunakan untuk server Anda. Jika Anda memiliki beberapa langganan, pilih langganan tempat Anda ingin ditagih untuk sumber daya tersebut.
    Grup sumber daya myresourcegroup Nama grup sumber daya baru atau nama yang sudah ada dari langganan Anda.
    Nama myasa Nama unik yang mengidentifikasi layanan Azure Spring Apps Anda. Nama harus antara 4 hingga 32 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung. Karakter pertama dari nama layanan harus berupa huruf dan karakter terakhir harus berupa huruf atau angka.
    Rencana Perusahaan Paket harga yang menentukan sumber daya dan biaya yang terkait dengan instans Anda.
    Wilayah Wilayah yang paling dekat dengan pengguna Anda. Lokasi yang paling dekat dengan pengguna Anda.
    Zona Redundan Tidak dipilih Opsi untuk membuat layanan Azure Spring Apps Anda di zona ketersediaan Azure. Fitur ini saat ini tidak didukung di semua wilayah.
    Paket IP perangkat lunak Bayar sesuai penggunaan Paket harga yang memungkinkan Anda membayar sesuai pemakaian dengan Azure Spring Apps.
    Istilah Dipilih Kotak centang perjanjian yang terkait dengan penawaran Marketplace. Anda diharuskan untuk memilih kotak centang ini.
    Menyebarkan proyek sampel Tidak dipilih Opsi untuk menggunakan aplikasi sampel bawaan.
  4. Pilih Tinjau dan Buat untuk meninjau pilihan Anda. Lalu, pilih Buat untuk memprovisikan instans Azure Spring Apps.

  5. Pada toolbar, pilih ikon Pemberitahuan (bel) untuk memantau proses penyebaran. Setelah penyebaran selesai, Anda dapat memilih Sematkan ke dasbor, yang membuat petak peta untuk layanan ini di dasbor portal Azure Anda sebagai pintasan ke halaman Gambaran Umum layanan.

    Cuplikan layar portal Azure yang memperlihatkan panel Pemberitahuan untuk pembuatan Azure Spring Apps.

  6. Pilih Buka sumber daya untuk masuk ke halaman Gambaran Umum Azure Spring Apps.

3.3. Menyiapkan instans PostgreSQL

Gunakan langkah-langkah berikut untuk membuat server Azure Database for PostgreSQL:

  1. Buka portal Azure dan pilih Buat sumber daya.

  2. Pilih Database>Azure Database for PostgreSQL.

  3. Pilih opsi penyebaran Server yang fleksibel.

    Cuplikan layar portal Azure yang memperlihatkan halaman Opsi penyebaran Pilih Azure Database for PostgreSQL.

  4. Isi tab Dasar dengan informasi berikut:

    • Nama server: my-demo-pgsql
    • Wilayah: US Timur
    • Versi PostgreSQL: 14
    • Jenis beban kerja: Pengembangan
    • Aktifkan ketersediaan tinggi: tidak dipilih
    • Metode autentikasi: Autentikasi PostgreSQL saja
    • Nama pengguna admin: myadmin
    • Kata sandi dan Konfirmasi kata sandi: Masukkan kata sandi.
  5. Gunakan informasi berikut untuk mengonfigurasi tab Jaringan :

    • metode Koneksi ivity: Akses publik (alamat IP yang diizinkan)
    • Izinkan akses publik dari layanan Azure apa pun dalam Azure ke server ini: dipilih
  6. Pilih Tinjau + buat untuk meninjau pilihan Anda, dan pilih Buat untuk memprovisikan server. Operasi ini mungkin akan memakan waktu beberapa menit.

  7. Buka server PostgreSQL Anda di portal Azure. Pada halaman Gambaran Umum, cari nilai Nama server, lalu rekam untuk digunakan nanti. Anda memerlukannya untuk mengonfigurasi variabel lingkungan untuk aplikasi di Azure Spring Apps.

  8. Pilih Database dari menu navigasi untuk membuat database - misalnya, todo.

    Cuplikan layar portal Azure yang memperlihatkan halaman Database dengan panel Buat Database terbuka.

3.4. Koneksi instans aplikasi ke instans PostgreSQL

Gunakan langkah-langkah berikut untuk menyambungkan instans layanan Anda:

  1. Buka instans Azure Spring Apps Anda di portal Microsoft Azure.

  2. Dari menu navigasi, buka Aplikasi, lalu pilih Buat Aplikasi.

  3. Pada halaman Buat Aplikasi , isi nama aplikasi simple-todo-api, lalu pilih artefak Java sebagai jenis penyebaran.

  4. Pilih Buat untuk menyelesaikan pembuatan aplikasi lalu pilih aplikasi untuk melihat detailnya.

  5. Buka aplikasi yang Anda buat di portal Azure. Pada halaman Gambaran Umum , pilih Tetapkan titik akhir untuk mengekspos titik akhir publik untuk aplikasi. Simpan URL untuk mengakses aplikasi setelah penyebaran.

  6. Pilih Service Koneksi or dari panel navigasi, lalu pilih Buat untuk membuat koneksi layanan baru.

    Cuplikan layar portal Azure yang memperlihatkan halaman Koneksi or Layanan paket perusahaan dengan tombol Buat disorot.

  7. Isi tab Dasar dengan informasi berikut:

    • Jenis layanan: Server fleksibel DB for PostgreSQL
    • nama Koneksi: Nama yang dihasilkan secara otomatis diisi, yang juga dapat dimodifikasi.
    • Langganan: Pilih langganan Anda.
    • Server fleksibel PostgreSQL: my-demo-pgsql
    • Database PostgreSQL: Pilih database yang Anda buat.
    • Jenis klien: SpringBoot

    Cuplikan layar portal Azure yang memperlihatkan tab Dasar dari panel Buat koneksi untuk menyambungkan ke Bus Layanan.

  8. Konfigurasikan tab Berikutnya: Autentikasi dengan informasi berikut:

    • Pilih jenis autentikasi yang ingin Anda gunakan antara layanan komputasi dan layanan target Anda.: Pilih string Koneksi ion.
    • Lanjutkan dengan...: Pilih Kredensial database
    • Nama pengguna: myadmin
    • Kata sandi: Masukkan kata sandi Anda.

    Cuplikan layar portal Azure yang memperlihatkan tab Autentikasi dari panel Buat koneksi dengan opsi string Koneksi ion disorot.

  9. Pilih Next: Networking. Gunakan opsi default Konfigurasikan aturan firewall untuk mengaktifkan akses ke layanan target.

  10. Pilih Berikutnya: Tinjau dan Buat untuk meninjau pilihan Anda, lalu pilih Buat untuk membuat koneksi.

3.5. Mengekspos API RESTful

Gunakan langkah-langkah berikut untuk mengekspos API RESTful Anda di ID Microsoft Entra:

  1. Masuk ke portal Azure.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan ( ) untuk memilih penyewa tempat Anda ingin mendaftarkan aplikasi.

  3. Mencari dan memilih Microsoft Entra ID.

  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.

  5. Masukkan nama untuk aplikasi Anda di bidang Nama - misalnya, Todo. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Untuk Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multipenyewa) dan akun Microsoft pribadi.

  7. Pilih Daftar untuk membuat aplikasi.

  8. Pada halaman Gambaran Umum aplikasi, cari nilai ID Aplikasi (klien), lalu catat untuk digunakan nanti. Anda memerlukannya untuk mengonfigurasi file konfigurasi YAML untuk proyek ini.

  9. Di bawah Kelola, pilih Ekspos API, temukan URI ID Aplikasi di awal halaman, lalu pilih Tambahkan.

  10. Pada halaman Edit URI ID aplikasi, terima URI ID Aplikasi yang diusulkan (api://{client ID}) atau gunakan nama yang bermakna alih-alih ID klien, seperti api://simple-todo, lalu pilih Simpan.

  11. Di bawah Kelola, pilih Ekspos API>Tambahkan cakupan, lalu masukkan informasi berikut:

    • Untuk Nama cakupan, masukkan ToDo.Read.
    • Untuk Siapa dapat menyetujui, pilih Admin saja.
    • Untuk Nama tampilan persetujuan admin, masukkan Baca data ToDo.
    • Untuk Deskripsi persetujuan admin, masukkan Izinkan pengguna terautentikasi membaca data ToDo..
    • Untuk Status, tetap aktifkan.
    • Pilih Tambahkan cakupan.
  12. Ulangi langkah-langkah sebelumnya untuk menambahkan dua cakupan lainnya: ToDo.Write dan ToDo.Delete.

    Cuplikan layar portal Azure yang memperlihatkan halaman Mengekspos API dari aplikasi RESTful API.

3.6. Memperbarui konfigurasi aplikasi

Gunakan langkah-langkah berikut untuk memperbarui file YAML untuk menggunakan informasi aplikasi terdaftar Microsoft Entra Anda untuk menjalin hubungan dengan aplikasi RESTful API:

  1. Temukan file src/main/resources/application.yml untuk simple-todo-api aplikasi. Perbarui konfigurasi di bagian spring.cloud.azure.active-directory agar sesuai dengan contoh berikut. Pastikan untuk mengganti tempat penampung dengan nilai yang Anda buat sebelumnya.

    spring:
      cloud:
        azure:
          active-directory:
            profile:
              tenant-id: <tenant>
            credential:
              client-id: <your-application-ID-of-ToDo>
            app-id-uri: <your-application-ID-URI-of-ToDo>
    

    Catatan

    Dalam token v1.0, konfigurasi memerlukan ID klien API, sementara dalam token v2.0, Anda dapat menggunakan ID klien atau URI ID aplikasi dalam permintaan. Anda dapat mengonfigurasi keduanya untuk menyelesaikan validasi audiens dengan benar.

    Nilai yang diizinkan untuk tenant-id adalah: common, organizations, consumers, atau ID penyewa. Untuk informasi selengkapnya tentang nilai-nilai ini, lihat bagian Menggunakan titik akhir (akun pribadi dan organisasi) yang salah dari Kesalahan AADSTS50020 - Akun pengguna dari penyedia identitas tidak ada di penyewa. Untuk informasi tentang mengonversi aplikasi penyewa tunggal Anda, lihat Mengonversi aplikasi penyewa tunggal ke multipenyewa di ID Microsoft Entra.

  2. Gunakan perintah berikut untuk membangun kembali proyek sampel:

    ./mvnw clean package
    

4. Menyebarkan aplikasi ke Azure Spring Apps

Anda sekarang dapat menyebarkan aplikasi ke Azure Spring Apps.

Gunakan langkah-langkah berikut untuk menyebarkan menggunakan plugin Maven untuk Azure Spring Apps:

  1. Navigasi ke direktori lengkap , lalu jalankan perintah berikut untuk mengonfigurasi aplikasi di Azure Spring Apps:

    ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
    

    Daftar berikut ini menjelaskan interaksi perintah:

    • Masuk OAuth2: Anda perlu mengotorisasi masuk ke Azure berdasarkan protokol OAuth2.
    • Pilih langganan: Pilih nomor daftar langganan instans Azure Spring Apps yang Anda buat, yang default ke langganan pertama dalam daftar. Jika Anda menggunakan nomor default, tekan Enter secara langsung.
    • Gunakan Azure Spring Apps yang sudah ada di Azure: Tekan y untuk menggunakan instans Azure Spring Apps yang ada.
    • Pilih Azure Spring Apps untuk penyebaran: Pilih jumlah instans Azure Spring Apps yang Anda buat. Jika Anda menggunakan nomor default, tekan Enter secara langsung.
    • Gunakan aplikasi yang sudah ada di Azure Spring Apps <nama> instans Anda: Tekan y untuk menggunakan aplikasi yang dibuat.
    • Konfirmasi untuk menyimpan semua konfigurasi di atas: Tekan y. Jika Anda menekan n, konfigurasi tidak disimpan dalam file POM.
  2. Gunakan perintah berikut untuk menyebarkan aplikasi:

    ./mvnw azure-spring-apps:deploy
    

    Daftar berikut ini menjelaskan interaksi perintah:

    • Masuk OAuth2: Anda perlu mengotorisasi masuk ke Azure berdasarkan protokol OAuth2.

    Setelah perintah dijalankan, Anda dapat melihat dari pesan log berikut bahwa penyebaran berhasil:

[INFO] Deployment Status: Running
[INFO]   InstanceName:simple-todo-api-default-15-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:N/A       
[INFO] Getting public url of app(simple-todo-api)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-simple-todo-api.azuremicroservices.io

5. Memvalidasi aplikasi

Anda sekarang dapat mengakses RESTful API untuk melihat apakah api berfungsi.

5.1. Minta Token Akses

RESTful API bertindak sebagai server sumber daya, yang dilindungi oleh ID Microsoft Entra. Sebelum memperoleh token akses, Anda harus mendaftarkan aplikasi lain di ID Microsoft Entra dan memberikan izin ke aplikasi klien, yang bernama ToDoWeb.

Mendaftarkan aplikasi klien

Gunakan langkah-langkah berikut untuk mendaftarkan aplikasi di ID Microsoft Entra, yang digunakan untuk menambahkan izin untuk ToDo aplikasi:

  1. Masuk ke portal Azure.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan ( ) untuk memilih penyewa tempat Anda ingin mendaftarkan aplikasi.

  3. Mencari dan memilih Microsoft Entra ID.

  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.

  5. Masukkan nama untuk aplikasi Anda di bidang Nama - misalnya, ToDoWeb. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Untuk Jenis akun yang didukung, gunakan nilai default Akun dalam direktori organisasi ini saja.

  7. Pilih Daftar untuk membuat aplikasi.

  8. Pada halaman Gambaran Umum aplikasi, cari nilai ID Aplikasi (klien), lalu catat untuk digunakan nanti. Anda memerlukannya untuk memperoleh token akses.

  9. Pilih izin API>Tambahkan izin>API Saya. ToDo Pilih aplikasi yang Anda daftarkan sebelumnya, lalu pilih izin ToDo.Read, ToDo.Write, dan ToDo.Delete. Pilih Tambahkan izin.

  10. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda untuk memberikan persetujuan admin untuk izin yang Anda tambahkan.

    Cuplikan layar portal Azure yang menunjukkan izin API aplikasi web.

Menambahkan pengguna untuk mengakses API RESTful

Gunakan langkah-langkah berikut untuk membuat pengguna anggota di penyewa Microsoft Entra Anda. Kemudian, pengguna dapat mengelola data ToDo aplikasi melalui API RESTful.

  1. Di bawah Kelola, pilih Pengguna>Pengguna>baru Buat pengguna baru.

  2. Pada halaman Buat pengguna baru, masukkan informasi berikut ini:

    • Nama prinsipal pengguna: Masukkan nama untuk pengguna.
    • Nama tampilan: Masukkan nama tampilan untuk pengguna.
    • Kata sandi: Salin kata sandi yang dibuat otomatis yang disediakan dalam kotak Kata Sandi .

    Catatan

    Pengguna baru harus menyelesaikan autentikasi masuk pertama dan memperbarui kata sandi mereka, jika tidak, Anda menerima kesalahan AADSTS50055: The password is expired saat Mendapatkan token akses.

    Saat pengguna baru masuk, mereka menerima perintah Tindakan yang Diperlukan . Mereka dapat memilih Minta nanti untuk melewati validasi.

  3. Pilih Tinjau + buat untuk meninjau pilihan Anda. Pilih Buat untuk membuat pengguna.

Memperbarui konfigurasi OAuth2 untuk otorisasi UI Swagger

Gunakan langkah-langkah berikut untuk memperbarui konfigurasi OAuth2 untuk otorisasi UI Swagger. Kemudian, Anda dapat mengotorisasi pengguna untuk memperoleh token akses melalui ToDoWeb aplikasi.

  1. Buka penyewa ID Microsoft Entra Anda di portal Azure, dan buka aplikasi terdaftarToDoWeb.

  2. Di bawah Kelola, pilih Autentikasi, pilih Tambahkan platform, lalu pilih Aplikasi halaman tunggal.

  3. Gunakan format <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html sebagai URL pengalihan OAuth2 di bidang URI Pengalihan, lalu pilih Konfigurasikan.

    Cuplikan layar portal Azure yang memperlihatkan halaman Autentikasi untuk ID Microsoft Entra.

2. Siapkan proyek Spring

Untuk menyebarkan aplikasi RESTful API, langkah pertama adalah menyiapkan proyek Spring agar berjalan secara lokal.

Gunakan langkah-langkah berikut untuk mengkloning dan menjalankan aplikasi secara lokal:

  1. Gunakan perintah berikut untuk mengkloning proyek sampel dari GitHub:

    git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
    
  2. Jika Anda ingin menjalankan aplikasi secara lokal, selesaikan langkah-langkah dalam Ekspos API RESTful dan Perbarui bagian konfigurasi aplikasi terlebih dahulu, lalu gunakan perintah berikut untuk menjalankan aplikasi sampel dengan Maven:

    cd ASA-Samples-Restful-Application
    ./mvnw spring-boot:run
    

3. Siapkan lingkungan cloud

Sumber daya utama yang diperlukan untuk menjalankan aplikasi sampel ini adalah instans Azure Spring Apps dan instans Azure Database for PostgreSQL. Bagian berikut menjelaskan cara membuat sumber daya ini.

3.1. Masuk ke portal Microsoft Azure.

Buka portal Azure dan masukkan kredensial Anda untuk masuk ke portal. Tampilan default adalah dasbor layanan Anda.

3.2. Membuat instans Azure Spring Apps

Gunakan langkah-langkah berikut untuk membuat instans layanan:

  1. Pilih Buat sumber daya di sudut portal.

  2. Pilih Komputasi >Azure Spring Apps.

  3. Isi formulir Dasar-dasar. Gunakan tabel berikut sebagai panduan untuk melengkapi formulir. Nilai Paket yang direkomendasikan adalah Konsumsi standar & khusus (pratinjau).

    Pengaturan Nilai yang disarankan Deskripsi
    Langganan Nama berlangganan Anda. Langganan Azure yang ingin Anda gunakan untuk server Anda. Jika Anda memiliki beberapa langganan, pilih langganan tempat Anda ingin ditagih untuk sumber daya tersebut.
    Grup sumber daya myresourcegroup Nama grup sumber daya baru atau nama yang sudah ada dari langganan Anda.
    Nama myasa Nama unik yang mengidentifikasi layanan Azure Spring Apps Anda. Nama harus antara 4 hingga 32 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung. Karakter pertama dari nama layanan harus berupa huruf dan karakter terakhir harus berupa huruf atau angka.
    Rencana Konsumsi standar & khusus (pratinjau) Paket harga menentukan sumber daya dan biaya yang terkait dengan instans Anda.
    Wilayah Wilayah yang paling dekat dengan pengguna Anda. Lokasi yang paling dekat dengan pengguna Anda.
    Lingkungan Aplikasi Kontainer myenvironment Opsi untuk memilih instans lingkungan Container Apps mana yang akan berbagi jaringan virtual yang sama dengan layanan dan sumber daya lain.

    Gunakan tabel berikut sebagai panduan untuk pembuatan Lingkungan Container Apps:

    Pengaturan Nilai yang disarankan Deskripsi
    Nama lingkungan myenvironment Nama unik yang mengidentifikasi layanan Azure Container Apps Environment Anda.
    Rencana Consumption Paket harga menentukan sumber daya dan biaya yang terkait dengan instans Anda.
    Zona Redundan Nonaktif Opsi untuk membuat layanan Lingkungan Aplikasi Kontainer Anda di zona ketersediaan Azure.
  4. Pilih Tinjau dan Buat untuk meninjau pilihan Anda. Lalu, pilih Buat untuk memprovisikan instans Azure Spring Apps.

  5. Pada toolbar, pilih ikon Pemberitahuan (bel) untuk memantau proses penyebaran. Setelah penyebaran selesai, Anda dapat memilih Sematkan ke dasbor, yang membuat petak peta untuk layanan ini di dasbor portal Azure Anda sebagai pintasan ke halaman Gambaran Umum layanan.

  6. Pilih Buka sumber daya untuk membuka halaman Gambaran Umum layanan.

    Cuplikan layar portal Azure yang memperlihatkan halaman Gambaran Umum dengan halaman Pemberitahuan terbuka.

Penting

Profil beban kerja Konsumsi memiliki model penagihan bayar sesuai pemakaian, tanpa biaya awal. Anda ditagih untuk profil beban kerja khusus berdasarkan sumber daya yang disediakan. Untuk informasi selengkapnya, lihat Profil beban kerja di Azure Container Apps dan harga Azure Spring Apps.

3.3. Menyiapkan instans PostgreSQL

Gunakan langkah-langkah berikut untuk membuat server Azure Database for PostgreSQL:

  1. Buka portal Azure dan pilih Buat sumber daya.

  2. Pilih Database>Azure Database for PostgreSQL.

  3. Pilih opsi penyebaran Server yang fleksibel.

    Cuplikan layar portal Azure yang memperlihatkan halaman Opsi penyebaran Pilih Azure Database for PostgreSQL.

  4. Isi tab Dasar dengan informasi berikut:

    • Nama server: my-demo-pgsql
    • Wilayah: US Timur
    • Versi PostgreSQL: 14
    • Jenis beban kerja: Pengembangan
    • Aktifkan ketersediaan tinggi: tidak dipilih
    • Metode autentikasi: Autentikasi PostgreSQL saja
    • Nama pengguna admin: myadmin
    • Kata sandi dan Konfirmasi kata sandi: Masukkan kata sandi.
  5. Gunakan informasi berikut untuk mengonfigurasi tab Jaringan :

    • metode Koneksi ivity: Akses publik (alamat IP yang diizinkan)
    • Izinkan akses publik dari layanan Azure apa pun dalam Azure ke server ini: dipilih
  6. Pilih Tinjau + buat untuk meninjau pilihan Anda, dan pilih Buat untuk memprovisikan server. Operasi ini mungkin akan memakan waktu beberapa menit.

  7. Buka server PostgreSQL Anda di portal Azure. Pada halaman Gambaran Umum, cari nilai Nama server, lalu rekam untuk digunakan nanti. Anda memerlukannya untuk mengonfigurasi variabel lingkungan untuk aplikasi di Azure Spring Apps.

  8. Pilih Database dari menu navigasi untuk membuat database - misalnya, todo.

    Cuplikan layar portal Azure yang memperlihatkan halaman Database dengan panel Buat Database terbuka.

3.4. Koneksi instans aplikasi ke instans PostgreSQL

Gunakan langkah-langkah berikut untuk menyambungkan instans layanan Anda:

  1. Buka instans Azure Spring Apps Anda di portal Microsoft Azure.

  2. Dari menu navigasi, buka Aplikasi, lalu pilih Buat Aplikasi.

  3. Pada halaman Buat Aplikasi , isi nama aplikasi simple-todo-api dan pilih artefak Java sebagai jenis penyebaran.

  4. Pilih Buat untuk menyelesaikan pembuatan aplikasi dan pilih aplikasi untuk melihat detailnya.

  5. Buka aplikasi yang Anda buat di portal Azure. Pada halaman Gambaran Umum , pilih Tetapkan titik akhir untuk mengekspos titik akhir publik untuk aplikasi. Simpan URL untuk mengakses aplikasi setelah penyebaran.

  6. Buka aplikasi yang Anda buat, perluas Pengaturan dan pilih Konfigurasi dari menu navigasi, lalu pilih Variabel lingkungan untuk mengatur variabel lingkungan.

  7. Tambahkan variabel lingkungan berikut untuk koneksi PostgreSQL, lalu pilih Simpan untuk menyelesaikan pembaruan konfigurasi aplikasi. Pastikan untuk mengganti tempat penampung dengan nilai Anda sendiri yang Anda buat sebelumnya.

    Variabel lingkungan Nilai
    SPRING_DATASOURCE_URL jdbc:postgresql://<your-PostgreSQL-server-name>:5432/<your-PostgreSQL-database-name>
    SPRING_DATASOURCE_USERNAME <your-PostgreSQL-admin-user>
    SPRING_DATASOURCE_PASSWORD <your-PostgreSQL-admin-password>

    Cuplikan layar portal Azure yang memperlihatkan tab Variabel lingkungan dengan semua nilai untuk koneksi PostgreSQL.

3.5. Mengekspos API RESTful

Gunakan langkah-langkah berikut untuk mengekspos API RESTful Anda di ID Microsoft Entra:

  1. Masuk ke portal Azure.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan ( ) untuk memilih penyewa tempat Anda ingin mendaftarkan aplikasi.

  3. Mencari dan memilih Microsoft Entra ID.

  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.

  5. Masukkan nama untuk aplikasi Anda di bidang Nama - misalnya, Todo. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Untuk Jenis akun yang didukung, pilih Akun di direktori organisasi apa pun (Direktori Microsoft Entra apa pun - Multipenyewa) dan akun Microsoft pribadi.

  7. Pilih Daftar untuk membuat aplikasi.

  8. Pada halaman Gambaran Umum aplikasi, cari nilai ID Aplikasi (klien), lalu catat untuk digunakan nanti. Anda memerlukannya untuk mengonfigurasi file konfigurasi YAML untuk proyek ini.

  9. Di bawah Kelola, pilih Ekspos API, temukan URI ID Aplikasi di awal halaman, lalu pilih Tambahkan.

  10. Pada halaman Edit URI ID aplikasi, terima URI ID Aplikasi yang diusulkan (api://{client ID}) atau gunakan nama yang bermakna alih-alih ID klien, seperti api://simple-todo, lalu pilih Simpan.

  11. Di bawah Kelola, pilih Ekspos API>Tambahkan cakupan, lalu masukkan informasi berikut:

    • Untuk Nama cakupan, masukkan ToDo.Read.
    • Untuk Siapa dapat menyetujui, pilih Admin saja.
    • Untuk Nama tampilan persetujuan admin, masukkan Baca data ToDo.
    • Untuk Deskripsi persetujuan admin, masukkan Izinkan pengguna terautentikasi membaca data ToDo..
    • Untuk Status, tetap aktifkan.
    • Pilih Tambahkan cakupan.
  12. Ulangi langkah-langkah sebelumnya untuk menambahkan dua cakupan lainnya: ToDo.Write dan ToDo.Delete.

    Cuplikan layar portal Azure yang memperlihatkan halaman Mengekspos API dari aplikasi RESTful API.

3.6. Memperbarui konfigurasi aplikasi

Gunakan langkah-langkah berikut untuk memperbarui file YAML untuk menggunakan informasi aplikasi terdaftar Microsoft Entra Anda untuk menjalin hubungan dengan aplikasi RESTful API:

  1. Temukan file src/main/resources/application.yml untuk simple-todo-api aplikasi. Perbarui konfigurasi di bagian spring.cloud.azure.active-directory agar sesuai dengan contoh berikut. Pastikan untuk mengganti tempat penampung dengan nilai yang Anda buat sebelumnya.

    spring:
      cloud:
        azure:
          active-directory:
            profile:
              tenant-id: <tenant>
            credential:
              client-id: <your-application-ID-of-ToDo>
            app-id-uri: <your-application-ID-URI-of-ToDo>
    

    Catatan

    Dalam token v1.0, konfigurasi memerlukan ID klien API, sementara dalam token v2.0, Anda dapat menggunakan ID klien atau URI ID aplikasi dalam permintaan. Anda dapat mengonfigurasi keduanya untuk menyelesaikan validasi audiens dengan benar.

    Nilai yang diizinkan untuk tenant-id adalah: common, organizations, consumers, atau ID penyewa. Untuk informasi selengkapnya tentang nilai-nilai ini, lihat bagian Menggunakan titik akhir (akun pribadi dan organisasi) yang salah dari Kesalahan AADSTS50020 - Akun pengguna dari penyedia identitas tidak ada di penyewa. Untuk informasi tentang mengonversi aplikasi penyewa tunggal Anda, lihat Mengonversi aplikasi penyewa tunggal ke multipenyewa di ID Microsoft Entra.

  2. Gunakan perintah berikut untuk membangun kembali proyek sampel:

    ./mvnw clean package
    

4. Menyebarkan aplikasi ke Azure Spring Apps

Anda sekarang dapat menyebarkan aplikasi ke Azure Spring Apps.

Gunakan langkah-langkah berikut untuk menyebarkan menggunakan plugin Maven untuk Azure Spring Apps:

  1. Navigasi ke direktori lengkap , lalu jalankan perintah berikut untuk mengonfigurasi aplikasi di Azure Spring Apps:

    ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
    

    Daftar berikut ini menjelaskan interaksi perintah:

    • Masuk OAuth2: Anda perlu mengotorisasi masuk ke Azure berdasarkan protokol OAuth2.
    • Pilih langganan: Pilih nomor daftar langganan instans Azure Spring Apps yang Anda buat, yang default ke langganan pertama dalam daftar. Jika Anda menggunakan nomor default, tekan Enter secara langsung.
    • Gunakan Azure Spring Apps yang sudah ada di Azure: Tekan y untuk menggunakan instans Azure Spring Apps yang ada.
    • Pilih Azure Spring Apps untuk penyebaran: Pilih jumlah instans Azure Spring Apps yang Anda buat. Jika Anda menggunakan nomor default, tekan Enter secara langsung.
    • Gunakan aplikasi yang sudah ada di Azure Spring Apps <nama> instans Anda: Tekan y untuk menggunakan aplikasi yang dibuat.
    • Konfirmasi untuk menyimpan semua konfigurasi di atas: Tekan y. Jika Anda menekan n, konfigurasi tidak disimpan dalam file POM.
  2. Gunakan perintah berikut untuk menyebarkan aplikasi:

    ./mvnw azure-spring-apps:deploy
    

    Daftar berikut ini menjelaskan interaksi perintah:

    • Masuk OAuth2: Anda perlu mengotorisasi masuk ke Azure berdasarkan protokol OAuth2.

    Setelah perintah dijalankan, Anda dapat melihat dari pesan log berikut bahwa penyebaran berhasil:

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo--default-xxxxxxx-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:NONE
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://demo.<unique-identifier>.<region-name>.azurecontainerapps.io

5. Memvalidasi aplikasi

Anda sekarang dapat mengakses RESTful API untuk melihat apakah api berfungsi.

5.1. Minta Token Akses

RESTful API bertindak sebagai server sumber daya, yang dilindungi oleh ID Microsoft Entra. Sebelum memperoleh token akses, Anda harus mendaftarkan aplikasi lain di ID Microsoft Entra dan memberikan izin ke aplikasi klien, yang bernama ToDoWeb.

Mendaftarkan aplikasi klien

Gunakan langkah-langkah berikut untuk mendaftarkan aplikasi di ID Microsoft Entra, yang digunakan untuk menambahkan izin untuk ToDo aplikasi:

  1. Masuk ke portal Azure.

  2. Jika Anda memiliki akses ke beberapa penyewa, gunakan filter Direktori + langganan ( ) untuk memilih penyewa tempat Anda ingin mendaftarkan aplikasi.

  3. Mencari dan memilih Microsoft Entra ID.

  4. Di bagian Kelola, pilih Pendaftaran aplikasi>Pendaftaran baru.

  5. Masukkan nama untuk aplikasi Anda di bidang Nama - misalnya, ToDoWeb. Pengguna aplikasi mungkin melihat nama ini, dan Anda dapat mengubahnya nanti.

  6. Untuk Jenis akun yang didukung, gunakan nilai default Akun dalam direktori organisasi ini saja.

  7. Pilih Daftar untuk membuat aplikasi.

  8. Pada halaman Gambaran Umum aplikasi, cari nilai ID Aplikasi (klien), lalu catat untuk digunakan nanti. Anda memerlukannya untuk memperoleh token akses.

  9. Pilih izin API>Tambahkan izin>API Saya. ToDo Pilih aplikasi yang Anda daftarkan sebelumnya, lalu pilih izin ToDo.Read, ToDo.Write, dan ToDo.Delete. Pilih Tambahkan izin.

  10. Pilih Berikan persetujuan admin untuk <nama> penyewa Anda untuk memberikan persetujuan admin untuk izin yang Anda tambahkan.

    Cuplikan layar portal Azure yang menunjukkan izin API aplikasi web.

Menambahkan pengguna untuk mengakses API RESTful

Gunakan langkah-langkah berikut untuk membuat pengguna anggota di penyewa Microsoft Entra Anda. Kemudian, pengguna dapat mengelola data ToDo aplikasi melalui API RESTful.

  1. Di bawah Kelola, pilih Pengguna>Pengguna>baru Buat pengguna baru.

  2. Pada halaman Buat pengguna baru, masukkan informasi berikut ini:

    • Nama prinsipal pengguna: Masukkan nama untuk pengguna.
    • Nama tampilan: Masukkan nama tampilan untuk pengguna.
    • Kata sandi: Salin kata sandi yang dibuat otomatis yang disediakan dalam kotak Kata Sandi .

    Catatan

    Pengguna baru harus menyelesaikan autentikasi masuk pertama dan memperbarui kata sandi mereka, jika tidak, Anda menerima kesalahan AADSTS50055: The password is expired saat Mendapatkan token akses.

    Saat pengguna baru masuk, mereka menerima perintah Tindakan yang Diperlukan . Mereka dapat memilih Minta nanti untuk melewati validasi.

  3. Pilih Tinjau + buat untuk meninjau pilihan Anda. Pilih Buat untuk membuat pengguna.

Memperbarui konfigurasi OAuth2 untuk otorisasi UI Swagger

Gunakan langkah-langkah berikut untuk memperbarui konfigurasi OAuth2 untuk otorisasi UI Swagger. Kemudian, Anda dapat mengotorisasi pengguna untuk memperoleh token akses melalui ToDoWeb aplikasi.

  1. Buka penyewa ID Microsoft Entra Anda di portal Azure, dan buka aplikasi terdaftarToDoWeb.

  2. Di bawah Kelola, pilih Autentikasi, pilih Tambahkan platform, lalu pilih Aplikasi halaman tunggal.

  3. Gunakan format <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html sebagai URL pengalihan OAuth2 di bidang URI Pengalihan, lalu pilih Konfigurasikan.

    Cuplikan layar portal Azure yang memperlihatkan halaman Autentikasi untuk ID Microsoft Entra.

Mendapatkan token akses

Gunakan langkah-langkah berikut untuk menggunakan metode alur kode otorisasi OAuth 2.0 untuk mendapatkan token akses dengan ID Microsoft Entra, lalu akses API ToDo RESTful aplikasi:

  1. Buka URL yang diekspos oleh aplikasi, lalu pilih Otorisasi untuk menyiapkan autentikasi OAuth2.

  2. Di jendela Otorisasi yang tersedia, masukkan ID ToDoWeb klien aplikasi di bidang client_id , pilih semua cakupan untuk bidang Cakupan , abaikan bidang client_secret , lalu pilih Otorisasi untuk mengalihkan ke halaman masuk Microsoft Entra.

Setelah menyelesaikan proses masuk dengan pengguna sebelumnya, Anda akan dikembalikan ke jendela Otorisasi yang tersedia.

5.2. Mengakses API RESTful

Gunakan langkah-langkah berikut untuk mengakses API ToDo RESTful aplikasi di antarmuka pengguna Swagger:

  1. Pilih API POST /api/simple-todo/lists lalu pilih Cobalah. Masukkan isi permintaan berikut, lalu pilih Jalankan untuk membuat daftar ToDo.

    {
      "name": "My List"
    }
    

    Setelah eksekusi selesai, Anda akan melihat isi Respons berikut:

    {
      "id": "<ID-of-the-ToDo-list>",
      "name": "My List",
      "description": null
    }
    
  2. Pilih API POST /api/simple-todo/lists/{listId}/items lalu pilih Coba. Untuk listId, masukkan ID daftar ToDo yang Anda buat sebelumnya, masukkan isi permintaan berikut, lalu pilih Jalankan untuk membuat item ToDo.

    {
      "name": "My first ToDo item", 
      "listId": "<ID-of-the-ToDo-list>",
      "state": "todo"
    }
    

    Tindakan ini mengembalikan item ToDo berikut:

    {
      "id": "<ID-of-the-ToDo-item>",
      "listId": "<ID-of-the-ToDo-list>",
      "name": "My first ToDo item",
      "description": null,
      "state": "todo",
      "dueDate": "2023-07-11T13:59:24.9033069+08:00",
      "completedDate": null
    }
    
  3. Pilih API GET /api/simple-todo/lists lalu pilih Jalankan untuk mengkueri daftar ToDo. Tindakan ini mengembalikan daftar ToDo berikut:

    [
      {
        "id": "<ID-of-the-ToDo-list>",
        "name": "My List",
        "description": null
      }
    ]
    
  4. Pilih API GET /api/simple-todo/lists/{listId}/items lalu pilih Coba. Untuk listId, masukkan ID daftar ToDo yang Anda buat sebelumnya, lalu pilih Jalankan untuk mengkueri item ToDo. Tindakan ini mengembalikan item ToDo berikut:

    [
      {
        "id": "<ID-of-the-ToDo-item>",
        "listId": "<ID-of-the-ToDo-list>",
        "name": "My first ToDo item",
        "description": null,
        "state": "todo",
        "dueDate": "2023-07-11T13:59:24.903307+08:00",
        "completedDate": null
      }
    ]
    
  5. Pilih API PUT /api/simple-todo/lists/{listId}/items/{itemId} lalu pilih Cobalah. Untuk listId, masukkan ID daftar ToDo. Untuk itemId, masukkan ID item ToDo, masukkan isi permintaan berikut, lalu pilih Jalankan untuk memperbarui item ToDo.

    {
      "id": "<ID-of-the-ToDo-item>",
      "listId": "<ID-of-the-ToDo-list>",
      "name": "My first ToDo item",
      "description": "Updated description.",
      "dueDate": "2023-07-11T13:59:24.903307+08:00",
      "state": "inprogress"
    }
    

    Tindakan ini mengembalikan item ToDo yang diperbarui berikut ini:

    {
      "id": "<ID-of-the-ToDo-item>",
      "listId": "<ID-of-the-ToDo-list>",
      "name": "My first ToDo item",
      "description": "Updated description.",
      "state": "inprogress",
      "dueDate": "2023-07-11T05:59:24.903307Z",
      "completedDate": null
    }
    
  6. Pilih API DELETE /api/simple-todo/lists/{listId}/items/{itemId} lalu pilih Cobalah. Untuk listId, masukkan ID daftar ToDo. Untuk itemId, masukkan ID item ToDo, lalu pilih Jalankan untuk menghapus item ToDo. Anda akan melihat bahwa kode respons server adalah 204.

6. Membersihkan sumber daya

Anda dapat menghapus grup sumber daya Azure, yang menyertakan semua sumber daya dalam grup sumber daya.

Gunakan langkah-langkah berikut untuk menghapus seluruh grup sumber daya, termasuk layanan yang baru dibuat:

  1. Temukan grup sumber daya Anda di portal Azure.

  2. Pada menu navigasi, pilih Grup sumber daya. Kemudian, pilih nama grup sumber daya Anda - misalnya, myresourcegroup.

  3. Pada halaman grup sumber daya Anda, pilih Hapus. Masukkan nama grup sumber daya Anda di kotak teks untuk mengonfirmasi penghapusan - misalnya, myresourcegroup. Kemudian, pilih Hapus.

Gunakan langkah-langkah berikut untuk menghapus seluruh grup sumber daya, termasuk layanan yang baru dibuat:

  1. Temukan grup sumber daya Anda di portal Azure.

  2. Pada menu navigasi, pilih Grup sumber daya. Kemudian, pilih nama grup sumber daya Anda - misalnya, myresourcegroup.

  3. Pada halaman grup sumber daya Anda, pilih Hapus. Masukkan nama grup sumber daya Anda di kotak teks untuk mengonfirmasi penghapusan - misalnya, myresourcegroup. Kemudian, pilih Hapus.

7. Langkah selanjutnya

Untuk informasi lebih lanjut, baca artikel berikut: