Tüm Ürünler
Search
Belge Merkezi

:Yükleme geri arama hatalarını nasıl gideririm?

Son Güncelleme:Oct 01, 2026

Bu konu, yükleme işlemlerindeki geri arama işlevlerinde karşılaşılan yaygın hataları ve bu hataların nasıl ele alınacağını açıklar.

Yükleme geri aramaları hakkında

Bir dosya yüklendiğinde OSS, geri arama sunucunuza bir Geri Arama gönderebilir. Yükleme geri aramasını uygulamak için yükleme isteğine ilgili geri arama parametrelerini ekleyebilirsiniz. Yükleme geri aramasını destekleyen API'ler şunlardır: PutObject, PostObject ve CompleteMultipartUpload. Daha fazla bilgi için Geliştirici Kılavuzu'ndaki Yükleme geri araması ve Geri Arama API'si konularına bakın.

Not

Geri arama sunucusuna hizmet sunucusu da denir.

Uygulama senaryoları

  • Bildirim

    Tipik bir uygulamada yetkili bir üçüncü taraf, dosya yükleme sırasında geri arama parametrelerini belirterek yükleme ve geri arama işlemi gerçekleştirir. Yükleme tamamlandığında OSS, geri arama sunucusuna bir geri arama isteği gönderir. Geri arama sunucusu bu isteği aldığında yükleme bilgilerini kaydeder.

  • İşleme, inceleme ve istatistik

    Geri arama sunucusu, bir geri arama isteği aldığında yüklenen dosyaları işler, inceler ve bunlar üzerinde istatistiksel analizler yapar.

Veri akışı

Aşağıdaki tabloda veri akışları açıklanmaktadır.

Veri akışı

Anlamı

Açıklama

1

İstemci bir dosya yükler ve bir geri arama parametresi taşır. Biçim hakkında daha fazla bilgi için bkz. SDK/PostObject.

Yükleme, SDK (PutObject ve CompleteMultipartUpload) aracılığıyla; geri arama ise PostObject API'si aracılığıyla gerçekleştirilir.

2

OSS örneği dosyayı depolar ve bir geri arama başlatır.

OSS örneği, yükleme isteğinde belirtilen CallbackUrl adresine bir POST isteği gönderir. Geri arama zaman aşımı süresi beş saniyedir; bu sabit bir değerdir ve yapılandırılamaz.

POST isteğinin biçimi hakkında daha fazla bilgi için bkz. Geri arama isteği başlatma.

3

Geri arama sunucusu işleme sonucunu döndürür.

  • Geri arama sunucusu tarafından döndürülen ileti gövdesi JSON biçiminde olmalıdır.

  • Döndürülen sonuç 200 durum kodu değilse OSS, geri aramanın başarısız olduğunu belirler. 40x kodu geçersiz parametreleri veya geri arama hatalarını gösterir. 50x kodu zaman aşımını veya bağlantı hatalarını gösterir.

4

OSS, yükleme ve geri arama sonucunu döndürür.

  • Hem yükleme hem de geri arama başarılı olursa 200 döndürülür.

  • Yükleme başarılı olur ancak geri arama başarısız olursa 203 döndürülür. ErrorCode değeri CallbackFailed olur ve ErrorMessage hata nedenini belirtir.

SDK/PostObject

Dosya yükleme sırasında, geri arama sunucusunun URL'sini, geri arama sunucusuna gönderilecek verileri ve veri biçimini belirtmek için geri arama parametrelerini ayarlayabilirsiniz. Geri arama sunucusu bir geri aramayı işlerken bucket ve object gibi bazı bağlam bilgileri sistem değişkenleri kullanılarak belirtilir. Diğer bağlam bilgileri ise özel değişkenler kullanılarak belirtilir.

Bir yükleme geri araması için aşağıdaki parametreler kullanılabilir:


Alan


Anlamı


Açıklama


callbackUrl


Geri arama sunucusu adresi


Zorunlu


callbackHost


Geri arama isteği ileti üstbilgisindeki Host değeri


