Tutorial: Men-debug API Anda menggunakan pelacakan permintaan

BERLAKU UNTUK: Semua lapisan API Management

Tutorial ini menjelaskan cara memeriksa, atau trace, pemrosesan permintaan di Azure API Management. Pelacakan membantu Anda men-debug dan memecahkan masalah API Anda.

Catatan

Saat ini, fitur ini tidak tersedia di ruang kerja.

Dalam tutorial ini, Anda akan mempelajari cara:

Melacak contoh panggilan di konsol pengujian
Meninjau langkah-langkah pemrosesan permintaan
Mengaktifkan pelacakan untuk API

Prasyarat

Pelajari terminologi Azure API Management.
Selesaikan panduan cepat berikut: Buat instans Azure API Management.
Selesaikan tutorial berikut: Mengimpor dan menerbitkan API pertama Anda.

Penting

API Management tidak lagi mendukung langganan untuk pelacakan atau header Ocp-Apim-Trace.
Untuk meningkatkan keamanan API, pelacakan sekarang dapat diaktifkan pada tingkat API individual. Dapatkan token terbatas waktu menggunakan API Management REST API, dan teruskan token dalam permintaan ke gateway. Untuk detailnya, lihat Mengaktifkan pelacakan API.
Berhati-hatilah saat mengaktifkan pelacakan. Ini dapat mengekspos informasi sensitif dalam data pelacakan. Pastikan Anda memiliki langkah-langkah keamanan yang sesuai untuk melindungi data pelacakan.

Melacak panggilan di portal Azure

Ikuti langkah-langkah ini untuk melacak permintaan API di konsol pengujian di portal. Contoh ini mengasumsikan bahwa Anda mengimpor API sampel dalam tutorial sebelumnya. Anda dapat mengikuti langkah-langkah serupa dengan API lain yang Anda impor.

Masuk ke portal Azure, dan navigasikan ke instans API Management Anda.
Pilih API>API.
Pilih Petstore API dari daftar API Anda.
Pilih tab Uji.
Pilih operasi Temukan hewan peliharaan menurut ID.
Pada parameter petId kueri, masukkan 1.
Secara opsional periksa nilai untuk header Ocp-Apim-Subscription-Key yang digunakan dalam permintaan dengan memilih ikon "mata".

Tips

Anda dapat mengambil alih nilai Ocp-Apim-Subscription-Key dengan mengambil kunci untuk langganan lain di portal Azure. Pilih Langganan dan buka menu konteks (...) untuk langganan lain. Pilih Tampilkan/sembunyikan kunci dan salin salah satu kunci. Anda juga dapat menghasilkan ulang kunci jika diperlukan. Kemudian, di konsol pengujian, pilih + Tambahkan header untuk menambahkan header Ocp-Apim-Subscription-Key dengan nilai kunci yang baru.
Pilih Lacak.

Meninjau informasi jejak

Setelah panggilan selesai, buka tab Lacak di tanggapan HTTP.
Pilih salah satu tautan berikut untuk melompat ke informasi pelacakan terperinci: Kesalahan Masuk, Backend, Keluar, Aktif.
- Lalu Lintas Masuk. Menampilkan permintaan asli API Management diterima dari pemanggil dan kebijakan yang diterapkan pada permintaan. Misalnya, jika Anda menambahkan kebijakan di Tutorial: Mengubah dan melindungi API Anda, kebijakan tersebut akan muncul di sini.
- Backend. Menampilkan permintaan API Management dikirim ke backend API dan respons yang diterimanya.
- Keluar. Memperlihatkan kebijakan yang diterapkan ke respons sebelum mengirim kembali ke pemanggil.
- Pada kesalahan. Memperlihatkan kesalahan yang terjadi selama pemrosesan permintaan dan kebijakan yang diterapkan pada kesalahan.
Tips

Setiap langkah juga menunjukkan waktu yang berlalu karena API Management menerima permintaan.

Mengaktifkan pelacakan untuk API

Langkah-langkah tingkat tinggi berikut diperlukan untuk mengaktifkan pelacakan permintaan ke API Management saat menggunakan curl, klien REST seperti Visual Studio Code dengan ekstensi Klien REST, atau aplikasi klien. Saat ini langkah-langkah ini harus diikuti menggunakan API Management REST API:

