教學課程：建置應用程式並將其部署至 Azure 容器應用程式

本文示範如何使用您偏好的程式設計語言從來源存放庫建置微服務，並將其部署至 Azure 容器應用程式。

這是系列文章中的第一個教學課程，逐步引導您了解如何使用 Azure 容器應用程式中的核心功能。 第一步是建立後端 Web API 服務，以傳回靜態音樂專輯集合。

注意

您也可以依照快速入門：從存放庫建置應用程式並將其部署至 Azure 容器應用程式 (部分機器翻譯) 一文中的指示，使用 az containerapp up 來建置和部署此應用程式。 az containerapp up 命令是使用單一命令建置應用程式並將其部署至 Azure 容器應用程式的快速便利方式。 不過，該命令不會為您的容器應用程式提供相同的自訂層級。

本系列的下一個教學課程會建置前端 Web 應用程式，並將其部署至 Azure 容器應用程式。

下列螢幕擷取畫面顯示本教學課程中所部署專輯 API 的輸出。

必要條件

若要完成此專案，您需要下列項目：

需求	指示
Azure 帳戶	如果您沒有帳戶，可免費建立帳戶。 您需要 Azure 訂用帳戶的使用者存取管理員或擁有者權限才能繼續。 請務必針對您的內容使用限制最嚴格的角色。 如需詳細資訊，請參閱使用 Azure 入口網站指派 Azure 角色和 Azure 角色、Microsoft Entra 角色和傳統訂用帳戶管理員角色。
GitHub 帳戶	免費註冊。
git	安裝 git
Azure CLI	安裝 Azure CLI。

需求	指示
Azure 帳戶	如果您沒有帳戶，可免費建立帳戶。 您需要 Azure 訂用帳戶的「參與者」或「擁有者」權限才能繼續。 如需詳細資料，請參閱使用 Azure 入口網站指派 Azure 角色。
GitHub 帳戶	免費註冊。
git	安裝 git
Azure CLI	安裝 Azure CLI。
Docker Desktop	Docker 提供可在 macOS、Windows 和 Linux 上設定 Docker 環境的安裝程式。 在命令提示字元中，輸入 docker 以確保 Docker 正在執行。

設定

若要從 CLI 登入 Azure，請執行下列命令，並遵循提示來完成驗證流程。

Bash

az login

Azure PowerShell

Connect-AzAccount

若要確定您執行的是最新版本 CLI，請執行升級命令。

Bash

az upgrade

Azure PowerShell

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

忽略目前使用中模組的任何警告。

接下來，安裝或更新 CLI 的 Azure 容器應用程式延伸模組。

如果您在 Azure CLI 中執行 az containerapp 命令或 Azure PowerShell 模組中的 Cmdlet Az.App 時收到遺漏參數的錯誤，請確定您已安裝最新版的 Azure 容器應用程式延伸模組。

Bash

az extension add --name containerapp --upgrade

注意

從 2024 年 5 月開始，Azure CLI 延伸模組預設不會再啟用預覽功能。 若要存取容器應用程式預覽功能，請使用 --allow-preview true 安裝容器應用程式延伸模組。

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

Azure PowerShell

Install-Module -Name Az.App

請務必將 Az.App 模組更新為最新版本。

Update-Module -Name Az.App

現在已安裝目前的延伸模組或模組，請註冊 Microsoft.App 和 Microsoft.OperationalInsights 命名空間。

Bash

az provider register --namespace Microsoft.App

az provider register --namespace Microsoft.OperationalInsights

Azure PowerShell

Register-AzResourceProvider -ProviderNamespace Microsoft.App

Register-AzResourceProvider -ProviderNamespace Microsoft.OperationalInsights

建立環境變數

現在您的 Azure CLI 設定已完成，接下來您可以定義本文中使用的環境變數了。

Bash

在您的 Bash 殼層中定義下列變數。

RESOURCE_GROUP="album-containerapps"
LOCATION="canadacentral"
ENVIRONMENT="env-album-containerapps"
API_NAME="album-api"
FRONTEND_NAME="album-ui"
GITHUB_USERNAME="<YOUR_GITHUB_USERNAME>"

執行此命令之前，請務必將 <YOUR_GITHUB_USERNAME> 取代為您的 GitHub 使用者名稱。

接下來，定義唯一的容器登錄名稱。

ACR_NAME="acaalbums"$GITHUB_USERNAME

Azure PowerShell

