開始使用 API 中心
在本練習中，您將會：
建立 API 中心服務。
定義中繼資料屬性。
將 API 新增至 API 中心。
新增部署和環境。
必要條件
若要開始透過 API 中心來管理 API，您需要：
- Azure 訂用帳戶。
- 在您的訂用帳戶中註冊的 Microsoft.ApiCenter 資源提供者。
- 在 Azure 訂用帳戶中至少有參與者角色指派或對等權限。
注意
如果您尚未在訂用帳戶中註冊 Microsoft.ApiCenter 資源提供者，必須先註冊。
- 登入 Azure 入口網站。
- 在搜尋列中輸入訂用帳戶。
- 選取您要在其中建立 API 中心的訂用帳戶。
- 在左側功能表的 [資源] 底下，選取 [資源提供者]。
- 在資源提供者清單中搜尋 Microsoft.ApiCenter。 如果未註冊，請選取 [註冊]。
步驟 1：建立 API 中心服務
若要在本機執行 CLI 參考命令，請安裝 Azure CLI，並使用下列命令登入。
az login
注意
如果您尚未在訂用帳戶中註冊 Microsoft.ApiCenter 資源提供者，必須先註冊。
執行下列命令以註冊資源提供者
az provider register –namespace Microsoft.ApiCenter
步驟 1：建立 API 中心服務
執行下列命令以建立資源群組；請傳入：
- 資源群組名稱 --name 範例。 Contoso
- 位置範例 --location 範例。 Eastus
az group create –-name contoso –-location eastus
注意
az apic 命令需要 apic-extension Azure CLI 延伸模組。 如果您尚未使用 az apic 命令，延伸模組將會在您執行第一個 az apic 命令時動態安裝，或者您可以手動安裝延伸模組。 深入了解 Azure CLI 延伸模組。
執行下列命令以建立 API 中心；請傳入：
- API 中心服務名稱 -n 範例。 contoso-apis
- 資源群組 -g 範例。 Contoso
- 位置 --l 範例。 Eastus
az apic create -n contoso-apis -g contoso -l eastus
注意
根據預設，API 中心會在免費定價層下建立。
注意
目前不支援在 VS Code 上建立 API 中心服務。 請使用 Azure CLI 或 Azure 入口網站來建立。
步驟 2：定義中繼資料屬性
API 中心會使用中繼資料屬性將 API 組織在您的詳細目錄中，並啟用篩選、搜尋等作業。
注意
請勿在中繼資料屬性標題/名稱中包含任何敏感性、機密或個人資訊。
Contoso 與其他許多組織一樣，希望其所有 API 都必須先通過核准才可供使用，並確實對所有 API 進行合規性檢閱。 該組織也有面向公眾的 API，以及專為內部使用而建置的 API。 為了在所有 API 間大規模強制執行這一點，我們新增了三個自訂中繼資料屬性：
- 字串類型的 API 核准者
- 預先定義選項類型的合規性檢閱
- 布林值類型的面向公眾
在左側功能表上，選取 [資產] > [中繼資料]> [+ 新增中繼資料]。
在 [詳細資料] 索引標籤上，輸入屬性的相關資訊。
a. 在 [標題] 中，輸入 API 核准者
b. 在 [描述] 中，輸入預設 API 核准者
c. 選取 [字串] 類型，然後選取 [下一步]
在 [指派] 索引標籤上，針對 API 選取 [必要]。 針對 [部署和環境] 選取 [選用]。 選取下一個
選取 [建立]
針對面向公眾屬性重複相同的步驟，如下圖所示。 針對類型，選取 [布林值]
在 [指派] 索引標籤上，針對 API 選取 [必要]。 針對 [部署和環境] 選取 [不適用]。 選取下一個
選取 [建立]
針對合規性檢閱屬性重複相同的步驟，如下圖所示。 針對類型，選取 [預先定義的選項]，然後新增 3 個選項：[未啟動]、[進行中] 和 [已完成]
在 [指派] 索引標籤上，針對 API 選取 [必要]。 針對 [部署和環境]，選取 [不適用]
選取下一個
此時，您的 API 會有 JSON 中繼資料結構描述可供檢視、編輯和下載。 若要檢視，請選取 [檢視中繼資料結構描述]，然後從下拉式清單中選取 [API]。
這會在右側開啟具有中繼資料詳細資料的強制回應，其中包含來自 API 中心的內建屬性，例如 LifecycleStage、Name、Description、TermsOfService 等等。 如果捲動至檔案底部，您會看到您在先前的步驟中新增的自訂中繼資料，如下所示。
注意
您可以隨時新增和編輯結構描述中的屬性，並立即將其套用至 API 中心的所有 API
執行下列命令以建立新的中繼資料結構描述，以設定：
- 中繼資料 [名稱] 為 api-approver
- [結構描述]，具有字串的屬性類型和 API Approver 的標題
- 針對 [API]，[指派] 為必要，而針對 [環境] 和 [部署] 為選擇性
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
對以下項目重複相同的步驟：
- 中繼資料 [名稱] 為 public-facing
- [結構描述]，具有布林值的屬性類型以及標題為 Public Facing
- 針對 [API]，[指派] 為必要，而針對 [環境] 和 [部署] 為選擇性
執行下列命令：
az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
最後，對以下項目重複相同的步驟：
- 中繼資料 [名稱] 為 compliance-review
- [結構描述]，具有字串的屬性類型及 [標題] 為 Compliance Review
- 針對 [API]，[指派] 為必要，而針對 [環境] 和 [部署] 為選擇性
執行下列命令：
az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'
您可以執行下列命令，以檢視 API 中心所有已定義中繼資料的清單。
az apic metadata list -g <resource-group-name> -n <api-center-name>
注意
您可以隨時新增和編輯結構描述中的屬性，並立即將其套用至 API 中心的所有 API
注意
目前在 VS Code 上不支援此動作。 請使用 Azure CLI 或 Azure 入口網站來建立。
步驟 3：將 API 新增至詳細目錄
Contoso 組織想要為其工程小組推薦技術會議，藉以提升其內部技能。 我們將新增具有演講者、研討會和主題的會議 API。
會議 API URL：https://bigconference.azurewebsites.net/
針對以下步驟，您可以從上述網站複製 OpenAPI 定義，並將其儲存為本機電腦上的 JSON 檔案。 或者，將 API 新增至庫存時，取代不同的 API 定義。
在入口網站中，瀏覽至您的 API 中心。
在左側功能表中，選取 [資產] > [API]> [+ 註冊 API]。
在 [註冊 API] 頁面中，新增 API 的下列必要資訊。 您會在頁面底部看到您在先前的步驟中定義的自訂 API 核准者、*面向公眾和合規性檢閱中繼資料屬性。
若要檢視已建立的 API，請在左側功能表上選取 [資產] > [API] > [會議 API]。
[概觀] 索引標籤提供 API 設定的檢視。 展開 [詳細資料] 以查看和編輯其他資訊，例如 API 版本和部署 (此時我們沒有任何部署)。
您通常需要為 API 版本新增 API 定義，API 中心支援文字規格格式，包括適用於 REST 的 OpenAPI 2 和 OpenAPI 3。
若要新增定義：
- 在左側功能表中，選取 [資產] > [API] > 選取您的 API (會議 API)。
- 展開 [詳細資料]，然後選取 [版本]。
- 選取您的版本 (v1)，然後展開 [詳細資料]。
- 在 [詳細資料] 底下，選取 [定義] > [新增定義]。
您可以使用 Visual Studio Code 的 Azure API 中心延伸模組，將 API 註冊到您的 API 執行個體中。
步驟 1：安裝延伸模組
步驟 2：開啟命令選擇區，按 'Ctrl + Shift + P'，然後輸入 API 中心：註冊 API
依照提示為您的 API 提供下列資訊：
| 註冊 API | 逐步 |
|---|---|
| 選取 API 中心服務 | 選取您的 API 中心執行個體 |
| API 標題 | 輸入 API 的名稱 (會議 API) |
| API 類型 | REST |
| API 版本標題 | 輸入 API 的版本名稱 (v1) |
| API 版本生命週期 | 從下拉式清單中選取生命週期 (開發) |
| API 定義標題 | 輸入定義的名稱 (會議 API 定義) |
| API 規格名稱 | 從下拉式清單中選取規格 (OpenAPI 2) |
| 選取要匯入的 API 定義檔 | 瀏覽並選取您儲存體中的定義檔 |
重新整理 API 中心延伸模組索引標籤，新建立的 API 會出現在各自的 APIC 執行個體/資源中。
使用下列命令建立新的 API；請傳入：
- 資源群組 -g 範例。 Contoso
- API 中心服務名稱 -n 範例。 contoso-api-center
- 標題 --title 範例。 會議 API
- API 識別碼 --api-id 範例。 conference-api
- 類型 --type Example。 REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
使用下列命令建立 API 版本；請傳入：
- 資源群組 -g 範例。 contoso
- API 中心服務名稱 -n 範例。 contoso-apis
- API 識別碼 --api-id 範例。 conference-api
- 標題 --title 範例。 v1.2.2
- 版本識別碼 --version-id 範例。 2024-07-03
- 生命週期階段 --lifecycle-stage 範例。 設計
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design
您也可以為 API 版本新增 API 定義，API 中心支援文字規格格式，包括適用於 REST 的 OpenAPI 2 和 OpenAPI 3。
若要新增定義，請使用下列命令；請傳入：
- 資源群組 -g 範例。 contoso
- API 中心服務名稱 -n 範例。 contoso-apis
- API 識別碼 --api-id 範例。 conference-api
- 版本識別碼 --version-id 範例。 2024-07-03
- 標題 --title 範例。 OpenAPI
- 定義識別碼 --definition-id 範例。 openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi
使用 az apic api definition import-specification 命令，從 URL 匯入 OpenAPI 定義檔。 範例: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples
az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'
步驟 4：新增部署和環境
環境
環境 (開發、測試、預備或實際執行) 代表部署 API 執行階段的位置。 Contoso 的 API 平台工程師在其 API 中心執行個體中定義兩個環境 – 測試和實際執行環境，用以管理及追蹤組織中的不同 API 執行階段。
若要建立環境：
在左側功能表上，選取 [資產] > [環境] > [+ 新增環境]。
新增下列資訊。
選取 建立。
針對實際執行環境重複相同的步驟。
若要建立環境，請執行下列 CLI 命令
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
針對實際執行環境重複相同的步驟
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
注意
目前在 VS Code 上不支援建立環境。 請針對此步驟使用 Azure CLI 或 Azure 入口網站選項。
部署
指定環境中的每個 API 執行階段都會獲得唯一的位置 (位址)，供使用者與 API 互動。 此位置稱為部署，單一 API 版本可以有兩個部署 -- 預備部署和實際執行部署。
Contoso 有一個 API (會議 API)，我們會將其與先前建立的環境產生關聯。
在入口網站中，瀏覽至您的 API 中心。
在左側功能表中選取 [API]，然後選取 API，例如會議 API。
在 [會議 API] 頁面上，展開 [詳細資料] > [部署] > [+ 新增部署]。
加入下列資訊：
a. 從 [環境] 欄位的下拉式清單中，選取 [Contoso 測試]。
b. 針對定義，按一下 [選取]，從下拉式清單中選擇 API 版本 v1，然後選取您先前新增的定義。 按一下 [選取]。
c. 成功新增定義後，請新增所選環境中的 API 專屬的基底執行階段 URL。
若要建立部署並將其與我們在上述步驟中建立的環境產生關聯，請執行下列 CLI 命令
az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'
注意
目前在 VS Code 上不支援建立部署。 請針對此步驟使用 Azure CLI 或 Azure 入口網站選項。