Dapatkan token debug untuk pelacakan.
Tambahkan nilai token di header permintaan Apim-Debug-Authorization ke gateway API Management.
Dapatkan ID pelacakan di Apim-Trace-Id header balasan.
Ambil jejak yang sesuai dengan ID pelacakan.

Langkah-langkah terperinci berikut.

Catatan

Langkah-langkah ini memerlukan API Management REST API versi 2023-05-01-preview atau yang lebih baru.
Anda harus diberi peran Kontributor atau yang lebih tinggi pada instans API Management atau memiliki izin tulis yang setara pada API untuk mendapatkan token debug.
Untuk informasi tentang mengautentikasi ke REST API, lihat referensi Azure REST API.

Dapatkan token debug. Panggil API Daftar kredensial debug dari gerbang API Management. Di URI, masukkan terkelola untuk gateway terkelola instans di cloud, atau ID gateway untuk gateway yang dihost sendiri. Misalnya, untuk mendapatkan kredensial pelacakan untuk gateway terkelola instans, gunakan permintaan yang mirip dengan contoh berikut:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
Di isi permintaan, berikan ID sumber daya lengkap API yang ingin Anda lacak. Tentukan purposes sebagai tracing. Secara default, kredensial token yang dikembalikan dalam respons kedaluwarsa setelah 1 jam. Anda dapat menentukan nilai yang berbeda dalam payload. Waktu kedaluwarsa dibatasi hingga maksimum 1 jam. Contoh:
```
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Catatan

apiId hanya dapat ditarik dari ID sumber daya lengkap, bukan nama yang ditampilkan di portal Azure.

Dapatkan apiId:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
Kredensial debug dikembalikan dalam respons, mirip dengan contoh berikut:
```
{
      "token": "aid=api-name&......."
}
```
Tambahkan nilai token di header permintaan. Untuk mengaktifkan pelacakan permintaan ke gateway API Management, kirim nilai token di header Apim-Debug-Authorization. Misalnya, untuk melacak panggilan ke PETstore API yang Anda impor dalam tutorial sebelumnya, Anda mungkin menggunakan permintaan yang mirip dengan contoh berikut:
```
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&......."
```

Evaluasi respons. Respons dapat berisi salah satu header berikut tergantung pada status token debug:

Header dalam respons	Explanation
`Apim-Trace-Id`	Token debug sah. Nilainya adalah ID pelacakan, seperti: `Apim-Trace-Id: 0123456789abcdef....`
`Apim-Debug-Authorization-Expired`	Token kedaluwarsa. Header menyertakan informasi tentang tanggal kedaluwarsa.
`Apim-Debug-Authorization-WrongAPI`	Token diperoleh untuk API yang berbeda. Header menyertakan pesan kesalahan.

Ambil jejaknya. Teruskan ID jejak yang diperoleh pada langkah sebelumnya ke API Daftar jejak gateway. Misalnya, untuk mengambil jejak gateway terkelola, gunakan permintaan yang mirip dengan contoh berikut:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
Di isi permintaan, berikan ID pelacakan yang diperoleh pada langkah sebelumnya.
```
{
    "traceId": "0123456789abcdef...."
}
```
Isi respons berisi data pelacakan untuk permintaan API sebelumnya ke gateway. Jejaknya mirip dengan jejak yang bisa Anda lihat saat Anda melacak panggilan di konsol pengujian portal.

Contoh file http untuk ekstensi Klien REST Visual Studio Code

Untuk membantu mengotomatiskan langkah-langkah ini dengan ekstensi Visual Studio Code REST Client, Anda dapat menggunakan contoh berikut .http file:

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/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
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{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}}"
}

Untuk informasi tentang menyesuaikan informasi pelacakan, lihat kebijakan pelacakan .

Ringkasan

Dalam tutorial ini, Anda mempelajari cara:

Melacak contoh panggilan di konsol pengujian
Meninjau langkah-langkah pemrosesan permintaan
Mengaktifkan pelacakan untuk API

Langkah selanjutnya

Melanjutkan ke tutorial berikutnya:

Gunakan revisi

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-18