教學課程：使用要求追蹤對 API 進行偵錯

發行項
11/05/2024

適用於：所有 APIM 層

本教學課程說明如何在 Azure API 管理中檢查 (追蹤) 要求處理。追蹤可協助您針對 API 進行偵錯和疑難排解。

在本教學課程中，您會了解如何：

在測試主控台中追蹤範例呼叫
檢閱要求處理步驟
啟用 API 的追蹤

必要條件

了解 Azure API 管理術語。
完成下列快速入門：建立 Azure API 管理執行個體。
請完成下列教學課程：匯入和發佈您的第一個 API。

重要

API 管理不再支援追蹤的訂用帳戶或Ocp-Apim-Trace 標頭。
若要改善 API 安全性，您現在可以在個別 API 層級啟用追蹤，方法是使用 API 管理 REST API 取得限時令牌，並將令牌傳遞至網關。如需詳細資料，請參閱啟用 API 的追蹤 (部分機器翻譯)。
啟用追蹤時請小心，因為敏感性資訊可能會在追蹤資料中公開。請確定您已採用適當的安全性措施來保護追蹤資料。

追蹤入口網站中的呼叫

請遵循下列步驟，在入口網站的測試控制台中追蹤 API 要求。此範例假設您在上一個教學課程中匯入範例 API。您可以使用您匯入的不同 API，遵循類似的步驟。

登入 Azure 入口網站，然後瀏覽至您的 API 管理執行個體。
選取 [API>API]。
從您的 API 清單中選取 [ 寵物存放區 API ]。
選取 [測試] 索引標籤。
選取 [ 依標識符 尋找寵物] 作業。
在 petId Query 參數中，輸入 1。
(選擇性) 選取「眼睛」圖示，檢查要求中使用的 Ocp-Apim-Subscription-Key 標頭的值。

提示

您可以在入口網站中擷取另一個訂用帳戶的金鑰，以覆寫 Ocp-Apim-Subscription-Key 的值。選取 [訂用帳戶]，然後開啟另一個訂用帳戶的操作功能表 (...)。選取 [顯示/隱藏金鑰]，並複製其中一個金鑰。您也可以視需要重新產生金鑰。然後，在測試主控台中選取 [+ 新增標頭]，以新增具有新金鑰值的 Ocp-Apim-Subscription-Key 標頭。
選取 [追蹤]。

檢閱追蹤資訊

在呼叫完成後，移至 [HTTP 回應] 中的 [追蹤] 索引標籤。
選取下列任一連結，以跳至詳細的追蹤資訊：輸入、後端、輸出、發生錯誤時。
- 輸入 - 顯示從呼叫者接收到的原始要求 API 管理，以及套用至要求的原則。例如，如果您在教學課程：轉換和保護 API 中新增原則，它們會出現在這裡。
- 後端 - 顯示 API 管理傳送至 API 後端的要求及其接收的回應。
- 輸出 - 顯示回應在傳回至呼叫者之前套用的所有原則。
- 發生錯誤時 - 顯示在處理要求期間發生的錯誤，以及套用至錯誤的原則。
提示

每個步驟也會顯示 API 管理收到要求後耗用的時間。

啟用 API 的追蹤

使用時curl，需要執行下列高階步驟，才能啟用對 API 管理要求的追蹤、使用 REST 用戶端延伸模組的 REST 用戶端，或用戶端應用程式等 REST 用戶端。目前必須使用 API 管理 REST API 來遵循這些步驟：

取得追蹤的令牌認證。
將要求標頭中的Apim-Debug-Authorization令牌值新增至 API 管理閘道。
取得回應標頭中的 Apim-Trace-Id 追蹤標識碼。
擷取對應至追蹤標識碼的追蹤。

詳細步驟如下。

注意

這些步驟需要 API 管理 REST API 版本 2023-05-01-preview 或更新版本。您必須在 APIM 執行個體上獲得參與者或更高角色的指派，才能呼叫 REST API。
如需向 REST API 驗證的相關信息，請參閱 Azure REST API 參考。

取得令牌認證 - 呼叫 API 管理閘道的清單偵錯認證 API。在 URI 中，輸入雲端中實例受控閘道的「受控」，或自我裝載閘道的閘道標識碼。例如，若要取得實例受控網關的追蹤認證，請使用類似下列的要求：
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
在要求本文中，傳遞您想要追蹤之 API 的完整資源識別碼，並將 purposes 指定為 tracing。根據預設，回應中傳回的權杖認證會在 1 小時後過期，但您可以在承載中指定不同的值。例如：
```
{
    "credentialsExpireAfter": PT1H,
    "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
    "purposes": ["tracing"]
}
```
權杖認證會在回應中傳回，如下所示：
```
{
      "token": "aid=api-name&......."
}
```
在要求標頭中新增令牌值 - 若要對 API 管理閘道啟用要求的追蹤，請在標頭中Apim-Debug-Authorization傳送令牌值。例如，若要追蹤您在上一個教學課程中匯入之 Petstore API 的呼叫，您可以使用類似下列的要求：
```
curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."
```
根據令牌，回應包含下列其中一個標頭：
- 如果令牌有效，回應會包含 Apim-Trace-Id 標頭，其值為追蹤標識符，如下所示：
```
Apim-Trace-Id: 0123456789abcdef....
```
- 若權杖已過期，回應會包含 Apim-Debug-Authorization-Expired 標頭，其中包含到期日的相關資訊。
- 如果為不同的 API 取得令牌，回應會包含 Apim-Debug-Authorization-WrongAPI 具有錯誤訊息的標頭。
擷取追蹤 - 將上一個步驟中取得的追蹤標識碼傳遞至閘道的清單追蹤 API。例如，若要擷取受控網關的追蹤，請使用類似下列的要求：
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
在要求本文中，傳遞在上一個步驟中取得的追蹤識別碼。
```
{
    "traceId": "0123456789abcdef...."
}
```
回應本文包含上一個對閘道之 API 要求的追蹤資料。該追蹤類似於您在入口網站測試主控台中追蹤呼叫所能看到的追蹤。

如需自訂追蹤資訊的相關資訊，請參閱追蹤原則。

下一步

在本教學課程中，您已了解如何：

在測試主控台中追蹤範例呼叫
檢閱要求處理步驟
啟用 API 的追蹤

前進到下一個教學課程：

使用修訂

共用方式為

教學課程：使用要求追蹤對 API 進行偵錯

必要條件

追蹤入口網站中的呼叫

檢閱追蹤資訊

啟用 API 的追蹤

下一步

意見反應

其他資源