Add clarity to the how-to trace section and included an example .http rest client file

Author: anotherRedbeard

articles/api-management/api-management-howto-api-inspector.md

@@ -74,7 +74,7 @@ Follow these steps to trace an API request in the test console in the portal. Th
 
 The following high level steps are required to enable tracing for a request to API Management when using `curl`, a REST client such as Visual Studio Code with the REST Client extension, or a client app. Currently these steps must be followed using the [API Management REST API](/rest/api/apimanagement):
 
-1. Obtain a token credential for tracing.
+1. Obtain a debug token for tracing.
 1. Add the token value in an `Apim-Debug-Authorization` request header to the API Management gateway.
 1. Obtain a trace ID in the `Apim-Trace-Id` response header.
 1. Retrieve the trace corresponding to the trace ID.
@@ -85,7 +85,7 @@ Detailed steps follow.
 > * These steps require API Management REST API version 2023-05-01-preview or later. You must be assigned the Contributor or higher role on the API Management instance to call the REST API.
 > * For information about authenticating to the REST API, see [Azure REST API reference](/rest/api/azure). 
 
-1. **Obtain a token credential** - Call the API Management gateway's [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. In the URI, enter "managed" for the instance's managed gateway in the cloud, or the gateway ID for a self-hosted gateway. For example, to obtain trace credentials for the instance's managed gateway, use a request similar to the following:
+1. **Obtain a debug token** - Call the API Management gateway's [List debug credentials](/rest/api/apimanagement/gateway/list-debug-credentials) API. In the URI, enter "managed" for the instance's managed gateway in the cloud, or the gateway ID for a self-hosted gateway. For example, to obtain trace credentials for the instance's managed gateway, use a request similar to the following:
 
     ```http
     POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
@@ -96,10 +96,17 @@ Detailed steps follow.
     ```json
     {
         "credentialsExpireAfter": PT1H,
-        "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
+        "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
         "purposes": ["tracing"]
     }
     ```
+
+    > NOTE:  The `apiId` can only be only be pulled from the full resource ID, not the name displayed in the portal.
+
+    Get apiId:
+    ```sh
+    az apim api list --resource-group <resource-group> --service-name <service-name> -o table
+    ```
         
     The token credential is returned in the response, similar to the following:
 
@@ -112,18 +119,20 @@ Detailed steps follow.
 1. **Add the token value in a request header** - To enable tracing for a request to the API Management gateway, send the token value in an `Apim-Debug-Authorization` header. For example, to trace a call to the Petstore API that you imported in a previous tutorial, you might use a request similar to the following:
 
     ```bash
-    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&......."
+    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&......."
     ```
 
-1. Depending on the token, the response contains one of the following headers:
-    * If the token is valid, the response includes an `Apim-Trace-Id` header whose value is the trace ID, similar to the following:
+1. **Evaluate the response** - The response can contain one of the following headers depending on the state of the debug token:
+    * If the debug token is valid, the response includes an `Apim-Trace-Id` header whose value is the trace ID, similar to the following:
 
         ```http
         Apim-Trace-Id: 0123456789abcdef....
         ```
         
-    * If the token is expired, the response includes an `Apim-Debug-Authorization-Expired` header with information about expiration date.
-    * If the token was obtained for a different API, the response includes an `Apim-Debug-Authorization-WrongAPI` header with an error message.
+    * If the debug token is expired, the response includes an `Apim-Debug-Authorization-Expired` header with information about expiration date.
+    * If the debug token was obtained for a different API, the response includes an `Apim-Debug-Authorization-WrongAPI` header with an error message.
 
 1. **Retrieve the trace** - Pass the trace ID obtained in the previous step to the gateway's [List trace](/rest/api/apimanagement/gateway/list-trace) API. For example, to retrieve the trace for the managed gateway, use a request similar to the following:
 
@@ -141,6 +150,58 @@ Detailed steps follow.
     
     The response body contains the trace data for the previous API request to the gateway. The trace is similar to the trace you can see by tracing a call in the portal's test console.
 
+Below is an example `.http` file for the VSCode http client extension:
+
+```http
+@subscriptionId = // Your subscription Id
+@resourceGroup = // Your resource group
+@apimName = // Your APIM Serviuce name
+@clientId = // Client id from an app registration for authentication
+@clientSecret = // Client Secret
+@externalHost = // The host name of the APP Gateway or the fully qualified gateway URL
+@subscriptionKey = // Subscription key
+@apiEndPoint = // API URL
+@requestBody = // Data to send
+@tenantId = // Tenant Id
+ 
+POST https://login.microsoftonline.com/{{tenandId}}/oauth2/token
+content-type: application/x-www-form-urlencoded
+ 
+grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
+ 
+###
+@authToken = {{login.response.body.$.access_token}}
+###
+# @name listDebugCredentials
+POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
+Authorization: Bearer {{authToken}}
+Content-Type: application/json
+{
+    "credentialsExpireAfter": "PT1H",
+    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
+    "purposes": ["tracing"]
+}
+ 
+###
+@debugToken = {{listDebugCredentials.response.body.$.token}}
+ 
+###
+# @name callApi
+curl -k -H "Apim-Debug-Authorization: {{debugToken}}" -H 'Host: {{externalHost}}' -H 'Ocp-Apim-Subscription-Key: {{subscriptionKey}}' -H 'Content-Type: application/json' '{{apiEndPoint}}' -d '{{requestBody}}'
+ 
+###
+@traceId = {{callApi.response.headers.Apim-Trace-Id}}
+ 
+###
+# @name getTrace
+POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
+Authorization: Bearer {{authToken}}
+Content-Type: application/json
+ 
+{
+    "traceId": "{{traceId}}"
+}
+```
 
 For information about customizing trace information, see the [trace](trace-policy.md) policy.