共用方式為

將適用於能源的 Azure 資料管理員 API Microsoft發佈至安全的 API 閘道

  • 發行項

Azure API 管理 可作為用戶端應用程式與後端 API 之間的重要媒介。 藉由隱藏技術詳細數據，讓組織能夠控制 API 安全性，讓用戶端更容易存取服務。

透過 Azure API 管理 發佈適用於能源的 Azure Data Manager API，即可使用適用於私人流量的 Azure Data Manager for Energy Private Link 功能，並完全移除您實例的直接公用存取權。

本文說明如何設定 Azure API 管理 來保護適用於能源的 Azure 數據管理員 API。

必要條件

您需要下列元件、工具和資訊，才能完成本逐步解說：

  • 有兩個可用子網的虛擬網路，一個用於適用於能源私人端點的 Azure Data Manager，另一個用於 Azure API 管理 虛擬網路插入。

  • 已設定 私人連結 部署至子網的 Azure Data Manager for Energy。

  • Azure API 管理 使用虛擬網路插入布建並部署至虛擬網路。 選取 [外部模式]，或參閱 [內部模式] 的 [其他選項] 區段。

  • Visual Studio Code 之類的程式碼編輯器，用於修改所發行每個 API 的 Azure Data Manager for Energy OpenAPI 規格。

  • 從 adme-samples GitHub 存放庫下載適用於能源的 Azure Data Manager OpenAPI 規格。 流覽至 rest-apis 目錄，然後為您的應用程式選取適當的版本。

  • 從布建時間使用的 Azure Data Manager for Energy 應用程式的應用程式註冊中，記下 租使用者識別碼 和 用戶端標識碼：

    應用程式註冊詳細數據的螢幕快照。

準備 API 管理 實例

使用下列步驟，對 Azure API 管理 實例進行組態變更：

  1. 從 [所有資源] 窗格中，選擇用於本逐步解說的 Azure API 管理 實例。

  2. 從 API 設定群組中選擇 [產品設定] 頁面，以流覽至 [產品設定] 頁面：

    API 管理 實例上 [產品] 索引標籤的螢幕快照。

  3. 在 [產品] 頁面上，選取 [新增] 按鈕 以建立新的產品。 Azure API 管理 產品可讓您建立一組鬆散結合的 API，以共同控管和管理。 我們會為適用於能源的 Azure 數據管理員 API 建立產品。

  4. 在 [新增產品] 頁面上，輸入下表所述的值來建立產品。

    API 管理 實例上 [新增產品] 頁面的螢幕快照。

    設定 值
    顯示名稱 「適用於能源產品的 Azure 數據管理員」
    識別碼 “adme-product”
    描述 輸入描述，向開發人員指出我們要分組的 API
    已發行 核取此方塊以發佈我們建立的產品
    需要訂用帳戶 核取此方塊以提供 API 的基本授權
    需要核准 選擇性地選取您是否希望系統管理員檢閱並接受或拒絕此產品的訂用帳戶嘗試。 如果未選取，系統會自動核准訂用帳戶嘗試。
    訂閱計數限制 可選擇限制多個同時訂閱的總數。
    法律條款 選擇性地定義訂閱者必須接受才能使用產品的產品使用規定。
    API 我們可以忽略這項功能。 本文稍後會建立 API 的關聯

  5. 選取 [建立] 以建立新產品。

  6. 產品建立完成後，入口網站會返回 [產品] 頁面。 選取新建立的產品 Azure Data Manager for Energy Product ，以移至 [產品資源] 頁面。 從 [設定] 功能選取 [ 原則 設定] 功能表項。

    API 管理 實例上產品原則設定頁面的螢幕快照。

  7. 在 [輸入處理] 窗格中，選取 </> 圖示，可讓您修改產品的原則。 您可以新增三組原則來增強解決方案的安全性：

    • 驗證 Entra ID Token ，以確保 API 閘道攔截到未經驗證的要求
    • 配額 和 速率限制 ，以控制要求率和傳輸的總要求/數據
    • 設定標頭 以移除後端 API 所傳回的標頭，這可能會向潛在的不良動作項目顯示敏感性詳細數據

  8. 將下列 validate-azure-ad-token 原則新增至輸入卷標內和基底標記下方的組態。 請務必使用必要條件中記下Microsoft Entra ID 應用程式詳細數據來更新範本。

    <validate-azure-ad-token tenant-id="INSERT_TENANT_ID">
    <client-application-ids>
        <application-id>INSERT_APP_ID</application-id>
    </client-application-ids>
