：Bagaimana cara saya menangani kesalahan callback unggah?

Tentang callback unggah

Saat file diunggah, OSS dapat memberikan Callback ke server callback Anda. Anda dapat membawa parameter callback yang relevan dalam permintaan unggah untuk mengimplementasikan callback unggah. API yang mendukung callback unggah adalah PutObject, PostObject, dan CompleteMultipartUpload. Untuk informasi lebih lanjut, lihat Callback Unggah dan API Callback di Panduan Pengembang.

Skenario aplikasi

Aliran data

Tabel berikut menjelaskan aliran data.

SDK/PostObject

Selama pengunggahan file, Anda dapat mengatur parameter callback untuk menentukan URL server callback, data yang akan dikirim ke server callback, dan format data. Saat server callback memproses callback, beberapa informasi konteks seperti bucket dan object ditentukan menggunakan variabel sistem. Informasi konteks lainnya ditentukan menggunakan variabel kustom.

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

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

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

Variabel sistem dan variabel kustom

Variabel untuk CallbackJson, seperti ${bucket}, ${object}, dan ${size}, dalam contoh CallbackJson adalah variabel sistem yang didefinisikan oleh OSS. Selama callback, OSS mengganti variabel sistem dengan nilai aktual. Tabel berikut mencantumkan variabel sistem yang didefinisikan oleh OSS.

Variabel untuk CallbackJson, seperti ${x:my_var}, dalam contoh CallbackJson adalah variabel kustom. Selama callback, OSS mengganti variabel kustom dengan nilai kustom. Nilai variabel kustom didefinisikan dan dibawa oleh permintaan unggah dengan salah satu dari dua cara berikut:

• Variabel kustom dibawa oleh x-oss-callback-var dalam header pesan. Ini adalah cara yang umum dan direkomendasikan.

• Variabel kustom dibawa oleh callback-var dalam QueryString.

Aturan untuk menghasilkan nilai x-oss-callback-var atau callback-var adalah sebagai berikut:

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

Contoh nilai CallbackVarJson adalah sebagai berikut:

    "x:my_var1" : "value1",
    "x:my_var2" : "value2"
            

Contoh penggunaan SDK

Beberapa SDK, seperti JAVA dan JS, mengenkapsulasi langkah-langkah sebelumnya. Beberapa SDK, seperti Python, PHP, dan C, perlu menggunakan aturan sebelumnya untuk menghasilkan parameter callback unggah dan variabel kustom. Tabel berikut mencantumkan contoh penggunaan SDK.

Contoh penggunaan PostObject

PostObject mendukung callback unggah, yang mana parameter callback dibawa oleh bidang formulir callback dan variabel kustom dibawa oleh bidang formulir independen. Untuk informasi lebih lanjut, lihat PostObjet.

Tabel berikut mencantumkan contoh penggunaan PostObject.

Server callback

Server callback adalah server HTTP yang memproses permintaan callback dan pesan POST yang dikirim dari OSS. URL server callback adalah nilai dari parameter callback unggah callbackUrl. Anda dapat mengimplementasikan logika pemrosesan Anda sendiri pada server callback untuk pencatatan, tinjauan, pemrosesan, dan statistik data yang diunggah.

Prosedur debugging

Debugging callback unggah mencakup debugging klien yang mengunggah file dan server callback yang memproses callback. Kami merekomendasikan agar Anda mendebag klien terlebih dahulu, lalu server callback. Setelah mendebag dua bagian secara mandiri, lakukan callback unggah lengkap.

• Debugging Klien

  Anda dapat menggunakan server callback http://oss-demo.aliyuncs.com:23450 yang disediakan oleh OSS, yaitu parameter callback callbackUrl untuk mendebag klien. Server callback hanya memverifikasi tanda tangan permintaan callback, dan tidak memproses permintaan callback. Untuk permintaan callback yang tanda tangannya berhasil diverifikasi, server callback mengembalikan {"Status":"OK"}. Untuk permintaan callback yang tanda tangannya gagal diverifikasi, server callback mengembalikan 400 Bad Request. Untuk permintaan non-POST, server callback mengembalikan 501 Unsupported method. Untuk informasi lebih lanjut tentang kode contoh server callback, lihat callback_app_server.py.zip.

