Azure 開發人員 CLI 樣本概觀

Azure 開發者 CLI （azd） 範本是一個遵循azd慣例的程式碼庫。 它結合了專案設定、基礎架構即程式碼，以及可選的應用程式來源，讓你能建立可重複的 Azure 環境與部署。

範本可支援不同類型的專案，包括：

• 一個完整的應用程式，包含一個或多個可部署服務。
• 僅針對基礎設施的解決方案，無需應用程式碼。
• 一個可重複使用的起點，讓其他開發者可以初始化並擴展。
• 為了使用 azd 進行佈建和部署而準備的現有專案。

本文說明範本的結構以及指令如何 azd 使用其檔案。

為什麼要用範本？

範本則記錄了在 Azure 上執行專案所需的決策。 視專案而定，它可以定義：

• Azure 資源及其設定。
• 可部署的應用服務與打包說明。
• 應用程式服務與 Azure 資源之間的連結。
• 環境特定的參數與輸出。
• 本地開發、持續整合與持續交付配置。

由於設定與專案一同儲存，團隊可以檢視原始碼控制的變更，建立一致的開發、測試及生產環境。

azd 如何使用範本

範本中的檔案支援工作流程的不同 azd 階段：

• azd init 初始化專案並建立 azd 一個環境。 它也可以使用 GitHub Copilot 產生初始範本或複製現有範本。
• azd provision評估基礎架構定義，並建立或更新 Azure 資源。
• azd package 根據 azure.yaml 準備可部署的應用程式服務。
• azd deploy將每個服務與其 Azure 主機關聯，並部署應用程式套件。
• azd up 將配置、打包與部署階段作為合併的工作流程執行。

模板檔案在此過程中仍維持為一般原始碼檔案。 你可以檢視、編輯並與專案其他部分一起進行版本化。

探索 Azure 開發人員 CLI 樣本結構

azd 範本是標準的程式碼庫，並附有額外的設定與基礎架構資產。 大多數範本採用以下結構：

• azure.yaml file - 定義專案並將可部署的原始碼目錄映射到 Azure 資源。
• infra資料夾 - 包含建立 Azure 資源的 Bicep 或 Terraform 基礎設施即程式碼檔案。
• src 資料夾 - 通常包含可部署的應用程式原始碼。 僅基礎設施範本可以省略應用程式原始碼，應用程式範本則可使用其他來源目錄名稱。
• .azure 資料夾 - 包含由 azd. 建立的本地環境與值。 這個資料夾是本地專案狀態，通常不會作為可重用範本的一部分分享。

例如，常見的 azd 範本可能會符合下列資料夾結構：

contoso-project/
├── azure.yaml                 # azd project and service configuration
├── infra/
│   ├── main.bicep            # Infrastructure entry point
│   └── main.parameters.json  # Maps azd values to Bicep parameters
├── src/                      # Optional application source
│   ├── api/
│   └── web/
├── .github/workflows/        # Optional GitHub Actions pipelines
└── .azure/                   # Local environment state; don't distribute

azd 範本也可以選擇性地包含下列一或多個資料夾：

• .github資料夾 - 存放 GitHub Actions 的 CI/CD 工作流程檔案。
• .azdo 資料夾 - 如果您決定使用適用於 CI/CD 的 Azure Pipelines，請在此資料夾中定義工作流程組態檔。
• .devcontainer 資料夾 - 定義專案 的開發容器 環境。

下圖展示了主要範本資產如何協同運作：

flowchart LR
AZ[azure.yaml] -->|Defines services| SRC[Application source]
AZ -->|Selects provider and path| INFRA[Infrastructure as code]
INFRA -->|Provisions| RES[Azure resources]
INFRA -->|Exports values| ENV[azd environment]
ENV -->|Configures| SRC
AZ -->|Maps services to| RES

必備與選修資產

具體結構會因專案而異，但大多數範本會使用以下素材。

azure.yaml

該 azure.yaml 檔案是主要的專案設定檔。 它定義專案名稱，並能定義可部署服務、基礎架構提供者、鉤子、工作流程及其他 azd 行為。

對於應用程式服務， azure.yaml 通常會識別：