İsteğe bağlı. Varsayılan değer callbackUrl değeridir.


callbackBody


Geri arama isteği ileti gövdesi


Zorunlu. Sistem değişkenlerini ve özel değişkenleri içerebilir.


callbackBodyType


Geri arama isteği ileti üstbilgisindeki Content-Type değeri, yani callbackBody veri biçimi


İsteğe bağlı. application/x-www-form-urlencoded (varsayılan) veya application/json olabilir.

Yükleme geri arama parametreleri, yükleme isteğine aşağıdaki iki yoldan biriyle eklenir:

  • Geri arama parametreleri, ileti üstbilgisindeki x-oss-callback ile taşınır. Bu yaygın ve önerilen bir yöntemdir.

  • Geri arama parametreleri, QueryString'deki callback ile taşınır.

x-oss-callback veya callback değerlerini oluşturma kuralları şöyledir:

Callback := Base64(CallbackJson)
CallbackJson := '{' CallbackUrlItem, CallbackBodyItem [, CallbackHostItem, CallbackBodyTypeItem] '}' 
CallbackUrlItem := '"'callbackUrl'"' ':' '"'CallbackUrlValue'"'
CallbackBodyItem := '"'callbackBody'"' ':' '"'CallbackBodyValue'"'
CallbackHostItem := '"'callbackHost'"' ':' '"'CallbackHostValue'"'
CallbackBodyTypeItem := '"'callbackBodyType'"' : '"'CallbackBodyType'"'
CallbackBodyType := application/x-www-form-urlencoded | application/json

CallbackJson değeri örnekleri şöyledir:


    "callbackUrl" : "http://abc.com/test.php",
    "callbackHost" : "oss-cn-hangzhou.aliyuncs.com",
    "callbackBody" : "{\"bucket\":${bucket}, \"object\":${object},\"size\":${size},\"mimeType\":${mimeType},\"my_var\":${x:my_var}}",
    "callbackBodyType" : "application/json"
                

veya


    "callbackUrl" : "http://abc.com/test.php",
    "callbackBody" : "bucket=${bucket}&object=${object}&etag=${etag}&size=${size}&mimeType=${mimeType}&my_var=${x:my_var}"
                

Sistem değişkenleri ve özel değişkenler

CallbackJson örneğindeki CallbackJson değişkenleri (örneğin ${bucket}, ${object} ve ${size}) OSS tarafından tanımlanan sistem değişkenleridir. Geri arama sırasında OSS, sistem değişkenlerini gerçek değerlerle değiştirir. Aşağıdaki tabloda OSS tarafından tanımlanan sistem değişkenleri listelenmiştir.


Değişken


Anlamı


${bucket}


Depolama alanı adı


${object}


Dosya adı


${etag}


Dosyanın etag değeri


${size}


Dosya boyutu


${mimeType}


Dosya türü (örneğin image/jpeg)


${imageInfo.height}


Görüntü yüksekliği


${imageInfo.width}


Görüntü genişliği


${imageInfo.format}


Görüntü biçimi (örneğin .jpg ve .png)

Not
  • Sistem değişkenleri büyük/küçük harfe duyarlıdır.

  • Sistem değişkeni ${bucket} biçimindedir.

  • imageInfo yalnızca görüntüler için ayarlanır. Görüntü dışı biçimler için imageInfo değeri boştur.

CallbackJson örneğindeki CallbackJson değişkenleri (örneğin ${x:my_var}) özel değişkenlerdir. Geri arama sırasında OSS, özel değişkenleri özel değerlerle değiştirir. Özel değişken değerleri, yükleme isteği tarafından aşağıdaki iki yoldan biriyle tanımlanır ve taşınır:

  • Özel değişkenler, ileti üstbilgisindeki x-oss-callback-var ile taşınır. Bu yaygın ve önerilen bir yöntemdir.

  • Özel değişkenler, QueryString'deki callback-var ile taşınır.

x-oss-callback-var veya callback-var değerlerini oluşturma kuralları şöyledir:

