All Products
Search
Document Center

Object Storage Service:Callback

Last Updated:Jun 03, 2026

OSS dapat memicu callback setelah unggahan file untuk memberi tahu server aplikasi Anda guna melakukan pemrosesan pasca-unggahan.

Batasan

  • Ketersediaan wilayah

    Callback didukung di: Tiongkok (Hangzhou), Tiongkok (Shanghai), Tiongkok (Qingdao), Tiongkok (Beijing), Tiongkok (Zhangjiakou), Tiongkok (Hohhot), Tiongkok (Ulanqab), Tiongkok (Shenzhen), Tiongkok (Heyuan), Tiongkok (Guangzhou), Tiongkok (Chengdu), Tiongkok (Hong Kong), AS (Silicon Valley), AS (Virginia), Jepang (Tokyo), Singapura, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Filipina (Manila), Jerman (Frankfurt), Inggris (London), dan UEA (Dubai).

  • Perilaku callback

    • Permintaan callback harus menerima respons dalam waktu 5 detik. Jika tidak, permintaan akan timeout dan gagal.

    • Kegagalan callback tidak memengaruhi penyelesaian unggahan file.

    • Callback yang gagal tidak secara otomatis dicoba ulang.

  • Operasi API yang didukung

    Operasi PutObject, PostObject, dan CompleteMultipartUpload mendukung callback. File upload manager SDK V2 dan URL yang ditandatangani juga mendukung callback.

Cara kerja

Proses callback:

  1. Unggah file dengan parameter callback

    Klien menyertakan parameter callback yang menentukan URL server aplikasi dan konten badan callback. Anda juga dapat menyertakan parameter opsional callback-var untuk variabel kustom.

  2. OSS menyimpan file dan mengirim permintaan callback

    Setelah file diunggah, OSS mengirim permintaan POST ke URL callback dengan informasi file (bucket, object, ukuran, ETag) dan parameter kustom.

  3. Server memproses callback dan merespons

    Server Anda menerima callback, secara opsional memverifikasi signature permintaan, dan harus mengembalikan respons JSON dalam waktu 5 detik. HTTP 200 menunjukkan keberhasilan; kode status lainnya berarti kegagalan.

  4. OSS mengembalikan hasil unggahan

    OSS meneruskan badan respons server kembali ke klien sebagai hasil unggahan.

Implementasi

Implementasikan dan uji sisi klien serta sisi server secara terpisah, lalu jalankan pengujian integrasi end-to-end.

Implementasi sisi klien

Bagian ini mencakup pembuatan parameter callback. Untuk memulai lebih cepat, gunakan contoh SDK di bawah ini.

