從 API 管理 實體同步處理 API （預覽）

本文說明如何整合 API 管理 實例，讓實例的 API 在 API 中心清查中持續保持最新狀態。

關於整合 API 管理 實例

雖然您可以使用 Azure CLI 視需要將 API 從 Azure API 管理 匯入至 Azure API 中心，但整合 API 管理 實例可啟用持續同步處理，讓 API 清查保持在最新狀態。 Azure API 中心也可以同步處理來自來源的 API，包括 Amazon API 閘道。

當您將 API 管理 實例整合為 API 來源時，會發生下列情況：

1. 所有 API，以及選擇性的 API 定義（規格），都會從 API 管理 實例新增至 API 中心清查。
2. 您可以在 API 中心設定 Azure API 管理 類型的環境。
3. 系統會針對每個從 API 管理 同步處理的 API 定義建立相關聯的部署。

每當現有的 API 設定變更時，API 管理 API 會自動同步處理至 API 中心（例如，新增版本）、建立新的 API 或刪除 API。 此同步處理是從 API 管理 到 Azure API 中心的單向，這表示 API 中心中的 API 更新不會同步處理回 API 管理 實例。

注意

• Azure API 管理 整合目前為預覽狀態。
• 整合式 API 管理 實例數目有限制（API 來源）。
• API 管理 中的 API 更新通常會在幾分鐘內同步處理至您的 API 中心，但同步處理最多可能需要 24 小時。
• 如果您選取在整合期間包含 API 中心的選項，API 定義也會同步處理至 API 中心。

從 API 管理 同步處理的實體

您可以將元資料屬性和檔新增或更新至 API 中心的同步處理 API，以協助專案關係人探索、瞭解及取用 API。 深入瞭解 Azure API 中心內 建和自定義元數據屬性。

下表顯示可在 Azure API 中心修改的實體屬性，以及根據 API 來源中的值所設定的屬性。

Entity	可在 API 中心設定的屬性	整合式 API 來源中決定的屬性
API	摘要 lifecycleStage termsOfService license (授權) externalDocumentation customProperties	title description 種類
API 版本	lifecycleStage	title 定義（如果已同步處理）
Environment	title description kind server.managementPortalUri 上架 customProperties	server.type
部署	title description 伺服器 state customProperties	server.runtimeUri

注意

同步處理至 Azure API 中心之實體的資源和系統識別碼會自動產生，且無法變更。

必要條件

• Azure 訂用帳戶中的 API 中心。 如果您尚未建立，請參閱快速入門：建立您的 API 中心。

• 相同或不同訂用帳戶中的 Azure API 管理 實例。 實例必須位於相同的目錄中。

• 對於 Azure CLI：

  • 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

    

  • 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱〈如何在 Docker 容器中執行 Azure CLI〉。

    • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱使用 Azure CLI 登入。

    • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能詳細資訊，請參閱使用 Azure CLI 擴充功能。

    • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

  注意

  az apic 命令需要 apic-extension Azure CLI 延伸模組。 如果您尚未使用 az apic 命令，則可以在執行第一個 az apic 命令時動態安裝延伸模組，也可以手動安裝延伸模組。 深入了解 Azure CLI 延伸模組。

  如需 apic-extension 中的最新變更和更新，請參閱版本資訊。 某些功能可能需要預覽或特定版本的擴充功能。

  注意

  本文中的 Azure CLI 命令範例可在 PowerShell 或 Bash 殼層中執行。 若因變數語法不同而有需要，可參考為兩個殼層提供的個別命令範例。

在您的 API 中心啟用受控識別

在此案例中，您的 API 中心會使用 受控識別 來存取 Azure 資源。 根據您的需求，啟用系統指派或一或多個使用者指派的受控識別。

下列範例示範如何使用 Azure 入口網站 或 Azure CLI 來啟用系統指派的受控識別。 概括而言，設定步驟與使用者指派的受控識別類似。

入口網站

1. 在入口網站中，瀏覽至您的 API 中心。
2. 在 [安全性] 下的左側功能表中，選取 [受控識別]。
3. 選取 [系統指派]，然後將狀態設定為 [開啟]。
4. 選取 [儲存]。

