Mulai cepat: Menyebarkan aplikasi RESTful API ke Azure Spring Apps

Catatan

Paket Basic, Standard, dan Enterprise memasuki periode pensiun pada 17 Maret 2025. Untuk informasi selengkapnya, lihat pengumuman penghentian Azure Spring Apps.

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.

Diagram berikut menunjukkan arsitektur sistem:

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

portal Azure + plugin Maven

• 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 kepada 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 dibutuhkan oleh aplikasi.

  Untuk informasi selengkapnya, lihat Persetujuan admin untuk seluruh penyewa pada aplikasi.

• Git.

• Java Development Kit (JDK), versi 17.

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

Azure CLI

• 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 kepada 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 dibutuhkan oleh aplikasi.

  Untuk informasi selengkapnya, lihat Persetujuan admin untuk seluruh penyewa pada aplikasi.

• Git.

• Java Development Kit (JDK), versi 17.

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

• Azure CLI versi 2.53.1 atau yang lebih tinggi.

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.

portal Azure + plugin Maven

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 Redundansi	Tidak dipilih	Opsi untuk membuat layanan Azure Spring Apps Anda di zona ketersediaan Azure. Fitur ini saat ini tidak didukung di semua wilayah.
   Rencana 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 untuk layanan ini di dasbor portal Azure Anda sebagai pintasan ke halaman Gambaran Umum layanan.

   

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.

   

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 konektivitas: 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.

   

3.4. Menyambungkan 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 Konektor Layanan dari panel navigasi, lalu pilih Buat untuk membuat koneksi layanan baru.

   

7. Isi tab Dasar dengan informasi berikut:

   • Jenis layanan: DB untuk Server fleksibel PostgreSQL
   • Nama koneksi: Nama yang dihasilkan secara otomatis akan diisi, yang juga dapat diubah.
   • Langganan: Pilih langganan Anda.
   • Server fleksibel PostgreSQL: my-demo-pgsql
   • Database PostgreSQL: Pilih database yang Anda buat.
   • Jenis klien: SpringBoot

   

8. Konfigurasikan tab Berikutnya: Autentikasi dengan informasi berikut:

   Catatan

   Microsoft merekomendasikan penggunaan alur autentikasi paling aman yang tersedia. Alur autentikasi yang dijelaskan dalam prosedur ini, seperti untuk database, cache, olahpesan, atau layanan AI, memerlukan tingkat kepercayaan yang sangat tinggi dalam aplikasi dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya ketika opsi yang lebih aman, seperti identitas terkelola untuk koneksi tanpa kata sandi atau tanpa kunci, tidak layak. Untuk operasi komputer lokal, lebih suka identitas pengguna untuk koneksi tanpa kata sandi atau tanpa kunci.

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

   

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>, lalu masukkan informasi berikut:

    • Untuk Nama cakupan, masukkan ToDo.Read.
    • Untuk Siapa yang 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.

    

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 aplikasi simple-todo-api. Perbarui konfigurasi di bagian spring.cloud.azure.active-directory agar sesuai dengan contoh berikut. Pastikan untuk mengganti placeholder 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 ini, lihat bagian Menggunakan endpoint yang salah (akun pribadi dan organisasi) dalam Kesalahan AADSTS50020 - Akun pengguna dari penyedia identitas tidak ada di penyewa. Untuk informasi tentang pengonversian aplikasi penyewa tunggal Anda, lihat Mengonversi aplikasi penyewa tunggal ke multipenyewa pada Microsoft Entra ID.

2. Gunakan perintah berikut untuk membangun kembali proyek sampel:

   ./mvnw clean package
   

Azure CLI

3.1. Berikan nama untuk setiap sumber daya

Buat variabel untuk menahan nama sumber daya dengan menggunakan perintah berikut. Pastikan untuk mengganti placeholder dengan nilai Anda sendiri.

Catatan

Microsoft merekomendasikan penggunaan alur autentikasi paling aman yang tersedia. Alur autentikasi yang dijelaskan dalam prosedur ini, seperti untuk database, cache, olahpesan, atau layanan AI, memerlukan tingkat kepercayaan yang sangat tinggi dalam aplikasi dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya ketika opsi yang lebih aman, seperti identitas terkelola untuk koneksi tanpa kata sandi atau tanpa kunci, tidak layak. Untuk operasi komputer lokal, lebih suka identitas pengguna untuk koneksi tanpa kata sandi atau tanpa kunci.