在您的 PowerShell 主控台中定義下列變數。

$ResourceGroup = "album-containerapps"
$Location = "canadacentral"
$Environment = "env-album-containerapps"
$APIName="album-api"
$FrontendName="album-ui"
$GITHUB_USERNAME = "<YOUR_GITHUB_USERNAME>"

執行此命令之前，請務必將 <YOUR_GITHUB_USERNAME> 取代為您的 GitHub 使用者名稱。

接下來，定義唯一的容器登錄名稱。

$ACRName = "acaalbums"+$GITHUB_USERNAME

準備 GitHub 存放庫

瀏覽至慣用語言的存放庫，並派生存放庫。

C#

選取專輯 API 存放庫頂端的 [分支] 按鈕，將存放庫派生至您的帳戶。

現在，您可以複製範例存放庫的分支。

使用下列 git 命令，將分支存放庫複製到 code-to-cloud 資料夾：

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-csharp.git code-to-cloud

Go

選取專輯 API 存放庫頂端的 [分支] 按鈕，將存放庫派生至您的帳戶。

現在，您可以複製範例存放庫的分支。

使用下列 git 命令，將分支存放庫複製到 code-to-cloud 資料夾：

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-go.git code-to-cloud

Java

選取專輯 API 存放庫頂端的 [分支] 按鈕，將存放庫派生至您的帳戶。

現在，您可以複製範例存放庫的分支。

使用下列 git 命令，將分支存放庫複製到 code-to-cloud 資料夾：

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-java.git code-to-cloud

注意

Java 範例僅支援 Maven 組建，這會產生 JAR 檔案可執行檔。 組建會使用預設設定，因為不支援傳入環境變數。

JavaScript

選取專輯 API 存放庫頂端的 [分支] 按鈕，將存放庫派生至您的帳戶。

現在，您可以複製範例存放庫的分支。

使用下列 git 命令，將分支存放庫複製到 code-to-cloud 資料夾：

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-javascript.git code-to-cloud

Python

選取專輯 API 存放庫頂端的 [分支] 按鈕，將存放庫派生至您的帳戶。

現在，您可以複製範例存放庫的分支。

使用下列 git 命令，將分支存放庫複製到 code-to-cloud 資料夾：

git clone https://github.com/$GITHUB_USERNAME/containerapps-albumapi-python.git code-to-cloud

接下來，將目錄變更為複製存放庫的根目錄。

cd code-to-cloud/src

建立 Azure 資源群組

建立資源群組，以組織與容器應用程式部署相關的服務。

Bash

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

Azure PowerShell

New-AzResourceGroup -Location $Location -Name $ResourceGroupName

建立 Azure Container Registry

1. 在建立專輯 API 容器映像後，在資源群組中建立 Azure Container Registry (ACR) 執行個體，以儲存。

   Bash

   az acr create \
       --resource-group $RESOURCE_GROUP \
       --location $LOCATION \
       --name $ACR_NAME \
       --sku Basic
   

   Azure PowerShell

   $acr = New-AzContainerRegistry `
       -ResourceGroupName $ResourceGroup `
       -Location $Location `
       -Name $ACRName `
       -Sku Basic
   

