適用於：所有 API 管理層級
APIOps CLI 是 Azure API 管理 的配置即程式碼工具。 在本文中，你可以用它將 API Management 設定解讀到本地產物中，檢視 Git 中的產物，預覽變更，並將核准產物發佈到 API Management 實例。 CLI 也可以將 GitHub Actions 或 Azure Pipelines 檔案作為 APIOps 工作流程的支架。
這些步驟提供了一個簡潔的工作流程，你可以用非生產環境的 API 管理實例來驗證。 關於架構與設計指引，請參見 API 自動化部署與 APIOps。
使用此工作流程來：
- 透過拉取請求檢視 API 定義、政策及其他 API 管理設定。
- 保持可稽核的設定變更紀錄。
- 在 API 管理環境之間升級已檢閱的成品。
- 從現有實例擷取的設定開始，或以程式碼撰寫相容 CLI 的產物。
APIOps CLI 補充了 Use DevOps 與 CI/CD 中描述的 API DevOps 方法以發佈 API。 在非生產環境下評估 CLI 和你預期的工件工作流程，再用它來執行生產部署。
Prerequisites
- Node.js 版本 22 或更新。
- Azure CLI，用於本文中的本機驗證步驟。
- 一個 Azure 訂閱和一個現有的非生產 API 管理實例。
- 一個用來存放 API 管理產物的 Git 倉庫。
- 一個擁有 API Management 實例存取權的身份。 APIOps CLI 啟動指引在其擷取與發佈工作流程的 API 管理資源範圍內列出了 API 管理服務貢獻 者與 讀取 者角色。
生產自動化時，盡量使用獨立且權限最低的身份。 擷取身份需要對原始實例有讀取權限。 發佈身分只需要具備更新目標執行個體所需的權限。
安裝 APIOps CLI
安裝 @azure-tools/apiops-cli npm 套件：
npm install -g @azure-tools/apiops-cli
驗證已安裝的版本：
apiops --version
記錄並固定經你核准的版本，用於 CI/CD 管線。 升級前先查閱 APIOps CLI 變更日誌 。
向 Azure 驗證
若要使用本地使用，請使用 Azure CLI 登入並選擇包含你非生產環境 API Management 實例的訂閱：
az login
az account set --subscription <subscription-id>
APIOps CLI 使用 DefaultAzureCredential. 除了 Azure CLI 憑證外，它還支援環境憑證、工作負載身份、管理身份、Azure PowerShell 以及 Azure 開發者 CLI 憑證。
對於 CI/CD，建議優先使用工作負載身分同盟或受控識別，而不是使用用戶端密碼。 切勿在原始碼控制中放入憑證、存取權杖、訂閱金鑰或秘密命名值。 有關支援的認證選項，請參閱 APIOps CLI 認證指南。
準備一個文物資料庫
從包含你 API 管理產物的 Git 倉庫根執行 APIOps CLI 指令。
要為 GitHub Actions 搭建管線與設定範本，請執行：
apiops init --ci github-actions --environments dev,prod --non-interactive
若為 Azure Pipelines，請使用：
apiops init --ci azure-devops --environments dev,prod --non-interactive
此指令建立管線定義、擷取過濾器範本、環境覆寫範本、身份設定指引及 apim-artifacts 目錄。 在提交或啟用管線前，先檢查每個產生的檔案。 除非你先審查那些被指令覆寫的檔案，否則不要在已有檔案的倉庫中使用 --force 。
如果您已有存放庫和管線設計，可以改為建立或選取成品目錄，然後直接使用擷取和發佈命令。
建立初始成品
請選擇以下方法之一來建立你儲存庫所擁有的產物。
擷取現有配置
要從現有的 API Management 實例建立基準，請擷取其設定：
apiops extract \
--subscription-id <source-subscription-id> \
--resource-group <source-resource-group> \
--service-name <source-apim-name> \
--output ./apim-artifacts
此指令在 下建立 JSON 資訊檔案、XML 政策檔案及 API 規範檔案的階層結構。apim-artifacts 對於大型實例，設定 一個擷取過濾器 ，使儲存庫只管理預期的資源。
從程式碼優先的工件開始
若採用程式碼優先的工作流程，請使用 APIOps CLI 產物格式，新增 OpenAPI 規範及所需的 API 管理資訊與政策檔案。 不要假設現有的應用程式倉庫佈局或 OpenAPI 檔案本身就已經準備好。apiops publish
如果你是工件格式新手，建議先從非生產實例擷取一個小型參考 API。 將產生的檔案當作範本使用，並檢視以 程式碼為先的工作流程指引。
檢視文物
發表前：
- 檢查產生或撰寫的檔案，確認儲存庫僅包含你打算管理的資源。
- 檢視 API 規範、政策、後端、命名值、產品及其相依關係。
- 移除那些不應該移動到其他環境的環境專屬值。 適當時，請使用已審查的環境覆寫檔案或 Azure Key Vault 參考。
- 搜尋認證憑據和機密值。 擷取作業會遮蔽受支援的機密欄位和已識別的政策模式，但可能無法偵測到所有內嵌的機密資訊。 不要提交機密資訊或未解析的
*** REDACTED ***值。 - 將產物提交到分支，並使用 pull request 進行驗證與核准。
預覽發佈
對非生產目標執行個體進行試執行。 試跑會列出預計進行的建立、更新和刪除作業，但不會實際套用：
apiops publish \
--subscription-id <target-subscription-id> \
--resource-group <target-resource-group> \
--service-name <target-apim-name> \
--source ./apim-artifacts \
--dry-run
檢視輸出結果，並解決意外變更或遺失的相依性。 成功的演練並不能取代對 API 行為、政策、權限或後端連線的測試。
Caution
不要在你的第一個工作流程中增加 --delete-unmatched 內容。 這個選項會刪除目標實例中未被原始產物代表的資源。
發佈經過審查的文物
提取要求獲得核准且試執行成功後，請將相同的已檢閱成品發佈至非生產目標：
apiops publish \
--subscription-id <target-subscription-id> \
--resource-group <target-resource-group> \
--service-name <target-apim-name> \
--source ./apim-artifacts
發佈後驗證目標實例中的 API 與政策。 當您將此工作流程自動化時，請將管線設定為發佈已核准的提交，並使用貴組織要求的檢查與核准來保護部署環境。