• 通往應用程式來源的路徑。
• 程式語言或封裝策略。
• 就是承載該應用程式的 Azure 服務。
• 建置、部署、容器或 Kubernetes 設定。

僅包含基礎結構的範本可以省略應用服務。 完整組態模型請參閱結構圖azure.yaml。

以下範例定義了兩種應用服務。 服務名稱、原始碼路徑、語言與託管目標告訴 azd 我們該打包什麼以及部署在哪裡：

name: store
services:
  api:
    project: ./src/api
    language: js
    host: containerapp
  web:
    project: ./src/web
    language: js
    host: staticwebapp

基礎結構即程式碼

大多數範本包含infra包含 Bicep 或 Terraform 檔案的目錄。 這些檔案定義了專案所需的 Azure 資源、角色指派、網路、應用程式設定及部署輸出。

對於預設的 Bicep 提供者，azd 通常會使用 infra/main.bicep 作為部署進入點，並使用 infra/main.parameters.json 將 azd 環境值映射至 Bicep 參數。 Terraform 範本通常使用 infra/main.tf 及相關的 Terraform 檔案。

例如，Bicep 參數檔案可以將由 azd 選取的值傳遞至基礎架構部署：

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" }
  }
}

當 Bicep 配置完成後，會azd將進入點的輸出儲存為環境值。 應用程式服務與鉤子可利用這些值作為資源端點、名稱及其他執行時設定。

output API_ENDPOINT string = api.outputs.uri

應用程式來源

應用程式來源為可選。 當範本包含可部署服務時，每個 azure.yaml 服務定義都指向其來源目錄。 範本可將服務整理到 src 之下、使用儲存庫中的其他目錄，或將服務指向儲存庫根目錄。

資料夾名稱本身並不重要。 azure.yaml 中的 project 值決定了 azd 在哪裡找到各個服務。

環境設定

該 .azure 目錄包含由 azd所建立的本地環境狀態與值。 它可以包含訂閱、位置、資源名稱、端點，以及多個環境的部署輸出值。

將此目錄視為本地狀態，而非可重複使用的範本資產。 不要提交包含秘密或特定環境值的環境檔案。

支援資產

範本也可以包含：

• GitHub Actions 或 Azure Pipelines 定義。
• Docker 檔案與容器設定。
• 開發容器設定。
• 命令和服務掛鉤。
• 測試、腳本和專案文件。

這些資產是可選的，只有在支援預期範本體驗時才應納入。

服務與資源協會

要部署應用程式服務，azd必須將其定義azure.yaml與已配置的 Azure 資源關聯。 預設情況下， azd 會找到標籤 azd-service-name 與服務名稱相符的資源。

例如，一個名為 api 的服務對應到一個標記為 azd-service-name: api的資源。 你可以改用 resourceName 服務屬性來明確識別部署目標。

以下 Bicep 運算式會將探索標籤新增至資源的現有標籤中：

tags: union(tags, {
  'azd-service-name': 'api'
})

編輯範本時，請保持服務名稱、資源發現設定、基礎設施輸出和應用環境變數的一致性。

建立或調整範本

建議的創作體驗是執行azd init並選擇「Set up with GitHub Copilot （Preview）」。 專用的 Copilot Agent 會話可以分析現有檔案、協助規劃新專案、產生範本資產，並驗證結果。 關於此工作流程及其他創作方法，請參見 「從新範本開始」。

產生的檔案並未綁定到 Copilot。 你可以在初始化後直接 探索和編輯範本檔案 。 你也可以手動建立這些相同的檔案，或使用另一個 AI 編碼代理來建立。

如果 Microsoft、你的組織或開發者社群已經提供有用的架構範本，請從現有範本開始，並針對你的專案進行調整。 瀏覽範本 畫廊中的可用範本。

範本使用指引

每個範本均由其擁有者依據範本附帶的協議授權。 在使用或發佈範本前，先確定適用哪種授權。

Microsoft 不負責非 Microsoft 的範本，也不會針對安全、隱私、相容性或效能問題進行篩選。 範本，包括 Microsoft 提供的範本，不受 Microsoft 支援計畫或服務支持，且僅以原樣提供，無需保固。

在配置前檢查所有範本檔案。 特別是，評估角色指派、網路暴露、認證方法、服務層級、資源位置及預期成本。

後續步驟