Sertakan parameter callback dan parameter opsional callback-var dalam permintaan unggahan Anda.

  1. Buat parameter callback

    Parameter ini merupakan objek JSON yang diencode Base64 yang mendefinisikan URL server aplikasi dan format badan permintaan.

    1. Contoh konfigurasi dasar:

      {
      "callbackUrl":"http://oss-demo.aliyuncs.com:23450",
      "callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}"
      }

      Dalam contoh ini:

      • callbackUrl: URL server aplikasi. Anda harus mengganti ini dengan URL aktual Anda. Contoh: http://oss-demo.aliyuncs.com:23450.

      • callbackBody: Konten badan permintaan callback. Gunakan placeholder seperti ${bucket} untuk nama bucket, ${object} untuk jalur file lengkap, dan ${x:xxx} untuk variabel kustom. OSS mengganti placeholder dengan nilai aktual selama callback. Placeholder yang didukung tercantum di Parameter sistem untuk callbackBody.

    2. Contoh konfigurasi lanjutan:

      {
      "callbackUrl":"http://oss-demo.aliyuncs.com:23450",
      "callbackHost":"oss-cn-hangzhou.aliyuncs.com",
      "callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}",
      "callbackBodyType":"application/x-www-form-urlencoded",
      "callbackSNI":false
      }

      Setiap bidang dijelaskan di Parameter callback.

  2. Buat parameter callback-var opsional

    Penting

    Parameter callback-var harus dalam format JSON. Kunci untuk setiap parameter kustom harus diawali dengan x: dan hanya boleh berisi huruf kecil, misalnya x:uid.

    Gunakan parameter ini untuk mengirim informasi kustom ke server aplikasi Anda, seperti ID pengguna atau nomor pesanan:

    {
      "x:uid": "12345",
      "x:order_id": "67890"
    }

    Parameter callback-var bekerja bersama callbackBody. Rujuk variabel kustom menggunakan placeholder ${x:xxx} di callbackBody:

    {
      "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
      "callbackBody": "uid=${x:uid}&order=${x:order_id}"
    }

    Saat callback dipicu, OSS mengirim konten berikut, dengan asumsi callbackBodyType adalah application/x-www-form-urlencoded:

    uid=12345&order=67890
  3. Encode Base64 parameter callback dan callback-var

    • Contoh: Encode parameter callback

      Parameter callback asli:

      {
          "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
          "callbackHost": "your.callback.com",
          "callbackBody": "bucket=${bucket}&object=${object}&uid=${x:uid}&order=${x:order_id}",
          "callbackBodyType": "application/x-www-form-urlencoded",
          "callbackSNI": false
      }

      Hasil encode Base64:

      eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9
    • Contoh: Encode parameter callback-var

      Parameter callback-var asli:

      {
        "x:uid": "12345",
        "x:order_id": "67890"
      }

      Hasil encode Base64:

      eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=
  4. Sambungkan parameter yang telah diencode ke permintaan Anda

    Setelah mengencode parameter, Anda dapat mengirimkannya ke OSS dengan salah satu cara berikut.

    Header (direkomendasikan)

    Direkomendasikan untuk unggahan SDK atau backend. Kirim parameter callback dalam header HTTP x-oss-callback dan x-oss-callback-var:

    • x-oss-callback: Parameter callback yang telah diencode Base64.

    • x-oss-callback-var (opsional): Parameter callback-var yang telah diencode Base64.

    Catatan: Anda harus menyertakan dua header ini dalam canonical headers saat menghitung signature permintaan.

    Contoh: Kirim parameter callback dalam header

    PUT /your_object HTTP/1.1
    Host: callback-test.oss-test.aliyun-inc.com
    Accept-Encoding: identity
    Content-Length: 5
    x-oss-callback-var: eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=
    User-Agent: aliyun-sdk-python/0.4.0 (Linux/2.6.32-220.23.2.ali1089.el5.x86_64/x86_64;2.5.4)
    x-oss-callback: eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9
    Host: callback-test.oss-test.aliyun-inc.com
    Expect: 100-Continue
    Date: Wed, 26 Apr 2023 03:46:17 GMT
    Content-Type: text/plain
    Authorization: OSS qn6q**************:77Dv****************
    Test

    Badan POST

    Metode ini hanya berlaku untuk unggahan yang menggunakan operasi API PostObject. Parameter callback harus dikirim sebagai field form dalam badan permintaan POST.

    • Parameter callback: Kirim konfigurasi JSON yang telah diencode Base64 sebagai field form terpisah.

      --9431149156168
      Content-Disposition: form-data; name="callback"
      eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9
    • Parameter callback-var (variabel kustom): Setiap parameter kustom harus dikirim sebagai field form terpisah; Anda tidak dapat menggabungkannya dalam satu field callback-var.

      Sebagai contoh, pertimbangkan variabel kustom uid dan order_id:

      {
        "x:uid": "12345",
        "x:order_id": "67890"
      }

      Anda harus mengonversinya menjadi dua field form terpisah.

      --9431149156168
      Content-Disposition: form-data; name="x:uid"
      12345
      --9431149156168
      Content-Disposition: form-data; name="x:order_id"
      67890
    • Validasi parameter callback (opsional): Anda dapat menentukan kondisi dalam policy untuk memvalidasi parameter callback. Jika tidak ada kondisi yang ditetapkan, parameter tidak divalidasi selama unggahan. Contoh:

      { "expiration": "2021-12-01T12:00:00.000Z",
        "conditions": [
          {"bucket": "examplebucket" },
          {"callback": "eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9"},
          ["starts-with", "$key", "user/eric/"]
        ]
      }

    URL

    • Digunakan untuk mengunggah file dengan URL yang ditandatangani. Memicu callback dengan menambahkan parameter callback yang telah diencode Base64 ke URL. Ini mengekspos informasi callback di URL, jadi gunakan hanya untuk akses sementara atau skenario dengan sensitivitas rendah.

    • Jika Anda mengirim parameter callback dalam URL, sertakan parameter callback (wajib) dan opsional callback-var. Keduanya harus menjadi bagian dari Canonical Query String untuk perhitungan signature. Signature Version 4.

      Contoh:

      PUT /your_object?OSSAccessKeyId=LTAI******************&Signature=vjby*************************************&Expires=1682484377&callback-var=eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=&callback=eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9 HTTP/1.1
      Host: callback-test.oss-cn-hangzhou.aliyuncs.com
      Date: Wed, 26 Apr 2023 03:46:17 GMT
      Content-Length: 5
      Content-Type: text/plain