</validate-azure-ad-token>

  9. 在 validate-azure-ad-token 原則下方，新增下列 配額 和 速率限制 原則。 視您的取用者情況更新原則組態值。

    <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
<quota calls="10000" bandwidth="40000" renewal-period="3600" />

  10. 在原則編輯器的輸出區段和基底卷標底下，新增下列 set-header 原則。

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
<set-header name="x-internal-uri-pattern" exists-action="delete" />

  11. 選取儲存認可您的變更。

    完整原則文件的螢幕快照。

  12. 流覽回 Azure 入口網站中的 API 管理 資源。 選取 [ 後端] 功能表項，然後選取 [ + 新增 ] 按鈕。

    [後端] 頁面的螢幕快照。

  13. 在 [ 後端 強制回應] 上，輸入下表所述的值來建立後端。

    設定 值
    名稱 “adme-backend”
    描述 輸入描述，向開發人員指出此後端與適用於能源的 Azure 數據管理員 API 相關
    類型 自訂 URL
    執行階段 URL 輸入您的 Azure Data Manager for Energy URI _ex。 https://INSERT_ADME_NAME.energy.azure.com/
    驗證憑證鏈結 已選取
    驗證憑證名稱 已選取

    後端強制回應的螢幕快照。

  14. 選取 [建立] 以建立後端。 當我們發佈 API 時，下一節將會使用這個新建立的後端。

匯入適用於能源的 Azure 資料管理員 API

使用下列步驟，將適用於能源的 Azure Data Manager API 匯入、設定及發佈至 Azure API 管理 閘道：

  1. 流覽回上一節中使用的 Azure API 管理 實例。

  2. 從功能表中選取 [API] 選單項，然後選取 [ + 新增 API] 按鈕。

  3. 選取 [從定義建立] 標題下的 [OpenAPI]。

    OpenAPI 匯入畫面的螢幕快照。

  4. 在 [ 從 OpenAPI 規格 建立] 模式視窗中，選取 [ 完整 ] 切換。

  5. 找出您在必要條件中下載的 OpenAPI 規格，並使用您選擇的程式碼編輯器開啟 架構 規格。 搜尋 「server」 一詞，並記下檔案中的伺服器 URL，例如 /api/schema-service/v1/。

  6. 選取 [ 選取檔案 ]，然後選取 [架構 API 規格]。 上傳完成時，強制響應視窗會從規格載入一些值。

  7. 針對其他欄位，請輸入下表所述的值：

    設定 值
    在作業範本中包含必要的查詢參數 已選取
    Display name 輸入適用於應用程式開發人員 的顯示名稱，例如適用於能源架構服務的 Azure Data Manager
    名稱 API 管理 建議一個烤肉串大小寫的名稱。 您可以選擇性地變更名稱，但實例必須是唯一的
    描述 如果 OpenAPI 規格會自動填入描述，則 OpenAPI 規格可能會定義描述。 或者，根據您的使用案例更新描述。
    URL 配置 選取 [兩者]
    API URL 尾碼 輸入所有適用於能源 API 的 Azure 數據管理員後綴（例如 adme）。 然後輸入步驟 5 中的伺服器 URL。 最終值看起來應該像 /adme/api/schema-service/v1/。 後綴可讓我們符合通常直接連線到適用於能源 API 的 Azure Data Manager 的現有用戶端和軟體開發工具包
    標籤 選擇性地輸入標籤
    產品 選取上一節中建立的「適用於能源的 Azure 數據管理員」產品

    重要

    驗證 API URL 後綴，這是發佈適用於能源的 Azure 數據管理員 API 時發生錯誤的常見原因

  8. 選取 [建立] 以建立 API 外觀。

    [從 OpenAPI 建立] 規格畫面的螢幕快照。

  9. 從 API 清單中選取新建立的架構 API 外觀，然後選取作業清單中的 [所有作業]。 在 [ 輸入處理 ] 窗格中，選取 </> 圖示以編輯原則檔。

    API 原則畫面的螢幕快照。

  10. 若要設定 API，請新增兩組原則：

    • 將後端服務 設定為將要求路由傳送至適用於能源的 Azure Data Manager 實例
    • 重寫 URI 以移除 adme 前置詞，並將要求建置至後端 API。 此原則語句會使用 原則表達式 ，以動態方式將目前作業 URL 範本的值新增至我們的伺服器 URL。

  11. 記下步驟 5 中的伺服器 URL。 在 基底 標記下方的 輸入 區段中，插入下列兩個原則語句。

    <set-backend-service backend-id="adme-backend" />

    <!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 -->
<rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />

  12. 選取儲存認可您的變更。

  13. 從作業清單中選取 GET 版本資訊 作業，以測試 API。 然後選取 [測試] 索引標籤，以流覽至 Azure API 管理 測試控制台。

  14. 輸入下表所述的值。 為您的 Azure Data Manager for Energy 產生驗證令牌。 選取 [ 傳送 ] 以測試 API。

    設定 值
    data-partition-id 適用於能源的 Azure Data Manager 實例的數據分割標識碼
    Products 選取稍早建立的 Azure Data Manager for Energy 產品
    授權 「持有人」和您產生的驗證令牌

    從 API 測試控制台建立的螢幕快照。

  15. 如果 API 已正確設定，您應該會看到 類似螢幕快照的 HTTP 200 - 確定 回應。 如果沒有，請檢查 [疑難解答] 區段。

  16. 針對每個適用於能源 API 的 Azure 數據管理員和相關聯的規格重複上述步驟。

疑難排解

在透過 Azure API 管理 測試 API 期間，如果您遇到錯誤，通常會指向設定問題。 根據錯誤，檢閱潛在的解決步驟。

代碼 錯誤訊息 詳細資料
HTTP 401 Unauthorized Invalid Azure AD JWT 檢查以確定您的 Azure Data Manager for Energy 實例具有Microsoft Entra ID 租使用者和用戶端應用程式的有效驗證標頭。
HTTP 401 Unauthorized Azure AD JWT not present 檢查以確定驗證標頭已新增至您的測試要求。
HTTP 404 Not Found 此錯誤通常表示對後端 API 的要求是對錯誤的 URL 進行。 在 API 管理 追蹤您的 API 要求，以瞭解後端要求所產生的 URL，並確保其有效。 如果沒有，請仔細檢查 URL 重寫 原則或 後端。
HTTP 500 Internal Server Error Internal server error 此錯誤通常反映對後端 API 提出要求的問題。 通常，在此案例中，問題與域名服務 （DNS） 相關。 請檢查以確定虛擬網路中已設定私人 DNS 區域，或您的自定義 DNS 解析具有適當的轉寄站。 追蹤 API 管理 中的 API 要求，以瞭解後端要求已發出，以及嘗試提出要求時所報告的錯誤 API 管理。

其他考量

API 管理 內部虛擬網路模式

內部模式會完全隔離 Azure API 管理，而不是透過公用 IP 位址公開端點。 在此設定中，組織可以確保所有適用於能源的 Azure Data Manager 都是內部的。 由於適用於能源的 Azure Data Manager 是與合作夥伴和客戶合作的共同作業解決方案，因此此案例可能不如實有用。

具有 Web 應用程式防火牆的應用程式閘道

許多組織選擇套用安全的反向 Proxy 機制，將內部模式 Azure API 管理 實例公開給外部合作夥伴和客戶，而不是單獨使用內部虛擬網路模式。 內部模式實例會與必須通過 Proxy 的嚴格控制輸入保持完全隔離。

Azure 應用程式閘道 是作為反向 Proxy 使用的常見服務。 Azure 應用程式閘道也有 Web 應用程式防火牆 （WAF） 功能，可主動偵測應用程式與 API 中弱點的潛在攻擊。

使用自定義網域設定 Azure API 管理

此架構的另一個常見功能是將自定義網域套用至 API。 雖然 Azure Data Manager for Energy 不支援此功能，但您可以改為在 Azure API 管理 上設定自定義網域。

網域的憑證是必要條件。 不過，Azure API 管理 支援為您的自定義網域建立免費的受控憑證。

相關內容