CallbackVar := Base64(CallbackVarJson)
CallbackVarJson := '{' CallbackVarItem [, CallbackVarItem]* '}'
CallbackVarItem := '"''x:'VarName'"' : '"'VarValue'"'

CallbackVarJson değeri örnekleri şöyledir:


    "x:my_var1" : "value1",
    "x:my_var2" : "value2"
            
Not
  • Özel değişkenler x: ile başlamalıdır: Büyük/küçük harfe duyarlıdırlar ve ${x:my_var} biçimindedirler.

  • Özel değişken uzunluğu, ileti üstbilgisi ve URL uzunluğu ile sınırlıdır. Özel değişken sayısının 10'u ve toplam uzunluğun 512 baytı geçmemesi önerilir.

SDK kullanım örneği

JAVA ve JS gibi bazı SDK'lar yukarıdaki adımları kapsüller. Python, PHP ve C gibi bazı SDK'lar ise yükleme geri arama parametrelerini ve özel değişkenleri oluşturmak için yukarıdaki kuralları kullanmalıdır. Aşağıdaki tabloda SDK kullanım örnekleri listelenmiştir.

SDK

Yükleme geri arama örneği

Açıklama:

JAVA

CallbackSample.java

CallbackBody içindeki kaçış karakterlerine dikkat edin.

Python

object_callback.py

-

PHP

Callback.php

$options içindeki OSS_CALLBACK ve OSS_CALLBACK_VAR değerlerinin Base64 ile kodlanması gerekmez; bu işlem SDK tarafından gerçekleştirilir.

C #

UploadCallbackSample.cs

PutObjectResult.ResponseStream değerini okumak için using kullanın ancak bunun devre dışı bırakıldığından emin olun.

JS

object.test.js

-

C

oss_callback_sample.c

-

Ruby

callback.rb

-

iOS

Yüklemeden sonra geri arama bildirimi

var1 biçiminin x:var1 olduğundan emin olun.

Android

Yüklemeden sonra geri arama bildirimi

CallbackBody içindeki kaçış karakterlerine dikkat edin.

Not

Go SDK şu anda yükleme geri aramasını desteklememektedir.

PostObject kullanım örneği

PostObject, yükleme geri aramasını destekler; geri arama parametreleri form alanı callback ile, özel değişkenler ise bağımsız bir form alanı ile taşınır. Daha fazla bilgi için bkz. PostObjet.

Aşağıdaki tabloda PostObject kullanım örnekleri listelenmiştir.


SDK


Yükleme geri arama örneği


Java


PostObjectSample.java


Python


object_post.py


C#


PostPolicySample.cs

Geri arama sunucusu

Geri arama sunucusu, OSS'ten gelen geri arama isteklerini ve POST iletilerini işleyen bir HTTP sunucusudur. Geri arama sunucusu URL'si, yükleme geri arama parametresi olan callbackUrl değeridir. Yüklenen verilerin kaydedilmesi, incelenmesi, işlenmesi ve istatistiksel analizi için kendi işleme mantığınızı geri arama sunucusunda uygulayabilirsiniz.

Geri arama imzası

Geri arama sunucusunun, POST isteğinin OSS yükleme geri aramasından geldiğinden emin olmak için isteğin imzasını doğrulaması gerekir. Geri arama sunucusu, imzayı doğrulamadan da doğrudan iletiyi işleyebilir. Geri arama sunucusunun güvenliğini artırmak için sunucunun ileti imzasını doğrulaması önerilir. Geri arama imzalama kuralları hakkında daha fazla bilgi için bkz. Geri arama imzası.

Not

OSS geri arama sunucusu örneği, imza doğrulamanın nasıl uygulanacağını açıklar. Kodu doğrudan kullanmanız önerilir.

İleti işleme

