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

發行項
05/07/2024

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

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

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

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

注意

目前，基本 v2 和標準 v2 層不支援 API 要求的追蹤。

必要條件

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

重要

設定，就無法再啟用 API 管理要求追蹤要求中的 Ocp-Apim-Trace 標頭，並在回應中使用 Ocp-Apim-Trace-Location 標頭的值來擷取追蹤。
為了改善安全性，現在透過使用 API 管理 REST API 取得限時令牌，並將令牌傳遞至網關，以在個別 API 層級啟用追蹤。如需詳細資訊，請參閱本教學課程稍後的。
啟用追蹤時請小心，因為它可以在追蹤數據中公開敏感性資訊。請確定您已具備適當的安全性措施來保護追蹤數據。

追蹤入口網站中的呼叫

登入 Azure 入口網站，然後瀏覽至您的 API 管理執行個體。
選取 [API]。
選取 API 清單中的 [Demo Conference API]。
選取 [測試] 索引標籤。
選取 GetSpeakers 作業。
(選擇性) 選取「眼睛」圖示，檢查要求中使用的 Ocp-Apim-Subscription-Key 標頭的值。

提示

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

檢閱追蹤資訊

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

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

啟用 API 的追蹤

您可以使用、具有 curlREST 用戶端延伸模組的 Visual Studio Code 或用戶端應用程式，在向 API 管理提出要求時，啟用 API 的追蹤。

使用呼叫 API 管理 REST API 來啟用下列步驟的追蹤。

注意

下列步驟需要 API 管理 REST API 版本 2023-05-01-preview 或更新版本。您必須在 API 管理實例上獲指派參與者或更高角色，才能呼叫 REST 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": "<API resource ID>",
    "purposes: ["tracing"]
}
```
令牌認證會在響應中傳回，如下所示：
```
{
      "token": "aid=api-name&p=tracing&ex=......."
}
```

若要啟用對 API 管理閘道的要求追蹤，請在標頭中Apim-Debug-Authorization傳送令牌值。例如，若要追蹤示範會議 API 的呼叫，請使用類似下列的呼叫：

curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."

根據令牌而定，回應會包含不同的標頭：
- 如果令牌有效，回應會包含 Apim-Trace-Id 其值為追蹤標識符的標頭。
- 如果令牌已過期，回應會包含 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": "<trace ID>"
}
```
回應本文包含先前對閘道之 API 要求的追蹤數據。追蹤與追蹤類似，您可以在入口網站的測試控制台中追蹤呼叫來查看追蹤。

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

下一步

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

追蹤範例呼叫
檢閱要求處理步驟
啟用 API 的追蹤

前進到下一個教學課程：

使用修訂

Share via

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

必要條件

追蹤入口網站中的呼叫

檢閱追蹤資訊

啟用 API 的追蹤

下一步

其他資源