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.
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 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. |
|
4 | OSS, yükleme ve geri arama sonucunu döndürür. |
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Yükleme geri arama parametreleri, yükleme isteğine aşağıdaki iki yoldan biriyle eklenir:
Geri arama parametreleri, ileti üstbilgisindeki
x-oss-callbackile taşınır. Bu yaygın ve önerilen bir yöntemdir.Geri arama parametreleri, QueryString'deki
callbackile 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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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-varile taşınır. Bu yaygın ve önerilen bir yöntemdir.Özel değişkenler, QueryString'deki
callback-varile 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"
Ö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 |
| |
Python | - | |
PHP | $options içindeki | |
C # |
| |
JS | - | |
C | - | |
Ruby | - | |
iOS |
| |
Android |
|
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.
|
|
|
|
|
|
|
|
|
|
|
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ı.
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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:23450geri arama sunucusunu, yanicallbackUrlgeri 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 sunucu400 Bad Requestdöndürür. POST dışı istekler için sunucu501 Unsupported methoddö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
Paketi açın vejava -jar oss-callback-server-demo.jar 9000komutunu çalıştırın.
PHP
Programı Apache ortamında dağıtın ve çalıştırın.
Python
Paketi açın vepython callback_app_server.pykomutunu çalıştırın.
C#
Programı derleyin vealiyun-oss-net-callback-server.exe 127.0.0.1 80komutunu çalıştırın.
Go
Programı derleyin vealiyun_oss_callback_serverkomutunu çalıştırın.
Rubyruby aliyun_oss_callback_server.rbkomutunu ç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 -vNotGeri arama sunucusunda hata ayıklarken,
cURLile 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
200döndürmelidir.Geri arama sunucusundan OSS'e gönderilen ileti gövdesi JSON biçiminde olmalı ve
Content-Typedeğeriapplication/jsonolarak 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>NotGeri arama parametre ayarları yanlış veya parametre biçimi hatalı. Yaygın bir hata,
ArgumentValueiç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>NotGeri arama sunucusundan OSS'e gönderilen ileti gövdesi JSON biçiminde değildir. İçeriği
curl -d "<Content>" <CallbackServerURL> -vkomutunu ç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:OKve\357\273\277{"Status":"OK"}(ef bb bfbaytları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>NotGeri 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>NotGeri 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>NotGeri arama sunucusundan OSS'e gönderilen iletinin durum kodu
400değ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>NotGeri arama sunucusu başlatılmamış, geri arama parametrelerinde
CallbackUrleksik 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 bfbaytları BOM başlığının üç ek baytını temsil eder.NotBu 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.
Not400, 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.
NotGü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.