2. 您的容器登錄必須允許 Azure Resource Manager（ARM） 物件令牌進行驗證，才能使用受控識別來提取映像。

   使用下列命令來檢查是否允許ARM令牌存取您的 Azure Container Registry（ACR）。

   Bash

   az acr config authentication-as-arm show --registry "$ACR_NAME"
   

   如果允許 ARM 令牌，命令會輸出下列命令。

   {
     "status": "enabled"
   }
   

   status如果 為 disabled，請使用下列命令允許ARM令牌。

   az acr config authentication-as-arm update --registry "$ACR_NAME" --status enabled
   

   Azure PowerShell

   $acr.AzureAdAuthenticationAsArmPolicyStatus
   

   如果命令傳 disabled回 ，請使用下列命令允許 ARM 令牌。

   Update-AzContainerRegistry `
       -ResourceGroupName $acr.ResourceGroupName `
       -Name $acr.Name `
       -AzureAdAuthenticationAsArmPolicyStatus enabled
   

建立使用者指派的受控識別

若要避免使用系統管理認證，請使用受控識別進行驗證，從 Microsoft Azure Container Registry 中的私人存放庫提取映像。 可能的話，請使用使用者指派的受控識別來提取映像。

Bash

1. 建立使用者指派的受控識別。 執行下列命令之前，請選擇受控識別的名稱，並將 取代 \<PLACEHOLDER\> 為 名稱。

   IDENTITY="<YOUR_IDENTITY_NAME>"
   

   az identity create \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP
   

2. 取得身分識別的資源標識碼。

   IDENTITY_ID=$(az identity show \
       --name $IDENTITY \
       --resource-group $RESOURCE_GROUP \
       --query id \
       --output tsv)
   

Azure PowerShell

1. 建立使用者指派的受控識別。 執行下列命令之前，請選擇受控識別的名稱，並將 取代 \<PLACEHOLDER\> 為 名稱。

   $IdentityName="<YOUR_IDENTITY_NAME>"
   $Identity = New-AzUserAssignedIdentity -ResourceGroupName $ResourceGroup -Name $IdentityName
   

2. 取得身分識別的資源和主體識別碼。

   $IdentityId = $Identity.Id
   $PrincipalId = (Get-AzUserAssignedIdentity -Name $IdentityName -ResourceGroupName $ResourceGroup).PrincipalId
   

3. 取得登錄的資源識別碼。 執行下列命令之前，請以登錄的資源群組名稱取代 <預留位置>。

   $RegistryId = (Get-AzContainerRegistry -ResourceGroupName $ResourceGroup -Name $ACRName).Id
   

4. 為身分識別建立 acrpull 角色指派。

   New-AzRoleAssignment -ObjectId $PrincipalId -Scope $RegistryId -RoleDefinitionName acrpull
   

建置您的 應用程式

透過 ACR 工作，您無須在本機安裝 Docker，即可建置和推送專輯 API 的 Docker 映像。

使用 ACR 建置容器

執行下列命令，以使用 ACR 起始映像建置和推送流程。 命令結尾的 . 代表 Docker 建置內容，這表示此命令應在 Dockerfile 所在的 src 資料夾中執行。

Bash

az acr build --registry $ACR_NAME --image $API_NAME .

Azure PowerShell

命令 az acr build 沒有對等的 PowerShell，但可以在 PowerShell 中執行。

若要使用 Azure CLI 登入 Azure，請執行下列命令，並遵循提示來完成驗證程式。

az login

然後建置容器。

az acr build --registry $AcrName --image $APIName .

az acr build 命令的輸出會顯示原始程式碼到 Azure 的上傳進度，以及 docker build 和 docker push 作業的詳細資料。

建置您的 應用程式

下列步驟示範如何使用 Docker 在本機建置容器映射，並將映像推送至新的容器登錄。

使用 Docker 建置容器

下列命令會建置專輯 API 的容器映像，並使用 ACR 登入伺服器的完整名稱加以標記。 命令結尾的 . 代表 Docker 建置內容，這表示此命令應在 Dockerfile 所在的 src 資料夾中執行。

Bash

docker build --tag $ACR_NAME.azurecr.io/$API_NAME .

Azure PowerShell

docker build --tag "$ACRName.azurecr.io/$APIName" .

將映像推送至容器登錄

首先，登入您的 Azure Container Registry。

Bash

az acr login --name $ACR_NAME

Azure PowerShell

Connect-AzContainerRegistry -Name $ACRName

現在，將映像推送至您的登錄。

Bash

docker push $ACR_NAME.azurecr.io/$API_NAME

Azure PowerShell

docker push "$ACRName.azurecr.io/$APIName"

建立容器應用程式環境

Azure 容器應用程式環境可作為容器應用程式群組周圍的安全界限。

使用下列命令建立容器應用程式環境。

Bash

az containerapp env create \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --location "$LOCATION"

Azure PowerShell

容器應用程式環境需要 Log Analytics 工作區。 下列命令會建立 Log Analytics 工作區，並將工作區識別碼和主要共用金鑰儲存至變數。

$WorkspaceArgs = @{
    Name = 'my-album-workspace'
    ResourceGroupName = $ResourceGroup
    Location = $Location
    PublicNetworkAccessForIngestion = 'Enabled'
    PublicNetworkAccessForQuery = 'Enabled'
}
New-AzOperationalInsightsWorkspace @WorkspaceArgs
$WorkspaceId = (Get-AzOperationalInsightsWorkspace -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).CustomerId
$WorkspaceSharedKey = (Get-AzOperationalInsightsWorkspaceSharedKey -ResourceGroupName $ResourceGroup -Name $WorkspaceArgs.Name).PrimarySharedKey

若要建立環境，請執行下列命令：

$EnvArgs = @{
    EnvName = $Environment
    ResourceGroupName = $ResourceGroup
    Location = $Location
    AppLogConfigurationDestination = 'log-analytics'
    LogAnalyticConfigurationCustomerId = $WorkspaceId
    LogAnalyticConfigurationSharedKey = $WorkspaceSharedKey
}

New-AzContainerAppManagedEnv @EnvArgs

將映像部署至容器應用程式

現在您已建立環境，則可以使用 az containerapp create 命令建立及部署容器應用程式。

使用下列命令建立及部署容器應用程式。

Bash

az containerapp create \
  --name $API_NAME \
  --resource-group $RESOURCE_GROUP \
  --environment $ENVIRONMENT \
  --image $ACR_NAME.azurecr.io/$API_NAME \
  --target-port 8080 \
  --ingress external \
  --registry-server $ACR_NAME.azurecr.io \
  --user-assigned "$IDENTITY_ID" \
  --registry-identity "$IDENTITY_ID" \
  --query properties.configuration.ingress.fqdn

• 透過將 --ingress 設定為 external，您的容器應用程式可從公用網際網路存取。

• target-port 會設定為 8080，以符合容器正在接聽要求的連接埠。

• 如果沒有 query 屬性，則對 az containerapp create 的呼叫會傳回 JSON 回應，其中包含一系列豐富的應用程式詳細資料。 新增查詢參數僅就應用程式的完整網域名稱 (FQDN) 篩選輸出。

• 此命令會將 acrPull 角色新增至使用者指派的受控識別，以便從容器登錄提取映像。

Azure PowerShell

若要建立容器應用程式，請建立範本物件，以引數形式傳入 New-AzContainerApp 命令。

1. 建立範本物件來定義容器映像參數。

   $ImageParams = @{
       Name = $APIName
       Image = $ACRName + '.azurecr.io/' + $APIName + ':latest'
   }
   $TemplateObj = New-AzContainerAppTemplateObject @ImageParams
   

2. 建立登錄認證對象來定義您的登錄資訊。

   $RegistryArgs = @{
       Server = $ACRName + '.azurecr.io'
       Identity = $IdentityId
   }
   $RegistryObj = New-AzContainerAppRegistryCredentialObject @RegistryArgs
   

3. 取得您的環境識別碼。

   $EnvId = (Get-AzContainerAppManagedEnv -EnvName $Environment -ResourceGroup $ResourceGroup).Id
   

4. 建立容器應用程式。

   $AppConfig = @{
       IngressTargetPort = 8080
       IngressExternal = $true
       Registry = $RegistryObj
   }
   $AppConfigObj = New-AzContainerAppConfigurationObject @AppConfig
   
   $AppArgs = @{
       Name = $APIName
       Location = $Location
       ResourceGroupName = $ResourceGroup
       ManagedEnvironmentId = $EnvId
       TemplateContainer = $TemplateObj
       Configuration = $AppConfigObj
       UserAssignedIdentity = @($IdentityId)
   }
   $MyApp = New-AzContainerApp @AppArgs
   
   # Show the app's fully qualified domain name (FQDN).
   $MyApp.LatestRevisionFqdn
   

   • 透過將 IngressExternal 設定為 $true，您的容器應用程式可從公用網際網路存取。
   • IngressTargetPort 參數會設定為 8080，以符合容器正在接聽要求的連接埠。

驗證部署

將 FQDN 複製到網頁瀏覽器。 從網頁瀏覽器，瀏覽至 FQDN 的 /albums 端點。

清除資源

如果您不打算繼續進行微服務之間的通訊 (部分機器翻譯) 教學課程，則可以移除本快速入門期間建立的 Azure 資源。 請執行下列命令來刪除資源群組，以及在本快速入門中建立的所有資源。

Bash

az group delete --name $RESOURCE_GROUP

Azure PowerShell

Remove-AzResourceGroup -Name $ResourceGroup -Force

提示

有問題嗎？ 在 Azure 容器應用程式存放庫中提出問題，讓我們在 GitHub 上了解該問題。

下一步

本快速入門是一系列漸進式教學課程的起點，展示了 Azure 容器應用程式內的各種功能。 繼續了解如何啟用來自 Web 前端的通訊，以呼叫您在本文中部署的 API。

教學課程：微服務之間的通訊 (部分機器翻譯)