export RESOURCE_GROUP=myresourcegroup
export LOCATION=<location>
export POSTGRESQL_SERVER=my-demo-pgsql
export POSTGRESQL_DB=Todo
export POSTGRESQL_ADMIN_USERNAME=<admin-username>
export POSTGRESQL_ADMIN_PASSWORD=<admin-password>
export AZURE_SPRING_APPS_NAME=myasa
export APP_NAME=simple-todo-api
export TODO_APP_NAME=Todo
export TODO_APP_URL=api://simple-todo
export TODOWEB_APP_NAME=TodoWeb
export TODOWEB_APP_URL=api://simple-todoweb
export NEW_MEMBER_USERNAME=<new-member-username>
export NEW_MEMBER_PASSWORD=<new-member-password>
export USER_PRINCIPAL_NAME=<user-principal-name>

3.2. Membuat grup sumber daya baru

Gunakan langkah-langkah berikut untuk membuat grup sumber daya baru:

1. Gunakan perintah berikut untuk masuk ke Azure CLI:

   az login
   

2. Gunakan perintah berikut untuk mengatur lokasi default:

   az configure --defaults location=${LOCATION}
   

3. Gunakan perintah berikut untuk mencantumkan semua langganan yang tersedia untuk menentukan ID langganan yang akan digunakan:

   az account list --output table
   

4. Gunakan perintah berikut untuk mengatur langganan default:

   az account set --subscription <subscription-ID>
   

5. Gunakan perintah berikut ini untuk membuat grup sumber daya:

   az group create --resource-group ${RESOURCE_GROUP}
   

6. Gunakan perintah berikut untuk mengatur grup sumber daya yang baru dibuat sebagai grup sumber daya default:

   az configure --defaults group=${RESOURCE_GROUP}
   

3.3. Menginstal ekstensi dan mendaftarkan namespace

Gunakan perintah berikut untuk menginstal ekstensi Azure Spring Apps untuk Azure CLI dan mendaftarkan namespace Microsoft.SaaS.

az extension add --name spring --upgrade
az provider register --namespace Microsoft.SaaS

3.4. Membuat instans Azure Spring Apps

Gunakan langkah-langkah berikut untuk membuat instans layanan dan aplikasi dalam instans:

1. Gunakan perintah berikut untuk menerima persyaratan hukum dan pernyataan privasi untuk paket Enterprise:

   Catatan

   Langkah ini diperlukan hanya jika langganan Anda belum pernah digunakan untuk membuat instans paket Enterprise azure Spring Apps.

   az term accept \
       --publisher vmware-inc \
       --product azure-spring-cloud-vmware-tanzu-2 \
       --plan asa-ent-hr-mtr
   

2. Gunakan perintah berikut ini untuk membuat instans layanan Azure Spring Apps:

   az spring create --name ${AZURE_SPRING_APPS_NAME} --sku enterprise
   

3. Gunakan perintah berikut untuk membuat aplikasi di instans Azure Spring Apps:

   az spring app create \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --assign-endpoint true
   

3.5. Menyiapkan instans PostgreSQL

Aplikasi web Spring menggunakan H2 untuk database di localhost dan Azure Database for PostgreSQL untuk database di Azure.

Gunakan perintah berikut untuk membuat instans PostgreSQL:

Catatan

Microsoft merekomendasikan penggunaan alur autentikasi paling aman yang tersedia. Alur autentikasi yang dijelaskan dalam prosedur ini, seperti untuk database, cache, olahpesan, atau layanan AI, memerlukan tingkat kepercayaan yang sangat tinggi dalam aplikasi dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya ketika opsi yang lebih aman, seperti identitas terkelola untuk koneksi tanpa kata sandi atau tanpa kunci, tidak layak. Untuk operasi komputer lokal, lebih suka identitas pengguna untuk koneksi tanpa kata sandi atau tanpa kunci.

az postgres flexible-server create \
    --name ${POSTGRESQL_SERVER} \
    --database-name ${POSTGRESQL_DB} \
    --admin-user ${POSTGRESQL_ADMIN_USERNAME} \
    --admin-password ${POSTGRESQL_ADMIN_PASSWORD} \
    --public-access 0.0.0.0

Menentukan 0.0.0.0 memungkinkan akses publik dari sumber daya apa pun yang disebarkan dalam Azure untuk mengakses server Anda.

3.6. Menyambungkan instans aplikasi ke instans PostgreSQL

Setelah instans aplikasi dan instans PostgreSQL dibuat, instans aplikasi tidak dapat mengakses instans PostgreSQL secara langsung. Gunakan langkah-langkah berikut untuk mengaktifkan aplikasi agar tersambung ke instans PostgreSQL:

1. Gunakan perintah berikut untuk mendapatkan nama domain instans PostgreSQL yang sepenuhnya memenuhi syarat:

   export PSQL_FQDN=$(az postgres flexible-server show \
       --name ${POSTGRESQL_SERVER} \
       --query fullyQualifiedDomainName \
       --output tsv)
   

2. Gunakan perintah berikut untuk menyediakan spring.datasource. properti ke aplikasi melalui variabel lingkungan:

   Catatan

   Microsoft merekomendasikan penggunaan alur autentikasi paling aman yang tersedia. Alur autentikasi yang dijelaskan dalam prosedur ini, seperti untuk database, cache, olahpesan, atau layanan AI, memerlukan tingkat kepercayaan yang sangat tinggi dalam aplikasi dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya ketika opsi yang lebih aman, seperti identitas terkelola untuk koneksi tanpa kata sandi atau tanpa kunci, tidak layak. Untuk operasi komputer lokal, lebih suka identitas pengguna untuk koneksi tanpa kata sandi atau tanpa kunci.

   az spring app update \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --env SPRING_DATASOURCE_URL="jdbc:postgresql://${PSQL_FQDN}:5432/${POSTGRESQL_DB}?sslmode=require" \
             SPRING_DATASOURCE_USERNAME="${POSTGRESQL_ADMIN_USERNAME}" \
             SPRING_DATASOURCE_PASSWORD="${POSTGRESQL_ADMIN_PASSWORD}"
   

3.7. Mengekspos API RESTful

Gunakan langkah-langkah berikut untuk mengekspos API RESTful:

1. Gunakan perintah berikut untuk membuat aplikasi ID Microsoft Entra:

   az ad app create \
       --display-name ${TODO_APP_NAME} \
       --sign-in-audience AzureADandPersonalMicrosoftAccount \
       --identifier-uris ${TODO_APP_URL}
   

2. Gunakan perintah berikut untuk membuat prinsipal layanan untuk aplikasi:

   az ad sp create --id ${TODO_APP_URL}
   

3. Gunakan perintah berikut untuk menghasilkan ID izin:

   permissionid1=$(uuidgen);permissionid2=$(uuidgen);permissionid3=$(uuidgen)
   

4. Tambahkan cakupan berikut sebagai JSON:

   api=$(echo '{
    "oauth2PermissionScopes": [
        {
            "adminConsentDescription": "Allows authenticated users to delete the ToDo data",
            "adminConsentDisplayName": "Delete the ToDo data",
            "id": "'$permissionid1'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Delete"
        },
   
        {
            "adminConsentDescription": "Allows authenticated users to write the ToDo data",
            "adminConsentDisplayName": "Write the ToDo data",
            "id": "'$permissionid2'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Write"
        },
        {
            "adminConsentDescription": "Allows authenticated users to read the ToDo data",
            "adminConsentDisplayName": "Read the ToDo data",
            "id": "'$permissionid3'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Read"
        }
    ]}')
   

5. Gunakan perintah berikut untuk menambahkan cakupan:

   az ad app update \
       --id ${TODO_APP_URL} \
       --set api="$api"
   

6. Gunakan perintah berikut untuk mendapatkan ID penyewa yang akan digunakan di langkah berikutnya:

   az account show --query "tenantId" --output tsv
   

7. Gunakan perintah berikut untuk mendapatkan ID aplikasi yang akan digunakan di langkah berikutnya:

   appid=$(az ad app show \
       --id ${TODO_APP_URL} \
       --query appId \
       --output tsv);
   echo $appid
   

3.8. 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 aplikasi simple-todo-api. Perbarui konfigurasi di bagian spring.cloud.azure.active-directory agar sesuai dengan contoh berikut. Pastikan untuk mengganti placeholder 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 ini, lihat bagian Menggunakan endpoint yang salah (akun pribadi dan organisasi) dalam Kesalahan AADSTS50020 - Akun pengguna dari penyedia identitas tidak ada di penyewa. Untuk informasi tentang pengonversian aplikasi penyewa tunggal Anda, lihat Mengonversi aplikasi penyewa tunggal ke multipenyewa pada Microsoft Entra ID.

2. Gunakan perintah berikut untuk membangun kembali proyek sampel:

   ./mvnw clean package
   

4. Menyebarkan aplikasi ke Azure Spring Apps

portal Azure + plugin Maven

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

Azure CLI

Gunakan perintah berikut untuk menyebarkan aplikasi berdasarkan kode sumber:

az spring app deploy \
    --service ${AZURE_SPRING_APPS_NAME} \
    --name ${APP_NAME} \
    --build-env BP_JVM_VERSION=17 \
    --source-path .

5. Memvalidasi aplikasi

portal Azure + plugin Maven

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.

    

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.

   

