Tüm Ürünler
Search
Belge Merkezi

API Gateway:Troubleshoot issues that occur during API debugging

Son Güncelleme:Oct 04, 2026

API Gateway, yayınladığınız API'leri çevrimiçi olarak hata ayıklamanıza olanak tanır. Bu konuda, API hata ayıklama sürecinde karşılaşılan sorunların nasıl çözüleceği açıklanmaktadır.

Hata ayıklama kısıtlamaları

Yayınlanmış API'lerde hata ayıklamak ve hataları gidermek için API Gateway konsolundaki API hata ayıklama özelliğini kullanın. Başlamadan önce aşağıdaki kısıtlamaları dikkate alın:

Not
  • API hata ayıklama özelliği üç kimlik doğrulama yöntemini destekler: imza tabanlı kimlik doğrulama, basit kimlik doğrulama (AppCode) ve temel kimlik doğrulama eklentisi (BasicAuth eklentisi).

  • API hata ayıklama özelliği multipart ve form-data türlerini destekler. Hata ayıklama sayfasında dosya yükleyebilirsiniz.

  • Hata ayıklama sayfasındaki maksimum istek paketi boyutu 512 KB'dir. Daha büyük veri yükleri için hata ayıklama amacıyla SDK'ları kullanın.

  • Bir örnekte izin listesi veya engelleme listesi içeren bir IP adresi tabanlı kısıtlama eklentisi yapılandırdıysanız, listenin hata ayıklama için kullanılan IP adresine izin verdiğinden emin olun. Bu IP adresini API hata ayıklama sayfasının sol alt köşesinde bulabilirsiniz.

Yanıt başlıklarından hata bilgilerini okuyun

API Gateway, aldığı her istek için bir yanıt döndürür. X-Ca önekiyle başlayan başlıklar, API Gateway tarafından döndürülen tanılama bilgilerini taşır. Sorun giderme için en yararlı üç başlık şunlardır:

  • X-Ca-Error-Code: Hata kodu. Yalnızca API Gateway isteği reddettiğinde mevcut olur.

  • X-Ca-Request-Id: Benzersiz istek kimliği. API Gateway, her istek için bu kimliği oluşturur ve döndürür. Hem istemcinizde hem de arka uç hizmetinizde bu kimliği kaydedin; izleme ve sorun giderme için ana başvuru noktanız budur.

  • X-Ca-Error-Message: Hata mesajı. Bir istek başarısız olduğunda X-Ca-Error-Code ile birlikte döndürülür.

X-Ca-Request-Id ile çağrı ayrıntılarını sorgulayın

İlk hatayı belirlemek için X-Ca-Error-Code ve X-Ca-Error-Message değerlerini kullanın. Üç olası sonuç vardır:

API Gateway tarafından bildirilen hatalar

Eğer X-Ca-Error-Code boş değilse, API Gateway isteği reddetmiştir. Hata kodu altı karakterlik bir dizedir. Nedenin kısa bir açıklaması için X-Ca-Error-Message değerini kullanın. Hata kodlarının tam listesi için bkz. Hata kodları.

Arka uç hizmeti tarafından bildirilen hatalar

HTTP durum kodu 200 değilse ve X-Ca-Error-Code boşsa, API Gateway isteği başarıyla iletmiş ancak arka uç hizmeti 200 dışı bir yanıt döndürmüştür. Arka uç hizmeti mantığınızı kontrol edin. API'yi Alibaba Cloud Marketplace üzerinden satın aldıysanız hizmet sağlayıcısıyla iletişime geçin.

Başarılı istek

HTTP durum kodu 200 ise, API Gateway isteği iletmiş ve arka uç hizmeti başarılı bir yanıt döndürmüştür.

Daha derinlemesine inceleme yapmak için X-Ca-Request-Id kullanarak Simple Log Service'te ayrıntılı istek günlüklerini sorgulayabilir ve API Gateway konsolunda sonuçları görüntüleyebilirsiniz. Ayrıca bu kimliği teknik destekle paylaşabilirsiniz.

Konsolda bir isteği aramak için:

  1. API Gateway konsoluna oturum açın.

  2. Sol gezinme bölmesinde Call APIs > Troubleshooting seçeneklerini tıklayın. Region of the API Gateway ve X-Ca-Request-Id değerlerini girin, ardından Query düğmesini tıklayın.

Not

Günlük alanları hakkında daha fazla bilgi için bkz. API çağrılarının günlüklerini yönetmek için Simple Log Service'i kullanma.

İzleme günlüklerini alın

API hata ayıklama sayfasında bir istek gönderdikten sonra izleme günlüğünü görüntüleyebilirsiniz. Günlük, istek yaşam döngüsünün tamamını kaydeder: API Gateway'in istemciden aldığı istek, API Gateway içindeki işleme adımları, API Gateway'in arka uç hizmetine gönderdiği istek, arka uç yanıtı ve istemciye döndürülen son yanıt.

Bir RAM kullanıcı hesabı veya üstlenilmiş rol kullanıyorsanız, isteği göndermeden önce Record Trace log seçeneğini işaretleyin. Hesabın ayrıca API'nin bulunduğu örnek için kök hesap tarafından apigateway:AcquireGatewayToken iznine sahip olması gerekir. İzin verme hakkında daha fazla bilgi için bkz. API'leri yönetmek için RAM'i kullanma.

Aşağıdaki örnek, bu izni veren ilke bildirimini göstermektedir:

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# The {#} symbol indicates a variable that you must replace with an actual value.

Tanılama sekmesini kullanarak hataları analiz edin

Tanılama sekmesindeki Call information bölümünde herhangi bir çağrı için günlükleri inceleyebilirsiniz. İki gecikme süresi alanı, bir hatanın API Gateway içinde mi yoksa arka uç hizmetinde mi kaynaklandığını hemen belirlemenize olanak tanır:

  • TotalLatency: API Gateway'in istemci isteğini almasından istemciye eksiksiz bir yanıt göndermesine kadar geçen toplam süre.

  • ServiceLatency: API Gateway'in isteği arka uç hizmetine göndermesinden eksiksiz bir yanıt almasına kadar geçen süre.

Eğer ServiceLatency değeri 0 ise, istek API Gateway tarafından engellenmiş ve arka uç hizmetine ulaşmamıştır. Eğer ServiceLatency değeri 0'dan büyükse, istek arka uç hizmetine ulaşmıştır.

Günlük, istek yolundaki her aşama için G/Ç zaman damgalarını da kaydeder:


Alan


Açıklama


FrontRequestStart


API Gateway istemci isteğini almaya başladığında


FrontRequestEnd


API Gateway istemci isteğini almayı bitirdiğinde


BackendRequestStart


API Gateway isteği arka uç hizmetine göndermeye başladığında


BackendRequestEnd


API Gateway isteği arka uç hizmetine göndermeyi bitirdiğinde


BackendResponseStart


API Gateway arka uç hizmeti yanıtını almaya başladığında


BackendResponseEnd


API Gateway arka uç hizmeti yanıtını almayı bitirdiğinde


FrontResponseStart


API Gateway yanıtı istemciye göndermeye başladığında


FrontResponseEnd


API Gateway yanıtı istemciye göndermeyi bitirdiğinde

Günlük alanları hakkında daha fazla bilgi için bkz. API çağrılarının günlüklerini yönetmek için Simple Log Service'i kullanma.