Azure CLI

使用下列 [az apic service update] 命令，在 API 中心設定系統指派的身分識別。 替換 API 中心和資源群組的名稱：

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

為受控識別指派 API 管理服務讀者角色

若要允許匯入 API，請為 API 中心的受控識別指派 API 管理執行個體中的 API 管理服務讀者角色。 您可以使用入口網站或 Azure CLI。

入口網站

1. 在入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表中，選取 [存取控制 (IAM)]。
3. 選取 [+ 新增角色指派]。
4. 在 [新增角色指派] 窗格上設定值，如下所示：
   1. 在 [角色] 索引標籤上，選取 [API 管理 服務讀取器]。
   2. 在 [成員] 索引標籤上的 [指派存取權的對象] 中 - 選取 [受控識別]>[+ 選取成員]。
   3. 在 [ 選取受控識別 ] 頁面上，選取您在上一節中新增之 API 中心的系統指派受控識別。 按一下 [選取]。
   4. 選取檢閱+指派。

Azure CLI

1. 取得身分識別的主體識別碼。 針對系統指派身分識別，請使用 [az apic show] 命令。

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. 使用 az apim show 命令，取得 API 管理執行個體的資源識別碼。

   #! /bin/bash
   apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. 使用 az role assignment create 命令，為受控識別指派 API 管理執行個體中的 API 管理服務讀者角色。

   #! /bin/bash
   scope="${apimID:1}"
   
   az role assignment create \
       --role "API Management Service Reader Role" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "API Management Service Reader Role" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

整合 API 管理 實例

您可以使用入口網站或 Azure CLI 來整合 API 管理 實例。

入口網站

1. 在入口網站中，瀏覽至您的 API 中心。
2. 在 [資產] 底下，選取 [環境]。
3. 選取 [鏈接][預覽]>+[建立連結]。
4. 在 [链接您的 Azure API 管理 服務] 頁面中：
   1. 選取您要整合的訂用帳戶、資源群組和 Azure API 管理 服務。
   2. 在 [ 鏈接詳細數據] 中，輸入標識符。
   3. 在 [環境詳細數據] 中，輸入 環境標題 （名稱）、 環境類型和選擇性 [描述]。
   4. 在 API 詳細資料中：
      1. 選取 已同步 API 的生命週期 。 （您可以在 API 中心新增 API 之後更新此值。
      2. 選擇性地選取是否要包含與同步 API 的 API 定義。
5. 選取 建立。

Azure CLI

執行 az apic integration create apim 命令，將 API 管理 實例整合到您的 API 中心。

• 提供資源群組、API 中心和整合的名稱。

• 如果 API 管理 實例和 API 中心位於相同的資源群組中，您可以提供 API 管理 實例名稱做為 的值azure-apim;否則，請提供 Azure 資源識別碼。

az apic integration create apim \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <apim-integration-name> \
    --azure-apim <apim-instance-name>

環境會新增至 API 中心。 API 管理 API 會匯入至 API 中心清查。

刪除整合

雖然 API 來源已整合，但您無法從 API 中心刪除已同步處理的 API。 如果您需要，您可以刪除整合。 當您移除整合時：

• 系統會刪除 API 中心清查中同步處理的 API
• 刪除與 API 來源相關聯的環境和部署

您可以使用入口網站或 Azure CLI 刪除整合。

入口網站

1. 在入口網站中，瀏覽至您的 API 中心。
2. 在 [資產] 底下，選取 [環境>鏈接][預覽]。
3. 選取連結，然後選取 [ 刪除 ] （垃圾桶圖示）。

Azure CLI

執行 az apic integration delete （preview） 命令來刪除整合。 提供資源群組、API 中心和整合的名稱。

az apic integration delete \
    --resource-group <resource-group-name> \
    --service-name <api-center-name> \
    --integration-name <integration-name> \

相關內容

• 使用 Azure CLI 命令管理 API 詳細目錄
• 將 API 從 API 管理 匯入至 Azure API 中心
• Azure API 管理文件