Azure CLI

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 diharuskan untuk mendaftarkan aplikasi lain di ID Microsoft Entra dan memberikan izin ke aplikasi klien, yang diberi nama ToDoWeb.

Mendaftarkan aplikasi klien

Gunakan langkah-langkah berikut untuk mendaftarkan aplikasi klien:

1. Gunakan perintah berikut untuk membuat aplikasi ID Microsoft Entra, yang digunakan untuk menambahkan izin untuk ToDo aplikasi:

   az ad app create \
       --display-name ${TODOWEB_APP_NAME} \
       --sign-in-audience AzureADMyOrg \
       --identifier-uris ${TODOWEB_APP_URL}
   

2. Gunakan perintah berikut untuk menambahkan izin:

   az ad app permission add \
       --id api://simple-todowebtest2 \
       --api $appid \
       --api-permissions $permissionid1=Scope $permissionid2=Scope $permissionid3=Scope
   

3. Gunakan perintah berikut untuk memberikan persetujuan admin untuk izin yang Anda tambahkan:

   az ad app permission admin-consent --id ${TODOWEB_APP_URL}
   

4. Gunakan perintah berikut untuk mendapatkan ID klien aplikasi yang ToDoWeb digunakan dalam langkah Dapatkan token akses:

   az ad app show \
       --id ${TODOWEB_APP_URL} \
       --query appId \
       --output tsv
   

Menambahkan pengguna untuk mengakses API RESTful

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

Catatan

Microsoft merekomendasikan penggunaan alur autentikasi paling aman yang tersedia. Alur autentikasi yang dijelaskan dalam prosedur ini, seperti untuk database, cache, olahpesan, atau layanan AI, memerlukan tingkat kepercayaan yang sangat tinggi dalam aplikasi dan membawa risiko yang tidak ada dalam alur lain. Gunakan alur ini hanya ketika opsi yang lebih aman, seperti identitas terkelola untuk koneksi tanpa kata sandi atau tanpa kunci, tidak layak. Untuk operasi komputer lokal, lebih suka identitas pengguna untuk koneksi tanpa kata sandi atau tanpa kunci.

az ad user create \
    --display-name ${NEW_MEMBER_USERNAME} \
    --password ${NEW_MEMBER_PASSWORD} \
    --user-principal-name ${USER_PRINCIPAL_NAME}

Memperbarui konfigurasi OAuth2 untuk otorisasi UI Swagger

Gunakan langkah-langkah berikut untuk memperbarui konfigurasi OAuth2:

1. Gunakan perintah berikut untuk mendapatkan ID ToDoWeb objek aplikasi:

   az ad app show --id ${TODOWEB_APP_URL} --query id
   

2. Gunakan perintah berikut untuk mendapatkan URL aplikasi Anda simple-todo-api :

   az spring app show \
       --name ${APP_NAME} \
       --service ${AZURE_SPRING_APPS_NAME} \
       --query properties.url
   

3. Gunakan perintah berikut untuk memperbarui konfigurasi OAuth2 guna otorisasi Swagger UI, dengan mengganti placeholder <object-id> dan <URL> dengan nilai parameter yang Anda peroleh. Kemudian, Anda dapat mengotorisasi pengguna untuk memperoleh token akses melalui ToDoWeb aplikasi.

   az rest \
       --method PATCH \
       --uri "https://graph.microsoft.com/v1.0/applications/<object-id>" \
       --headers 'Content-Type=application/json' \
       --body '{"spa":{"redirectUris":["<URL>/swagger-ui/oauth2-redirect.html"]}}'
   

Mendapatkan token akses

Gunakan langkah-langkah berikut dengan menggunakan metode aliran kode otorisasi OAuth 2.0 untuk mendapatkan token akses dengan ID Microsoft Entra, lalu akses ToDo API 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.

portal Azure + plugin Maven

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.

Azure CLI

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

az group delete --name ${RESOURCE_GROUP}

7. Langkah selanjutnya

Mulai cepat: Menyebarkan aplikasi berbasis peristiwa ke Azure Spring Apps

Mulai cepat: Menyebarkan aplikasi layanan mikro ke Azure Spring Apps

Log aplikasi terstruktur untuk Azure Spring Apps

Memetakan domain kustom yang sudah ada ke Azure Spring Apps

Gunakan Azure Spring Apps CI/CD dengan GitHub Actions

Mengotomatiskan penyebaran aplikasi ke Azure Spring Apps

Untuk informasi lebih lanjut, baca artikel berikut:

• Sampel Azure Spring Apps.
• Musim Semi di Azure
• Spring Cloud Azure