Implementasi sisi server

Untuk contoh kode dalam berbagai bahasa, lihat Contoh kode sisi server.

Server aplikasi Anda harus:

  1. Menerima permintaan POST dari OSS

    Setelah unggahan berhasil, OSS mengirim permintaan POST ke URL callback Anda:

    POST /test HTTP/1.1
    Host: your.callback.com
    Connection: close
    Authorization: GevnM3**********3j7AKluzWnubHSVWI4dY3VsIfUHYWnyw==
    Content-MD5: iKU/O/JB***ZMd8Ftg==
    Content-Type: application/x-www-form-urlencoded
    Date: Tue, 07 May 2024 03:06:13 GMT
    User-Agent: aliyun-oss-callback
    x-oss-bucket: your_bucket
    x-oss-pub-key-url: aHR0cHM6Ly9nb3NzcHVi**********vY2FsbGJeV92MS5wZW0=
    x-oss-request-id: 66399AA50*****3334673EC2
    x-oss-requester: 23313******948342006
    x-oss-signature-version: 1.0
    x-oss-tag: CALLBACK
    bucket=your_bucket&object=your_object&uid=12345&order_id=67890
  2. Verifikasi signature permintaan demi keamanan (opsional)

    Untuk memastikan permintaan berasal dari OSS, verifikasi signature-nya di server aplikasi Anda. Lihat Konfigurasi yang direkomendasikan.

    Catatan

    Verifikasi signature bersifat opsional.

  3. Kembalikan respons callback

    Server aplikasi Anda harus mengembalikan respons ke OSS yang memenuhi persyaratan berikut:

    • Server aplikasi harus mengembalikan HTTP/1.1 200 OK.

    • Header respons harus menyertakan Content-Length.

    • Badan respons mendukung format JSON atau XML. Contoh dalam topik ini menggunakan JSON. Untuk XML, tambahkan Content-Type: application/xml ke header respons.

    Sebagai contoh, server aplikasi dapat mengembalikan {"Status": "OK"}.

    Catatan: Contoh ini menggunakan Python 2.7.6. Kami merekomendasikan penggunaan Python 3 untuk pengembangan baru.

    HTTP/1.0 200 OK
    Server: BaseHTTP/0.3 Python/2.7.6
    Date: Mon, 14 Sep 2015 12:37:27 GMT
    Content-Type: application/json
    Content-Length: 9
    {"Status": "OK"}

    OSS kemudian meneruskan badan respons ini ke klien. Kode berikut menunjukkan contohnya:

    HTTP/1.1 200 OK
    Date: Mon, 14 Sep 2015 12:37:27 GMT
    Content-Type: application/json
    Content-Length: 9
    Connection: keep-alive
    ETag: "D8E8FCA2DC0F896FD7CB4CB0031BA249"
    Server: AliyunOSS
    x-oss-bucket-version: 1442231779
    x-oss-request-id: 55F6BF87207FB30F2640C548
    {"Status": "OK"}
    Penting

    Untuk permintaan CompleteMultipartUpload, jika badan respons asli berisi konten (misalnya, informasi dalam format JSON), konten tersebut akan ditimpa oleh respons dari upload callback setelah fitur diaktifkan, misalnya oleh {"Status": "OK"}.

Konfigurasi yang direkomendasikan

Verifikasi signature permintaan

