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

APPLIES TO: Tüm API Yönetimi katmanları

Bu öğretici, Azure API Management'te istek işleme sürecinin nasıl inceleneceğini veya trace edileceğini açıklar. İzleme, API'nizde hata ayıklamanıza ve sorun gidermenize yardımcı olur.

Not

Şu anda bu özellik çalışma alanlarında kullanılamaz.

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 terminoloji öğrenin.
• Aşağıdaki 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 için abonelikleri veya Ocp-Apim-Trace üst bilgisini desteklemez.
• API güvenliğini geliştirmek için izleme artık tek bir API düzeyinde etkinleştirilebilir. API Management REST API'sini kullanarak zaman sınırlı bir belirteç alın ve belirteci ağ geçidine bir istekte geçirin. Ayrıntılar için bkz. Bir API'nin izlenmesini etkinleştirme.
• İzlemeyi etkinleştirirken dikkatli olun. İzleme verilerinde hassas bilgileri ifşa edebilir. İzleme verilerini korumak için uygun güvenlik önlemlerine sahip olduğunuzdan emin olun.

Azure portalında bir aramanın izini sürün

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.

1. Azure portalında oturum açın ve API Management örneğine gidin.

2. API'leri> seçin.

3. API listenizden Petstore API'sini seçin.

4. Test sekmesini seçin.

5. Evcil hayvan kimliğine göre bul işlemini seçin.

6. petIdSorgu parametresi içine 1 girin.

7. İsteğe bağlı olarak, istekte kullanılan Ocp-Apim-Subscription-Key üst bilgisinin değerini göz simgesini seçerek denetleyin.

   İpucu

   Ocp-Apim-Subscription-Key değerini, Azure portalında başka bir abonelik için anahtar alarak 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.

8. İzleme'yi seçin.

İzleme bilgilerini gözden geçirme

1. Arama tamamlandıktan sonra HTTP yanıtında İzleme sekmesine gidin.

2. Ayrıntılı izleme bilgilerine atlamak için aşağıdaki bağlantılardan birini seçin: Gelen, Backend, Giden, Hata sırasında.

   

   • Gelen Çağrıdan alınan özgün isteği ve API Management tarafından bu 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.
   • Backend. API Management'in API arka ucuna gönderdiği istekleri ve aldığı yanıtları gösterir.
   • Giden. Arayana geri göndermeden önce yanıta uygulanan ilkeleri gösterir.
   • Hata meydana geldiğinde. İsteğin işlenmesi sırasında oluşan hataları ve hatalara uygulanan ilkeleri gösterir.

   İpucu

   Her adım, API Management isteği aldığından bu yana geçen süreyi de gösterir.

API için izlemeyi etkinleştirme

curl, REST İstemci uzantısıyla Visual Studio Code gibi bir REST istemcisi veya bir istemci uygulaması kullanılırken API Management isteği için izlemeyi etkinleştirmek için aşağıdaki üst düzey adımlar gereklidir. Şu anda bu adımlar API Management REST API kullanılarak izlenmelidir:

1. İzleme için hata ayıklama jetonu alın.
2. Apim-Debug-Authorization istek üst bilgisindeki belirteç değerini API Management ağ geçidine ekleyin.
3. Yanıt üst bilgisi Apim-Trace-Id'de bir izleme kimliği alın.
4. İ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 Yönetimi REST API'sinin 2023-05-01-preview veya sonraki bir sürümünü gerektirir.
• Hata ayıklama belirteci almak için API Management örneğinde Katkıda Bulunan veya daha yüksek bir role sahip olmanız veya API'de eşdeğer yazma izinlerine sahip olmanız gerekir.
• REST API'de kimlik doğrulaması hakkında bilgi için bkz. Azure REST API başvurusu.

1. Hata ayıklama belirteci edinin. API Management ağ geçidinin Debug Kimlik Bilgilerini Listele API'sini çağırın. URI'ye buluttaki örneğin yönetilen ağ geçidi için yönetilen değerini veya kendi barındırılan ağ geçidinin ağ geçidi kimliğini girin. Örneğin, örneğin yönetilen ağ geçidinin izleme kimlik bilgilerini almak için aşağıdaki örneğe 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. purposes tracingolarak belirtin. Varsayılan olarak, yanıtta döndürülen belirteç kimlik bilgilerinin süresi 1 saat sonra dolar. Yükte farklı bir değer belirtebilirsiniz. Süre sonu süresi en fazla 1 saat ile sınırlıdır. Örneğin:

   {
       "credentialsExpireAfter": "PT1H",
       "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
       "purposes": ["tracing"]
   }
   

   Not

   apiId, Azure portalında görüntülenen ad yerine yalnızca kaynağın tam kimliğinden alınabilir.

   ApiId alma:

   az apim api list --resource-group <resource-group> --service-name <service-name> -o table
   

   Hata ayıklama kimlik bilgileri, aşağıdaki örneğe benzer şekilde yanıtta döndürülür:

   {
         "token": "aid=api-name&......."
   }
   

2. Belirteç değerini istek üst bilgisine ekleyin. API Management ağ geçidine yönelik bir isteğin izlemeyi etkinleştirmek için belirteç değerini Apim-Debug-Authorization üst bilgisinde gönderin. Örneğin, önceki bir öğreticide içeri aktardığınız Petstore API'sine yönelik bir çağrıyı izlemek için aşağıdaki örneğe 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&......."
   

3. Yanıtı değerlendirin. Yanıt, hata ayıklama belirtecinin durumuna bağlı olarak aşağıdaki üst bilgilerden birini içerebilir:

   Yanıt başlığında üst bilgi	Explanation
   Apim-Trace-Id	Hata ayıklama belirteci geçerli. Değer izleme kimliğidir, örneğin: Apim-Trace-Id: 0123456789abcdef....
   Apim-Debug-Authorization-Expired	Token süresi doldu. Üst bilgi, son kullanma tarihi hakkındaki bilgileri içerir.
   Apim-Debug-Authorization-WrongAPI	Farklı bir API için alınan token. Üst bilgi bir hata iletisi içerir.

4. İz kaydını alın. Önceki adımda alınan izleme kimliğini ağ geçidinin Liste izleme API'sine geçirin. Örneğin, yönetilen ağ geçidinin izlemesini almak için aşağıdaki örneğe 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 dosyası

Visual Studio Code REST client uzantısıyla bu adımları otomatikleştirmeye yardımcı olmak için aşağıdaki örnek .http dosyasını 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
@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}}"
}

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

Özet

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 adım

Sonraki derse geçin

Düzeltmeleri kullanma