Geri arama sunucusunun temel mantığı, OSS geri arama isteğini işlemektir. Aşağıdaki öğelere dikkat edin:

  • Geri arama sunucusu, OSS'in POST isteğini işlemelidir.

  • OSS geri arama zaman aşımı süresi beş saniyedir. Bu nedenle, geri arama sunucusu işlemi beş saniye içinde tamamlamalı ve sonucu döndürmelidir.

  • Geri arama sunucusundan OSS'e gönderilen ileti gövdesi JSON biçiminde olmalıdır.

  • Geri arama sunucusu kendi mantığını kullanır; OSS ise belirli hizmet mantığı yerine örnekler sağlar.

Uygulama örneği

Aşağıdaki tabloda geri arama sunucusunun uygulama örnekleri açıklanmaktadır.


Dil


Örnek


Çalıştırma yöntemi


JAVA


AppCallbackServer.zip


Paketi açın ve java -jar oss-callback-server-demo.jar 9000 komutunu çalıştırın.


PHP


callback-php-demo.zip


Programı Apache ortamında dağıtın ve çalıştırın.


Python


callback_app_server.py.zip


Paketi açın ve python callback_app_server.py komutunu çalıştırın.


Ruby


oss-callback-server


ruby aliyun_oss_callback_server.rb komutunu çalıştırın.

Hata ayıklama prosedürü

Yükleme geri araması hata ayıklama, dosya yükleyen istemcinin ve geri aramayı işleyen geri arama sunucusunun hata ayıklamasını içerir. Önce istemcide, ardından geri arama sunucusunda hata ayıklamanız önerilir. İki parçayı bağımsız olarak hata ayıkladıktan sonra tam yükleme geri aramasını gerçekleştirin.

  • İstemci hata ayıklama

    İstemcide hata ayıklamak için OSS tarafından sağlanan http://oss-demo.aliyuncs.com:23450 geri arama sunucusunu, yani callbackUrl geri arama parametresini kullanabilirsiniz. Bu geri arama sunucusu yalnızca geri arama isteği imzasını doğrular ve geri arama isteğini işlemez. İmzası başarıyla doğrulanan geri arama istekleri için sunucu {"Status":"OK"} döndürür. İmzası doğrulanamayan geri arama istekleri için sunucu 400 Bad Request döndürür. POST dışı istekler için sunucu 501 Unsupported method döndürür. Geri arama sunucusu örneğinin kodu hakkında daha fazla bilgi için bkz. callback_app_server.py.zip.

  • Geri arama sunucusu hata ayıklama

    Geri arama sunucusu, POST isteğini işleyebilen bir HTTP sunucusudur. Geri arama sunucusunu OSS tarafından sağlanan örneğe göre değiştirebilir veya kendiniz uygulayabilirsiniz. Aşağıdaki tabloda OSS tarafından sağlanan geri arama sunucusu örnekleri açıklanmaktadır.


    Dil


    Örnek


    Çalıştırma yöntemi


    JAVA


    AppCallbackServer.zip


    Paketi açın ve java -jar oss-callback-server-demo.jar 9000 komutunu çalıştırın.


    PHP


    callback-php-demo.zip


    Programı Apache ortamında dağıtın ve çalıştırın.


    Python


    callback_app_server.py.zip


    Paketi açın ve python callback_app_server.py komutunu çalıştırın.


    C#


    callback-server-dotnet.zip


    Programı derleyin ve aliyun-oss-net-callback-server.exe 127.0.0.1 80 komutunu çalıştırın.


    Go


    callback-server-go.zip


    Programı derleyin ve aliyun_oss_callback_server komutunu çalıştırın.


    Ruby


    oss-callback-server


    ruby aliyun_oss_callback_server.rb komutunu çalıştırın.

    Geri arama sunucusu, cURL komutunu çalıştırarak hata ayıklanabilir. Aşağıdaki komutlar kullanılabilir:

    # Run the following command to send a `POST` request whose message body is `object=test_obj` to the callback server: 
    curl -d "object=test_obj" http://oss-demo.aliyuncs.com:23450 -v
    # Run the following command to send a `POST` request whose message body is `post.txt` to the callback server: 
    curl -d @post.txt http://oss-demo.aliyuncs.com:23450 -v
    # Run the following command to send a `POST` request whose message body is `post.txt` and which carries the specified message header `Content-Type` to the callback server:
    curl -d @post.txt -H "Content-Type: application/json" http://oss-demo.aliyuncs.com:23450 -v
    Not
    • Geri arama sunucusunda hata ayıklarken, cURL ile imzalama işlevini simüle etmek zor olduğu için imza doğrulamasını yok sayın.

    • OSS örneği zaten imza doğrulama işlevini sağlar. Bunu doğrudan kullanmanız önerilir.

    • Geri arama sunucusunun, hata ayıklamayı ve izlemeyi kolaylaştırmak için tüm iletileri kaydeden bir günlük kaydı işlevi sağlaması önerilir.

    • Geri arama sunucusu, bir geri arama isteğini doğru şekilde işledikten sonra 20x yerine 200 döndürmelidir.

    • Geri arama sunucusundan OSS'e gönderilen ileti gövdesi JSON biçiminde olmalı ve Content-Type değeri application/json olarak ayarlanmalıdır.