• Debugging Server Callback

  Server callback adalah server HTTP yang dapat memproses permintaan POST. Anda dapat memodifikasi server callback berdasarkan contoh yang disediakan oleh OSS atau mengimplementasikannya sendiri. Tabel berikut menjelaskan contoh server callback yang disediakan oleh OSS.

  Bahasa	Contoh	Cara menjalankan
  JAVA	AppCallbackServer.zip	Ekstrak paket dan jalankan java -jar oss-callback-server-demo.jar 9000.
  PHP	callback-php-demo.zip	Sebarkan dan jalankan program dalam lingkungan Apache
  Python	callback_app_server.py.zip	Ekstrak paket dan jalankan python callback_app_server.py.
  C#	callback-server-dotnet.zip	Kompilasi program dan jalankan aliyun-oss-net-callback-server.exe 127.0.0.1 80.
  Go	callback-server-go.zip	Kompilasi program dan jalankan aliyun_oss_callback_server.
  Ruby	oss-callback-server	Jalankan ruby aliyun_oss_callback_server.rb.

  Server callback dapat didedug dengan menjalankan perintah cURL. Perintah berikut mungkin digunakan:

  # Jalankan perintah berikut untuk mengirimkan permintaan `POST` yang badan pesannya adalah `object=test_obj` ke server callback: 
  curl -d "object=test_obj" http://oss-demo.aliyuncs.com:23450 -v
  # Jalankan perintah berikut untuk mengirimkan permintaan `POST` yang badan pesannya adalah `post.txt` ke server callback: 
  curl -d @post.txt http://oss-demo.aliyuncs.com:23450 -v
  # Jalankan perintah berikut untuk mengirimkan permintaan `POST` yang badan pesannya adalah `post.txt` dan membawa header pesan `Content-Type` yang ditentukan ke server callback:
  curl -d @post.txt -H "Content-Type: application/json" http://oss-demo.aliyuncs.com:23450 -v

  Catatan

  • Saat mendebag server callback, abaikan verifikasi tanda tangan karena sulit bagi cURL untuk mensimulasikan fungsi tanda tangan.

  • Contoh OSS sudah menyediakan fungsi verifikasi tanda tangan. Kami merekomendasikan agar Anda langsung menggunakannya.

  • Kami merekomendasikan agar server callback menyediakan fungsi logging untuk mencatat semua pesan, memudahkan debugging dan pelacakan.

  • Setelah memproses permintaan callback dengan benar, server callback harus mengembalikan 200 bukan 20x.

  • Badan pesan yang dikirim dari server callback ke OSS harus dalam format JSON, danContent-Type diatur ke application/json.

Kesalahan umum dan penyebabnya

