Tutorial: Menjalankan perintah shell dalam kumpulan sesi menggunakan Azure Container Apps (pratinjau)

Tutorial ini menunjukkan cara menyebarkan kumpulan sesi shell di Azure Container Apps dan menjalankan perintah shell menggunakan api Sesi Dinamis dan templat ARM.

Di tutorial ini, Anda akan:

Prasyarat

Anda memerlukan sumber daya berikut sebelum memulai tutorial ini.

Pengaturan

Mulailah dengan menyiapkan Azure CLI dengan pembaruan terbaru dan masuk ke Azure.

1. Perbarui Azure CLI ke versi terbaru.

   az upgrade
   

2. Daftarkan penyedia sumber Microsoft.App.

   az provider register --namespace Microsoft.App
   

3. Instal versi terbaru ekstensi CLI Azure Container Apps.

   az extension add --name containerapp --allow-preview true --upgrade
   

4. Masuk ke Azure.

   az login
   

5. Kueri untuk ID langganan Azure Anda dan atur nilai ke variabel.

   SUBSCRIPTION_ID=$(az account show --query id --output tsv)
   

6. Atur variabel yang digunakan dalam prosedur ini.

   Sebelum Anda menjalankan perintah berikut, pastikan untuk mengganti tempat penampung yang dikelilingi dengan <> nilai Anda sendiri.

   RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
   SESSION_POOL_NAME=<SESSION_POOL_NAME>
   LOCATION=<LOCATION>
   API_VERSION="2025-10-02-preview"
   

   Anda menggunakan variabel ini untuk membuat sumber daya dalam langkah-langkah berikut.

7. Atur langganan yang ingin Anda gunakan untuk membuat grup sumber daya.

   az account set -s $SUBSCRIPTION_ID
   

8. Buat grup sumber daya.

   az group create --name $RESOURCE_GROUP --location $LOCATION
   

Buat templat ARM

Buat file templat ARM bernama deploy.json untuk menentukan kumpulan sesi shell Anda.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
      {
         "apiVersion": "2025-10-02-preview",
            "name": "myshellpool",
            "type": "Microsoft.App/sessionpools",
            "location": "North Central US",
            "properties": {
                "poolManagementType": "Dynamic",
                "containerType": "Shell", # Set the "containerType" property to "Shell"
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "cooldownPeriodInSeconds": 300
                    }
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                }
            }
        }
    ]
}

Penerapan kumpulan sesi shell

Gunakan templat ARM untuk menyebarkan kumpulan sesi shell Anda.

az deployment group create --resource-group $RESOURCE_GROUP --template-file deploy.json

Menetapkan identitas terkelola

Buat identitas terkelola yang ditetapkan pengguna yang akan digunakan untuk mengautentikasi panggilan API ke kumpulan sesi.

1. Atur nama identitas dan ID sumber daya kumpulan.

   UAMI_NAME=${SESSION_POOL_NAME}-uami
   POOL_ID="/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME"
   

2. Buat identitas terkelola yang ditetapkan pengguna.

   az identity create --resource-group $RESOURCE_GROUP --name $UAMI_NAME --location $LOCATION
   

3. Dapatkan ID utama identitas terkelola.

   UAMI_PRINCIPAL=$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI_NAME --query principalId -o tsv)
   

Menetapkan identitas terkelola ke Aplikasi Kontainer Azure Anda

Saat membuat atau memperbarui Azure Container App Anda, tetapkan identitas terkelola yang ditetapkan pengguna ke aplikasi. Contohnya:

az containerapp update \
  --name <CONTAINER_APP_NAME> \
  --resource-group $RESOURCE_GROUP \
  --user-assigned $UAMI_NAME

Lihat Menetapkan identitas terkelola ke aplikasi kontainer untuk detail selengkapnya.

Mengatur penetapan peran untuk API eksekusi sesi

Untuk berinteraksi dengan API kumpulan sesi, Anda harus menetapkan peran Azure ContainerApps Session Executor ke identitas terkelola Anda.

Tunggu penyebaran identitas, kemudian tetapkan peran ke identitas terkelola.

az role assignment create --assignee $UAMI_PRINCIPAL --role "Azure ContainerApps Session Executor" --scope $POOL_ID

Mendapatkan token pembawa

Untuk mengakses API kumpulan sesi, Anda memerlukan token akses. Metode ini tergantung pada tempat Anda menjalankan kode:

Dari dalam Aplikasi Kontainer Azure Anda

Saat berjalan dari dalam suatu Aplikasi Kontainer Azure yang memiliki identitas terkelola yang ditetapkan oleh pengguna, dapatkan token akses menggunakan Layanan Metadata Instans Azure (IMDS):

ACCESS_TOKEN=$(curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://dynamicsessions.io" \
  | jq -r '.access_token')

Perintah ini mengambil token dan mengekstrak access_token nilai dari respons JSON menggunakan jq.

Untuk pengujian dan pengembangan lokal

Saat menguji secara lokal atau dari lingkungan pengembangan, Anda dapat memperoleh token akses menggunakan Azure CLI (Anda harus memiliki izin yang sesuai):

ACCESS_TOKEN=$(az account get-access-token --resource "https://dynamicsessions.io" --query accessToken --output tsv)

Menjalankan perintah shell dalam sesi Anda

Sekarang setelah Anda memiliki token pembawa untuk menetapkan konteks keamanan, Anda dapat mengirim permintaan ke kumpulan sesi untuk menjalankan perintah shell.

1. Buat isi permintaan untuk panggilan API.

   EXEC_ID=$(uuidgen)
   BODY=$(cat <<EOF
    {
      "codeInputType": "inline",
      "executionType": "synchronous",
      "shellCommand": "echo Hello world!",
      "timeoutInSeconds": 600
    }
    EOF
    )
   

2. Buat URL titik akhir API.

   URL="https://$LOCATION.dynamicsessions.io/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/sessionPools/$SESSION_POOL_NAME/executions?api-version=$API_VERSION&identifier=$EXEC_ID"
   

3. Jalankan perintah shell.

   Dari dalam Azure Container App atau pengujian lokal:

   curl --request POST --url "$URL" --header "Authorization: Bearer $ACCESS_TOKEN" --header 'content-type: application/json' --data "$BODY"
   

   Anda harus menerima respons JSON yang berisi hasil eksekusi, termasuk output dari perintah shell (hello world dan hi).

Verifikasi penerapan Anda

Anda dapat memverifikasi bahwa sumber daya Anda berhasil dibuat menggunakan perintah ini:

1. Verifikasi penyebaran kumpulan sesi.

   az resource show --ids "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --query '{name:name, location:location, provisioningState:properties.provisioningState}'
   

2. Verifikasi penetapan peran.

   az role assignment list --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --output table
   

Membersihkan sumber daya

Sumber daya yang dibuat dalam tutorial ini berpengaruh pada tagihan Azure Anda. Jika Anda tidak akan menggunakan layanan ini dalam jangka panjang, jalankan perintah berikut untuk menghapus semua yang dibuat dalam tutorial ini.

az group delete --resource-group $RESOURCE_GROUP

Langkah selanjutnya

• Pelajari selengkapnya tentang sesi Azure Container Apps
• Telusuri sampel API Sesi Dinamis
• Memahami manajemen kumpulan sesi