Yaygın hatalar ve nedenleri

  • InvalidArgument

    <Error>
      <Code>InvalidArgument</Code>
      <Message>The callback configuration is not json format.</Message>
      <RequestId>587C79A3DD373E2676F73ECE</RequestId>
      <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      <ArgumentName>callback</ArgumentName>
      <ArgumentValue>{"callbackUrl":"8.8.8.8:9090","callbackBody":"{"bucket":${bucket},"object":${object}}","callbackBodyType":"application/json"}</ArgumentValue>
    </Error>
    Not

    Geri arama parametre ayarları yanlış veya parametre biçimi hatalı. Yaygın bir hata, ArgumentValue içindeki geri arama parametrelerinin geçerli JSON biçiminde olmamasıdır. JSON'da \ ve " kaçış karakterleridir. Örneğin, "callbackBody":"{"bucket":${bucket},"object":${object}}" ifadesi "callbackBody":"{\"bucket\":${bucket},\"object\":${object}}" şeklinde olmalıdır. SDK'lar hakkında daha fazla bilgi için SDK kullanım örneği bölümündeki yükleme geri arama örneklerine bakın.


    Kaçış sonrası karakter


    Kaçış öncesi karakter


    \\


    \\\\


    “


    \\\”


    \b


    \\b


    \f


    \\f


    \n


    \\n


    \r


    \\r


    \t


    \\t

  • CallbackFailed

    CallbackFailed hatası örnekleri aşağıda açıklanmıştır:

    • Örnek 1

      <Error>
        <Code>CallbackFailed</Code>
        <Message>Response body is not valid json format.</Message>
        <RequestId>587C81A125F797621829923D</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      Not

      Geri arama sunucusundan OSS'e gönderilen ileti gövdesi JSON biçiminde değildir. İçeriği curl -d "<Content>" <CallbackServerURL> -v komutunu çalıştırarak veya paket yakalayarak doğrulayabilirsiniz. Windows'ta paket yakalamak için Wireshark, Linux'ta ise tcpdump kullanmanız önerilir. Geçersiz döndürülen iletiler şunları içerir: OK ve \357\273\277{"Status":"OK"} (ef bb bf baytlarını içeren BOM başlığı).

    • Örnek 2

      <Error>
        <Code>CallbackFailed</Code>
        <Message>Error status : -1. OSS can not connect to your callbackUrl, please check it.</Message>
        <RequestId>587C8735355BE8694A8E9100</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      Not

      Geri arama sunucusunun işleme süresi beş saniyeyi aşar. Bu nedenle OSS, bir zaman aşımı oluştuğunu belirler. Geri arama sunucusunun işleme mantığını, beş saniye içinde işlemi tamamlayıp sonucu OSS'e döndürebilecek şekilde eşzamansız işleme olarak değiştirmeniz önerilir.

    • Örnek 3

      <Error>
        <Code>CallbackFailed</Code>
        <Message> error status:-1 8.8.8.8: 9090 reply timeout, cost: 5000 MS, timeout: 5000 MS (Ernest-4, errno170) </message>
        <RequestId>587C8D382AE0B92FA3EEF62C</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      Not

      Geri arama sunucusunun işleme süresi beş saniyeyi aşar. Bu nedenle OSS, bir zaman aşımı oluştuğunu belirler.

    • Örnek 4

      <Error>
        <Code>CallbackFailed</Code>
        <Message>Error status : 400.</Message>
        <RequestId>587C89A02AE0B92FA3C7981D</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      Not

      Geri arama sunucusundan OSS'e gönderilen iletinin durum kodu 400 değerindedir. Geri arama sunucusunun işleme mantığını kontrol edin.

    • Örnek 5

      <Error>
        <Code>CallbackFailed</Code>
        <Message>Error status : 502.</Message>
        <RequestId>587C8D382AE0B92FA3EEF62C</RequestId>
        <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
      </Error>
      Not

      Geri arama sunucusu başlatılmamış, geri arama parametrelerinde CallbackUrl eksik veya OSS örneği ile geri arama sunucusu arasındaki ağ bağlantısı kesilmiş. Trafik maliyetinden tasarruf etmek ve ağ kalitesini garanti altına almak için geri arama sunucusunu, OSS ile aynı intranette bulunan bir ECS üzerine dağıtmanız önerilir.

  • Yanıt gövdesi JSON biçiminde değil.

    Örneğin:

    Bu hata aşağıdaki nedenlerden kaynaklanabilir:

    • Uygulama sunucusunun OSS'e döndürdüğü yanıt gövdesi JSON biçiminde değildir; aşağıdaki şekilde gösterildiği gibi:

      resp_body geçerli JSON biçiminde değilse OSS hata bildirir. Ayrıca, bu hata diğer alt düzey faktörlerden de kaynaklanabilir; örneğin, uygulama sunucusunun özel durumlar nedeniyle OSS'e normal bir yanıt yerine bir yığın izi döndürmesi.

    • Uygulama sunucusunun OSS'e döndürdüğü yanıt gövdesi başlıkta bir BOM taşır.

      Bu sorun genellikle PHP ile kodlanmış uygulama sunucularında ortaya çıkar; bu sunucular OSS'e döndürülen yanıtta bir BOM başlığı içerir. Bu nedenle, yanıtta JSON biçimine uymayan üç ek bayt (yani BOM başlığı) bulunduğundan OSS hata bildirir. Aşağıdaki şekilde, uygulama sunucusu tarafından gönderilen paketteki içerik gösterilmektedir.

      Yukarıdaki şekilde, ef bb bf baytları BOM başlığının üç ek baytını temsil eder.

      Not

      Bu sorunu çözmek için, uygulama sunucusunun OSS'e döndürdüğü yanıtta BOM başlığını kaldırın.

  • Hata durumu

    502 ve 400 gibi hata durumu kodları, aşağıdaki şekilde gösterildiği gibi hatalı geri arama işlevleri nedeniyle döndürülen hatalardır.

    Not

    400, 404 veya 403 gibi bir hata durumu kodu, uygulama sunucusunun OSS'e döndürdüğü HTTP durumunu belirtir. 200 durum kodunun döndürülmesi, işlemin başarılı olduğunu gösterir.

    Uygulama sunucusunda Web hizmeti etkinleştirilmemişse, yani sunucu OSS tarafından gönderilen geri arama isteğini alamıyorsa 502 hata durumu kodu döndürülür.

  • Zaman aşımı

    Aşağıdaki şekilde bir zaman aşımı hatası gösterilmektedir.

    Not

    Güvenlik nedenleriyle, OSS geri arama yanıtını en fazla 5 saniye bekler. Yanıt döndürülmezse OSS, uygulama sunucusuyla bağlantıyı keser ve istemciye bir zaman aşımı hatası döndürür. Hata mesajındaki IP adresi dikkate alınmayabilir.