教學課程：使用適用於 Visual Studio Code 的 Azure API 管理延伸模組來匯入和管理 API

  • 發行項

適用於：取用 |開發人員 |基本 |標準 |進階版

在本教學課程中，您將瞭解如何使用適用於 Visual Studio Code 的 API 管理延伸模組，在 API 管理中進行一般作業。 使用熟悉的 Visual Studio Code 環境來匯入、更新、測試及管理 API。

您將學習如何：

  • 將 API 匯入至 API 管理
  • 編輯 API
  • 套用 API 管理原則
  • 測試 API

API 管理擴充功能中 API 的螢幕快照。

如需更多 API 管理功能的簡介，請使用 Azure 入口網站查看 API 管理教學課程。

必要條件

匯入 API

下列範例會將 JSON 格式的 OpenAPI 規格匯入至 API 管理。 Microsoft 會提供在此範例中使用的後端 API，並將其裝載在 Azure 上 (https://conferenceapi.azurewebsites.net)。

  1. 在 Visual Studio Code 活動列上，選取 Azure 圖示。
  2. 在 Explorer 窗格中展開您建立的 API 管理執行個體。
  3. 以滑鼠右鍵按一下 [API]，然後選取 [從 OpenAPI 連線匯入]。
  4. 當系統提示時，輸入下列值：

    1. JSON 格式的 OpenAPI 連結內容。 針對此範例：https://conferenceapi.azurewebsites.net?format=json。

      此檔案會指定實作範例 API 的後端服務，在此案例中為 https://conferenceapi.azurewebsites.net。 API 管理則將要求轉送至此 Web 服務。

    2. API 管理執行個體中唯一的 API 名稱，例如 demo-conference-api。 名稱只能包含字母、數字和連字號。 第一個字元和最後一個字元必須是字母或數字。 呼叫 API 的路徑會使用此名稱。

成功匯入 API 之後，會出現在 Explorer 窗格中，而可用的 API 作業會出現在作業節點底下。

[總管] 窗格中已匯入 API 的螢幕快照。

編輯 API

您可以在 Visual Studio Code 中編輯 API。 例如，在編輯器視窗中編輯 API 的 Resource Manager JSON 描述，以移除用來存取 API 的 HTTP 通訊協定。

在 Visual Studio Code 中編輯 JSON 描述的螢幕快照。

若要編輯 OpenAPI 格式，請在瀏覽器窗格中的 API 名稱上按一下滑鼠右鍵，然後選取 [編輯 OpenAPI]。 進行所有變更，然後選取 [檔案]>[儲存]。

將原則新增至 API

API 管理提供原則給您為 API 設定。 原則是一組陳述式。 這些陳述式在 API 的要求或回應上循序執行。 原則可以是全域，套用至 API 管理執行個體中的所有 API，也可以是產品、API 或 API 作業專用。

本節說明如何將常用的輸出原則套用至 API，以轉換 API 回應。 此範例中的原則會變更回應標頭，並隱藏顯示在回應主體中的原始後端 URL。

  1. 在 Explorer 窗格中，選取您匯入的 demo-conference-api 底下的 [原則]。 原則檔案隨即在編輯器視窗中開啟。 此檔案會針對 API 中的所有作業設定原則。

  2. 以 <outbound> 元素中的以下內容更新檔案：

    [...]
<outbound>
    <set-header name="Custom" exists-action="override">
        <value>"My custom value"</value>
    </set-header>
    <set-header name="X-Powered-By" exists-action="delete" />
    <redirect-content-urls />
    <base />
</outbound>
[...]
    • 第一個 set-header 原則會新增自訂回應標頭以供示範之用。
    • 第二個 set-header 原則會刪除 X-Powered-By 標頭 (如果有)。 此標頭可以顯示 API 後端中使用的應用程式架構，而發行者通常會加以移除。
    • redirect-content-urls 原則會重寫 (遮罩) 回應本文中的連結，使其經由 API 管理閘道指向同等的連結。

  3. 儲存檔案。 如果出現提示，請選取 [上傳]，將檔案上傳到雲端。

測試 API

若要測試 API，請取得訂用帳戶金鑰，然後向 API 管理閘道提出要求。

取得訂用帳戶金鑰

您需要 API 管理執行個體的訂用帳戶金鑰，才能測試匯入的 API 和套用的原則。

  1. 在 Explorer 窗格中，以滑鼠右鍵按一下您的 API 管理執行個體名稱。

  2. 選取 [複製訂用帳戶金鑰]。 此金鑰適用於您建立 API 管理執行個體時所建立的全部內建存取訂用帳戶。

    Visual Studio Code 中複製訂用帳戶密鑰命令的螢幕快照。

    警告

    所有存取訂用帳戶可供存取此 API 管理執行個體中所有的 API，此訂用帳戶僅應由授權使用者使用。 請勿將將它用於常式 API 存取，也不要將全部存取金鑰內嵌在用戶端應用程式中。

測試 API 作業

  1. 在 Explorer 窗格中，展開您匯入的 demo-conference-api 下的作業。
  2. 選取 GetSpeakers 之類的作業，然後以滑鼠右鍵按一下作業來選取 [測試作業]。
  3. 在編輯器視窗的Ocp-Apim-Subscription-Key旁，將 {{SubscriptionKey}} 取代為您複製的訂用帳戶金鑰。
  4. 在 Ocp-Apim-Trace 旁邊，輸入 false。 此設定會停用要求追蹤。
  5. 選取 [傳送要求]。

從 Visual Studio Code 傳送 API 要求的螢幕快照。

要求成功時，後端會回應 200 OK 與部分資料。

Visual Studio Code 中 API 測試回應的螢幕快照。

在回應中，請注意下列詳細資料：

  • 自訂 標頭會新增至回應。
  • X-Powered-By 標頭不會出現在回應中。
  • API 後端的 URL 會重新導向至 API 管理閘道，在此案例中為 https://apim-hello-world.azure-api.net/demo-conference-api。

追蹤要求處理

您可以選擇取得詳細的要求追蹤資訊，以協助您對API進行偵錯和疑難排解。

若要追蹤要求處理，必須先為用來偵錯 API 的訂用帳戶啟用 [允許追蹤] 設定。 如需使用入口網站啟用此設定的步驟，請參閱確認允許追蹤設定。 若要限制敏感性資訊的意外洩漏，僅允許追蹤 1 小時。

允許使用您的訂用帳戶進行追蹤之後，請遵循下列步驟：

  1. 在 Explorer 窗格中，展開您匯入的 demo-conference-api 下的作業。
  2. 選取 GetSpeakers 之類的作業，然後以滑鼠右鍵按一下作業來選取 [測試作業]。
  3. 在編輯器視窗的Ocp-Apim-Subscription-Key旁，將 {{SubscriptionKey}} 取代為您要使用的訂用帳戶金鑰。
  4. 在 Ocp-Apim-Trace 旁邊，輸入 true。 此設定可啟用此要求的追蹤。
  5. 選取 [傳送要求]。

要求成功時，後端回應會包含 Ocp-APIM-Trace-Location 標頭。

Visual Studio Code 中 API 測試響應中追蹤位置的螢幕快照。

選取 Ocp-APIM-Trace-Location 旁邊的連結，以查看輸入、後端和輸出追蹤資訊。 追蹤資訊有助於查明提出要求之後何處發生問題。

提示

測試 API 作業時，API 管理延伸模組允許選擇性的 原則偵錯 (僅可在開發人員服務層級中使用)。

清除資源

如果不再需要，請移除 API 管理執行個體，方法是以滑鼠右鍵按一下，然後選取 [在入口網站中開啟] 以 [刪除 API 管理服務] 及其資源群組。

或者，您也可以選取 [刪除 API 管理]，從而只刪除 API 管理執行個體 (此作業不會刪除其資源群組)。

從 Visual Studio Code 刪除 API 管理 實例的螢幕快照。

相關內容

本教學課程介紹「適用於 Visual Studio Code 的 API 管理延伸模組」的幾項功能。 您可以使用這些功能來匯入和管理 API。 您已了解如何︰

  • 將 API 匯入至 API 管理
  • 編輯 API
  • 套用 API 管理原則
  • 測試 API

API 管理延伸模組提供更多功能來處理 API。 例如偵錯原則 (可在開發人員服務層級中使用) 或建立和管理具名值。