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

發行項
06/27/2024

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

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

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

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

注意

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

必要條件

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

重要

使用要求中的 Ocp-Apim-Trace 標頭以及使用 Ocp-Apim-Trace-Location 回應標頭值進行的 APIM 要求追蹤功能，即將遭到取代。
為了改善安全性，您現在可以在個別 API 層級啟用追蹤，方法是使用 APIM 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 的追蹤

您可以在使用 curl、REST 用戶端 (例如具有 REST Client 延伸模組的 Visual Studio Code)，或用戶端應用程式對 APIM 提出要求時，啟用 API 的追蹤。

透過下列步驟，使用對 APIM REST API 的呼叫來啟用追蹤。

注意

下列步驟需要 APIM REST API 版本 2023-05-01-preview 或更新版本。您必須在 APIM 執行個體上獲得參與者或更高角色的指派，才能呼叫 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=......."
}
```

若要啟用 APIM 閘道要求的追蹤，請在 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 的追蹤

前進到下一個教學課程：

使用修訂

共用方式為