OSS mengirim permintaan POST ke callbackUrl Anda setelah unggahan. Verifikasi signature permintaan untuk memastikan permintaan berasal dari OSS.

  1. Cara OSS menandatangani permintaan callback

    OSS menandatangani permintaan menggunakan RSA dengan hash MD5 dan menempatkan signature yang diencode Base64 di header authorization.

    • Signature dihitung sebagai berikut:

      authorization = base64_encode(rsa_sign(private_key, url_decode(path) + query_string + '\n' + body, md5))
      Catatan

      Dalam rumus ini, private_key adalah kunci privat, path adalah jalur sumber daya permintaan callback, query_string adalah string kueri, dan body adalah badan callback.

    • Langkah-langkah untuk menghasilkan signature:

      1. Buat string yang akan ditandatangani dengan menggabungkan jalur sumber daya yang telah didecode URL-nya, string kueri asli, karakter baris baru, dan badan callback.

      2. Tandatangani string dengan RSA: Gunakan kunci untuk menandatangani string. Fungsi hash untuk signature adalah MD5.

      3. Encode Base64 hasil yang telah ditandatangani untuk mendapatkan signature akhir, lalu tempatkan signature tersebut di header authorization permintaan callback.

    • Contoh pembuatan signature:

      POST /index.php?id=1&index=2 HTTP/1.0
      Host: 172.16.XX.XX
      Connection: close
      Content-Length: 18
      authorization: kKQeGTRccDKyHB3H9vF+xYMSrmhMZj****/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****
      Content-Type: application/x-www-form-urlencoded
      User-Agent: http-client/0.0.1
      x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnsr****
      bucket=examplebucket

      Jalurnya adalah /index.php, query_string-nya adalah ?id=1&index=2, badannya adalah bucket=examplebucket, dan hasil signature akhirnya adalah kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****.

  2. Cara Server Anda Memverifikasi Tanda Tangan

    Verifikasi signature permintaan untuk memastikan keasliannya:

    1. Dapatkan kunci publik:

      Ambil dan decode Base64 URL kunci publik dari header permintaan x-oss-pub-key-url.

      public_key = urlopen(base64_decode(value of x-oss-pub-key-url header))

      Contoh nilai sebelum decoding:

      aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ==

      Setelah decoding:

      http://gosspublic.alicdn.com/callback_pub_key_v1.pem
      Catatan

      URL kunci publik harus diawali dengan http://gosspublic.alicdn.com/ atau https://gosspublic.alicdn.com/. Simpan cache kunci publik secara lokal untuk menghindari gangguan akibat masalah jaringan.

    2. Decode signature.

      Ambil dan decode Base64 signature dari header permintaan authorization:

      signature = base64_decode(value of authorization header)
    3. Buat string untuk verifikasi.

      Gabungkan jalur sumber daya, string kueri, karakter baris baru, dan badan callback dalam format berikut:

      sign_str = url_decode(path) + query_string + ‘\n’ + body
    4. Verifikasi tanda tangan.

      Gunakan hash MD5 dengan kunci publik RSA untuk verifikasi:

      result = rsa_verify(public_key, md5(sign_str), signature)
  3. Contoh Verifikasi Tanda Tangan

    Contoh berikut dalam Python 3 menunjukkan cara memverifikasi signature di server aplikasi. Contoh ini memerlukan library M2Crypto.

    import http.client
    import base64
    import hashlib
    import urllib.request
    import urllib.parse
    import socket
    from http.server import BaseHTTPRequestHandler, HTTPServer
    from M2Crypto import RSA
    from M2Crypto import BIO
    
    def get_local_ip():
        try:
            csock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
            csock.connect(('8.8.8.8', 80))
            (addr, port) = csock.getsockname()
            csock.close()
            return addr
        except socket.error:
            return ""
    
    class MyHTTPRequestHandler(BaseHTTPRequestHandler):
        '''
        def log_message(self, format, *args):
            return
        '''
        def do_POST(self):
            # Dapatkan kunci publik.
            pub_key_url = ''
            try:
                pub_key_url_base64 = self.headers['x-oss-pub-key-url']
                pub_key_url = base64.b64decode(pub_key_url_base64).decode()
                if not pub_key_url.startswith("http://gosspublic.alicdn.com/") and not pub_key_url.startswith("https://gosspublic.alicdn.com/"):
                    self.send_response(400)
                    self.end_headers()
                    return
                url_reader = urllib.request.urlopen(pub_key_url)
                # Kami merekomendasikan agar Anda menyimpan cache konten kunci publik berdasarkan URL kunci publik untuk meningkatkan performa.
                pub_key = url_reader.read() 
            except Exception as e:
                print('pub_key_url : ' + pub_key_url)
                print('Get pub key failed! Error:', str(e))
                self.send_response(400)
                self.end_headers()
                return
            
            # Dapatkan signature.
            authorization_base64 = self.headers['authorization']
            authorization = base64.b64decode(authorization_base64)
            # Dapatkan badan callback.
            content_length = self.headers['content-length']
            callback_body = self.rfile.read(int(content_length))
            # Susun string untuk verifikasi signature.
            auth_str = ''
            pos = self.path.find('?')
            if -1 == pos:
                auth_str = urllib.parse.unquote(self.path) + '\n' + callback_body.decode()
            else:
                auth_str = urllib.parse.unquote(self.path[0:pos]) + self.path[pos:] + '\n' + callback_body.decode()
            print(auth_str)
            # Verifikasi signature.
            auth_md5 = hashlib.md5(auth_str.encode()).digest()
            bio = BIO.MemoryBuffer(pub_key)
            rsa_pub = RSA.load_pub_key_bio(bio)
            try:
                result = rsa_pub.verify(auth_md5, authorization, 'md5')
            except:
                result = False
            if not result:
                print('Authorization verify failed!')
                print('Public key : %s' % (pub_key))
                print('Auth string : %s' % (auth_str))
                self.send_response(400)
                self.end_headers()
                return
            
            # Proses permintaan berdasarkan badan callback.
            # Respons ke OSS.
            resp_body = '{"Status":"OK"}'
            self.send_response(200)
            self.send_header('Content-Type', 'application/json')
            self.send_header('Content-Length', str(len(resp_body)))
            self.end_headers()
            self.wfile.write(resp_body.encode())
    
    class MyHTTPServer(HTTPServer):
        def __init__(self, host, port):
            super().__init__((host, port), MyHTTPRequestHandler)
    
    if __name__ == '__main__':
        server_ip = get_local_ip()
        server_port = 23451
        server = MyHTTPServer(server_ip, server_port)
        server.serve_forever()

    Tabel berikut mencantumkan kode sisi server untuk bahasa lainnya.

    Bahasa

    Deskripsi

    Java

    • URL unduh: Java

    • Untuk menjalankan aplikasi, ekstrak paket dan jalankan perintah java -jar oss-callback-server-demo.jar 9000 (9000 adalah nomor port, yang dapat Anda ubah).

    Python

    • URL unduh: Python

    • Ekstrak paket dan jalankan python callback_app_server.py. Program ini memerlukan instalasi dependensi RSA.

    PHP

    • URL unduh: PHP

    • Deploy di lingkungan Apache. Beberapa header data berbeda tergantung lingkungan—sesuaikan kode sesuai kebutuhan.

    .NET

    • URL unduh: .NET

    • Untuk menjalankan: Ekstrak paket dan rujuk README.md.

    Node.js

    • URL unduh: Node.js

    • Untuk menjalankan, ekstrak paket dan jalankan node example.js.

    Ruby

    • URL unduh: Ruby

    • Cara menjalankan: ruby aliyun_oss_callback_server.rb