• InvalidArgument

  <Error>
    <Code>InvalidArgument</Code>
    <Message>Konfigurasi callback bukan dalam format json.</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>

  Catatan

  Pengaturan parameter callback salah, atau format parameternya tidak valid. Kesalahan umum adalah bahwa parameter callback dalam ArgumentValue tidak dalam format JSON yang valid. Dalam JSON, \ dan " adalah karakter escape. Sebagai contoh, "callbackBody":"{"bucket":${bucket},"object":${object}}" harus menjadi "callbackBody":"{\"bucket\":${bucket},\"object\":${object}}". Untuk informasi lebih lanjut tentang SDK, lihat contoh callback unggah di bagian Contoh Penggunaan SDK.

  Karakter setelah escape	Karakter sebelum escape
  \\	\\\\
  “	\\\”
  \b	\\b
  \f	\\f
  \n	\\n
  \r	\\r
  \t	\\t

• CallbackFailed

  Contoh kesalahan CallbackFailed dijelaskan sebagai berikut:

  • Contoh 1

    <Error>
      <Code>CallbackFailed</Code>
      <Message>Badan respons bukan dalam format json yang valid.</Message>
      <RequestId>587C81A125F797621829923D</RequestId>
      <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
    </Error>

    Catatan

    Badan pesan yang dikirim dari server callback ke OSS tidak dalam format JSON. Anda dapat mengonfirmasi isi dengan menjalankan curl -d "<Content>" <CallbackServerURL> -v atau menangkap paket. Kami merekomendasikan agar Anda menggunakan Wireshark untuk menangkap paket di Windows, dan menggunakan tcpdump untuk menangkap paket di Linux. Pesan yang dikembalikan tidak valid termasuk: OK dan \357\273\277{"Status":"OK"} (header BOM yang berisi byte ef bb bf).

  • Contoh 2

    <Error>
      <Code>CallbackFailed</Code>
      <Message>Status error : -1. OSS tidak dapat terhubung ke callbackUrl Anda, silakan periksa.</Message>
      <RequestId>587C8735355BE8694A8E9100</RequestId>
      <HostId>bucket.oss-cn-hangzhou.aliyuncs.com</HostId>
    </Error>

    Catatan

    Waktu pemrosesan server callback melebihi lima detik. Oleh karena itu, OSS menentukan bahwa waktu habis terjadi. Kami merekomendasikan agar Anda memodifikasi logika pemrosesan server callback menjadi pemrosesan asinkron untuk memastikan bahwa ia dapat menyelesaikan pemrosesan dalam lima detik dan mengembalikan hasil ke OSS.

  • Contoh 3

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

    Catatan

    Waktu pemrosesan server callback melebihi lima detik. Oleh karena itu, OSS menentukan bahwa waktu habis terjadi.

  • Contoh 4

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

    Catatan

    Kode status pesan yang dikirim dari server callback ke OSS adalah 400. Periksa logika pemrosesan server callback.

  • Contoh 5

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

    Catatan

    Server callback tidak dimulai, CallbackUrl hilang dalam parameter callback, atau jaringan antara instansi OSS dan server callback terputus. Kami merekomendasikan agar Anda menyebarkan server callback di ECS, yang termasuk dalam intranet yang sama dengan OSS, untuk menghemat biaya lalu lintas dan menjamin kualitas jaringan.

• Badan respons bukan dalam format JSON.

  Sebagai contoh:

  

  Kesalahan ini mungkin disebabkan oleh alasan berikut:

  • Badan respons yang dikembalikan oleh server aplikasi ke OSS tidak dalam format JSON, seperti yang ditunjukkan pada gambar berikut:

    OSS melaporkan kesalahan jika resp_body tidak dalam format JSON yang valid. Selain itu, kesalahan ini mungkin disebabkan oleh faktor-faktor dasar lainnya, seperti server aplikasi mengembalikan jejak stack alih-alih respons normal ke OSS karena pengecualian.

  • Badan respons yang dikembalikan oleh server aplikasi ke OSS membawa BOM di header.

    Masalah ini umumnya terjadi di server aplikasi yang dikodekan dalam PHP, yang menyertakan header BOM dalam respons yang dikembalikan ke OSS. Oleh karena itu, OSS melaporkan kesalahan karena tiga byte tambahan (yaitu, header BOM) disertakan dalam respons, yang tidak sesuai dengan format JSON. Gambar berikut menunjukkan konten yang disertakan dalam paket yang dikirim oleh server aplikasi.

    

    Dalam gambar sebelumnya, byte ef bb bf adalah tiga byte tambahan dari header BOM.

    Catatan

    Untuk menyelesaikan masalah ini, hapus header BOM dalam respons yang dikembalikan oleh server aplikasi ke OSS.

• Status Error

  Kode status error, seperti 502 dan 400, adalah kesalahan yang dikembalikan karena fungsi callback yang salah, seperti yang ditunjukkan pada gambar berikut.

  

  Catatan

  Kode status error, seperti 400, 404, atau 403, dikembalikan untuk menunjukkan status HTTP yang dikembalikan oleh server aplikasi ke OSS. Pengembalian kode status 200 menunjukkan operasi berhasil.

  Kode status error 502 dikembalikan ketika layanan Web tidak diaktifkan pada server aplikasi, artinya server tidak dapat menerima permintaan callback yang dikirim oleh OSS.

• Waktu Habis

  Gambar berikut menunjukkan kesalahan waktu habis.

  

  Catatan

  Untuk alasan keamanan, OSS menunggu untuk menerima respons callback maksimal selama 5 detik. Jika respons tidak dikembalikan, OSS memutuskan koneksi dengan server aplikasi dan mengembalikan kesalahan waktu habis ke klien. Alamat IP yang disertakan dalam pesan kesalahan dapat diabaikan.