Öğretici: İstek izlemeyi kullanarak API'lerinizde hata ayıklama

2025-04-21

UYGULANANLAR: Tüm API Management katmanları

Bu öğreticide, Azure API Management'ta istek işlemenin nasıl denetlendiği (izlenir) açıklanır. İzleme, API'nizde hata ayıklamanıza ve sorun gidermenize yardımcı olur.

İpucu

API ekipleri bu özelliği çalışma alanlarında kullanabilir. Çalışma alanları, API'lere ve kendi API çalışma zamanı ortamlarına yalıtılmış yönetim erişimi sağlar.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

Test konsolunda örnek bir çağrıyı izleme
İstek işleme adımlarını gözden geçirme
API için izlemeyi etkinleştirme

Önkoşullar

Azure API Management terminolojisini öğrenin.
Şu hızlı başlangıcı tamamlayın: Azure API Management örneği oluşturma.
Aşağıdaki öğreticiyi tamamlayın: İlk API'nizi içeri aktarın ve yayımlayın.

Önemli

API Management artık izleme aboneliklerini veya Ocp-Apim-Trace üst bilgisini desteklemez.
API güvenliğini geliştirmek için artık API Management REST API'sini kullanarak zaman sınırlı bir belirteç elde ederek ve belirteci ağ geçidine bir istekte geçirerek izleme tek bir API düzeyinde etkinleştirilebilir. Ayrıntılar için bkz. Bir API'nin izlenmesini etkinleştirme.
İzleme verilerindeki hassas bilgileri açığa çıkaraabildiği için izlemeyi etkinleştirirken dikkatli olun. İzleme verilerini korumak için uygun güvenlik önlemlerine sahip olduğunuzdan emin olun.

Portalda bir çağrıyı izleme

Portaldaki test konsolunda bir API isteğini izlemek için bu adımları izleyin. Bu örnek, önceki bir öğreticide örnek bir API'yi içeri aktarmış olduğunuz varsayılır. İçeri aktardığınız farklı bir API ile benzer adımları izleyebilirsiniz.

Azure portalında oturum açın ve API Management örneğine gidin.
API'leri> seçin.
API listenizden Petstore API'sini seçin.
Test sekmesini seçin.
Evcil hayvan kimliğine göre bul işlemini seçin.
petIdSorgu parametresi içine 1 girin.
İsteğe bağlı olarak, istekte kullanılan Ocp-Apim-Subscription-Key üst bilgisinin değerini göz simgesini seçerek denetleyin.

İpucu

Portalda başka bir abonelik için bir anahtar alarak Ocp-Apim-Subscription-Key değerini geçersiz kılabilirsiniz. Abonelikler'i seçin ve başka bir abonelik için bağlam menüsünü (...) açın. Anahtarları göster/gizle'yi seçin ve anahtarlardan birini kopyalayın. Gerekirse anahtarları da yeniden oluşturabilirsiniz. Ardından test konsolunda + Üst bilgi ekle'yi seçerek yeni anahtar değeriyle bir Ocp-Apim-Subscription-Key üst bilgisi ekleyin.
İzleme'yi seçin.

İzleme bilgilerini gözden geçirme

Arama tamamlandıktan sonra HTTP yanıtında İzleme sekmesine gidin.
Ayrıntılı izleme bilgilerine atlamak için aşağıdaki bağlantılardan herhangi birini seçin: Gelen, Arka uç, Giden, Hatada.
- Gelen - Arayanın API Yönetimine gönderdiği özgün isteği ve isteğe uygulanan ilkeleri gösterir. Örneğin, Öğretici: API'nizi dönüştürme ve koruma altına alma konusunda ilkeler eklediyseniz, bunlar burada görünür.
- Arka uç - API Management tarafından API arka ucuna gönderilen istekleri ve alınan yanıtı gösterir.
- Giden - Yanıtı aramayı yapan kişiye geri göndermeden önce uygulanan politikaları gösterir.
- Hata durumunda - İsteğin işlenmesi sırasında oluşan hataları ve hatalara uygulanan ilkeleri gösterir.
İpucu

Her bir adım, isteğin API Yönetimi tarafından alınmasından bu yana geçen süreyi de gösterir.

API için izlemeyi etkinleştirme

API Management'a yönelik bir isteğin izlenmesini etkinleştirmek için curl kullanırken, REST İstemci uzantısına sahip Visual Studio Code gibi bir REST istemcisi ya da bir istemci uygulaması kullanıyorsanız, aşağıdaki genel adımlar gereklidir. Şu anda BU adımlar API Management REST API kullanılarak izlenmelidir:

İzleme için hata ayıklama jetonu alın.
İstek üst bilgisindeki Apim-Debug-Authorization belirteç değerini API Management ağ geçidine ekleyin.
Yanıt üst bilgisi Apim-Trace-Id'de bir izleme kimliği alın.
İz kimliğine karşılık gelen izi alın.

Ayrıntılı adımlar aşağıda verilmiştir.

Not

Bu adımlar API Management REST API sürüm 2023-05-01-preview veya sonrasını gerektirir. REST API'yi çağırmak için API Management örneğinde Katkıda Bulunan veya daha yüksek bir role sahip olmanız gerekir.
REST API'de kimlik doğrulaması hakkında bilgi için bkz . Azure REST API başvurusu.

Hata ayıklama belirtecini edin - API Yönetimi ağ geçidinin Hata ayıklama kimlik bilgilerini listeleme API'sini çağırın. URI'ye, buluttaki örneğin yönetilen ağ geçidi için "yönetilen" veya kendi kendine barındırılan bir ağ geçidi için ağ geçidi kimliğini girin. Örneğin, örneğin yönetilen ağ geçidinin izleme kimlik bilgilerini almak için aşağıdakine benzer bir istek kullanın:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
```
İstek gövdesinde, izlemek istediğiniz API'nin tam kaynak kimliğini geçirin ve purposes yerini tracing olarak belirtin. Varsayılan olarak yanıtta döndürülen belirteç kimlik bilgilerinin süresi 1 saat sonra dolar, ancak yükte farklı bir değer belirtebilirsiniz. Süre sonu süresinin en fazla 1 saat ile sınırlı olduğunu unutmayın. Örneğin:
```
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
Not

apiId yalnızca portalda görüntülenen addan değil, tam kaynak kimliğinden çekilebilir.

ApiId alma:
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
Hata ayıklama kimlik bilgileri yanıtta döndürülür ve aşağıdakine benzer:
```
{
      "token": "aid=api-name&......."
}
```
İstek üst bilgisine belirteç değerini ekleme - API Management ağ geçidine bir istek için izlemeyi etkinleştirmek için, belirteç değerini bir Apim-Debug-Authorization üst bilgide gönderin. Örneğin, önceki bir öğreticide içeri aktardığınız Petstore API'sine yapılan çağrıyı izlemek için aşağıdakine benzer bir istek kullanabilirsiniz:
```
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&......."
```
Yanıtı değerlendirme - Yanıt, hata ayıklama belirtecinin durumuna bağlı olarak aşağıdaki üst bilgilerden birini içerebilir:
- Hata ayıklama belirteci geçerliyse, yanıt aşağıdakine benzer şekilde, değeri izleme kimliği olan bir Apim-Trace-Id üst bilgi içerir:
```
Apim-Trace-Id: 0123456789abcdef....
```
- Hata ayıklama belirtecinin süresi dolduysa, yanıt son kullanma tarihi hakkında bilgi içeren bir Apim-Debug-Authorization-Expired üst bilgi içerir.
- Hata ayıklama belirteci farklı bir API için alındıysa, yanıt hata iletisi içeren bir Apim-Debug-Authorization-WrongAPI üst bilgi içerir.
İzlemeyi geri alma - Önceki adımda alınan izleme kimliğini ağ geçidinin Listeleme izleme API'sine geçirin. Örneğin, yönetilen ağ geçidinin izlemesini almak için aşağıdakine benzer bir istek kullanın:
```
POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
```
İstek gövdesinde, önceki adımda alınan izleme kimliğini geçirin.
```
{
    "traceId": "0123456789abcdef...."
}
```
Yanıt gövdesi, ağ geçidine yönelik önceki API isteğinin izleme verilerini içerir. İzleme, portalın test konsolunda bir çağrıyı izleyerek görebileceğiniz izlemeye benzer.

VS Code REST İstemci uzantısı için örnek `.http` dosya

Visual Studio Code REST İstemci uzantısıyla bu adımları otomatikleştirmeye yardımcı olmak için aşağıdaki örnek .http dosyayı kullanabilirsiniz:

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

İzleme bilgilerini özelleştirme hakkında bilgi için izleme ilkesine bakın.

Sonraki adımlar

Bu öğreticide, şunların nasıl yapıldığını öğrendiniz:

Test konsolunda örnek bir çağrıyı izleme
İstek işleme adımlarını gözden geçirme
API için izlemeyi etkinleştirme

Sonraki derse geçin

Düzeltmeleri kullanma

Aracılığıyla paylaş