Parameter callback

Tabel berikut menjelaskan parameter callback yang mengonfigurasi permintaan callback yang dikirim OSS setelah unggahan berhasil.

Bidang

Wajib

Deskripsi

callbackUrl

Ya

URL tempat OSS mengirim permintaan POST setelah unggahan file berhasil.

  • Anda dapat mengonfigurasi hingga lima URL, dipisahkan titik koma (;). OSS mengirim permintaan secara berurutan hingga yang pertama mengembalikan respons sukses.

  • URL HTTPS didukung.

  • Anda tidak dapat menentukan alamat IPv6 atau nama domain yang diselesaikan ke alamat IPv6.

  • Untuk memastikan karakter seperti bahasa Tionghoa diproses dengan benar, callbackUrl harus diencode URL. Contoh, https://example.com/中文.php?key=value&中文名称=中文值 harus diencode sebagai https://example.com/%E4%B8%AD%E6%96%87.php?key=value&%E4%B8%AD%E6%96%87%E5%90%8D%E7%A7%B0=%E4%B8%AD%E6%96%87%E5%80%BC.

callbackBody

Ya

Konten badan permintaan callback. Formatnya harus sesuai dengan nilai parameter callbackBodyType:

  • Ketika callbackType bernilai default application/x-www-form-urlencoded, callbackBody harus dalam format pasangan kunci-nilai, contoh: bucket=${bucket}&object=${object}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}

  • Jika callbackType adalah application/json, callbackBody harus dalam format JSON. Contoh: {\"bucket\":${bucket},\"object\":${object},\"mimeType\":${mimeType},\"size\":${size},\"my_var1\":${x:my_var1},\"my_var2\":${x:my_var2}}

callbackBody mendukung referensi ke parameter sistem OSS, variabel kustom, dan konstanta. Untuk deskripsi parameter sistem, lihat Parameter sistem untuk callbackBody.

callbackHost

Tidak

Nilai header Host dalam permintaan callback. Nilainya dapat berupa nama domain atau alamat IP.

  • Jika Anda tidak mengatur callbackHost, OSS mengurai host dari callbackUrl dan menggunakannya sebagai nilai untuk callbackHost.

callbackSNI

Tidak

Menentukan apakah akan menyertakan Server Name Indication (SNI) dalam permintaan callback. SNI digunakan dalam permintaan HTTPS untuk mengidentifikasi nama domain dan mengembalikan sertifikat yang benar.

Jika callbackUrl menggunakan HTTPS, kami merekomendasikan agar Anda mengaktifkan parameter ini. Jika tidak, callback mungkin gagal karena ketidakcocokan sertifikat (misalnya, 502 callback failed). Nilai yang valid adalah:

  • true: Mengirim SNI.

  • false (Default): Tidak mengirim SNI.

    Catatan

    Wilayah Inggris (London) selalu mengirim SNI, terlepas dari pengaturan parameter ini.

callbackBodyType

Tidak

Content-Type permintaan callback, yaitu format data dari callbackBody.

Jenis berikut didukung:

  • application/x-www-form-urlencoded (Default)

    Mengganti variabel dalam callbackBody dengan nilai yang telah diencode URL.

  • application/json

    Mengganti variabel dalam callbackBody dalam format JSON.

Parameter sistem untuk callbackBody

Bidang callbackBody mendukung parameter sistem berikut untuk mengirimkan informasi file yang diunggah dalam permintaan callback.

Parameter

Deskripsi

bucket

Nama bucket.

object

Jalur lengkap objek (file).

etag

ETag file. Nilai ini sama dengan nilai ETag yang dikembalikan kepada pengguna.

size

Ukuran objek. Untuk panggilan CompleteMultipartUpload, ini adalah ukuran seluruh objek.

mimeType

Jenis sumber daya. Misalnya, jenis sumber daya gambar JPEG adalah image/jpeg.

imageInfo.height

Tinggi gambar. Kosong untuk file non-gambar.

imageInfo.width

Lebar gambar. Kosong untuk file non-gambar.

imageInfo.format

Format gambar (JPG, PNG, dll.). Kosong untuk file non-gambar.

crc64

Nilai ini sama dengan nilai header x-oss-hash-crc64ecma yang dikembalikan setelah file diunggah.

contentMd5

Nilai ini sama dengan nilai header Content-MD5 yang dikembalikan setelah file diunggah.

Penting

Variabel ini tidak kosong hanya jika Anda mengunggah file menggunakan operasi API PutObject atau PostObject.

vpcId

ID VPC klien yang melakukan permintaan. Variabel ini kosong jika permintaan tidak berasal dari VPC.

clientIp

Alamat IP klien yang menginisiasi permintaan.

reqId

ID permintaan.

operation

Nama operasi API yang dipanggil, seperti PutObject atau PostObject.

SDK

Demo implementasi callback sisi klien:

Unggahan sederhana

(menggunakan operasi API PutObject)

Unggahan multipart

(menggunakan operasi API CompleteMultipartUpload)

Unggah menggunakan URL yang ditandatangani

(menggunakan operasi API PutObject)

Java

demo

demo

demo

Python V2

demo

-

demo

Go V2

demo

demo

demo

Troubleshooting

Pesan error OSS mencakup kode EC untuk troubleshooting. Kode EC terkait callback tercantum di 07-CALLBACK.

FAQ

Callback saat unggahan gagal

Tidak. Callback hanya dipicu untuk unggahan yang berhasil. Untuk unggahan yang gagal, OSS langsung mengembalikan error ke klien alih-alih memicu callback.

Error format JSON tidak valid

  • Exception pada server aplikasi menyebabkan respons yang dikembalikan tidak dalam format JSON yang valid. Gambar berikut memberikan contohnya.callback

    Solusi:

    • Jalankan perintah berikut untuk memastikan kontennya.

      curl -d "<Content>" <CallbackServerURL> -v
    • Tangkap paket untuk memastikan kontennya.

      Di Windows, kami merekomendasikan penggunaan Wireshark untuk menangkap paket. Di Linux, jalankan perintah tcpdump.

  • Badan yang dikembalikan server aplikasi ke OSS berisi byte order mark (BOM).

    Error ini umum terjadi pada aplikasi PHP. SDK PHP dapat mengembalikan byte order mark (BOM), yang menambahkan tiga byte ekstra ke badan respons dan membuat format JSON tidak valid. Seperti yang ditunjukkan pada gambar berikut, tiga byte ef bb bf adalah BOM.

    callback1

    Solusi: Hapus BOM dari badan respons server aplikasi.