Callback de upload | OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

O OSS pode acionar um callback após o upload de um arquivo para notificar o servidor de aplicação e realizar o processamento pós-upload.

Limitações

Disponibilidade por região

Os callbacks são compatíveis com as seguintes regiões: China (Hangzhou), China (Shanghai), China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Ulanqab), China (Shenzhen), China (Heyuan), China (Guangzhou), China (Chengdu), China (Hong Kong), US (Silicon Valley), US (Virginia), Japan (Tokyo), Singapore, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Germany (Frankfurt), UK (London) e UAE (Dubai).
Comportamento do callback
- Uma solicitação de callback deve receber uma resposta em até 5 segundos. Caso contrário, a solicitação expira e falha.
- Uma falha no callback não afeta a conclusão do upload do arquivo.
- O OSS não repete automaticamente callbacks que falharam.
Operações de API compatíveis

As operações PutObject, PostObject e CompleteMultipartUpload são compatíveis com callbacks. O gerenciador de upload de arquivos do SDK V2 e as URLs pré-assinadas também são compatíveis com callbacks.

Como funciona

O processo de callback:

Faça upload de um arquivo com parâmetros de callback

O cliente inclui parâmetros de callback especificando a URL do servidor de aplicação e o conteúdo do corpo do callback. Você também pode incluir o parâmetro opcional callback-var para variáveis personalizadas.
O OSS armazena o arquivo e envia uma solicitação de callback

Após o upload do arquivo, o OSS envia uma solicitação POST para a URL de callback com informações do arquivo (bucket, objeto, tamanho, ETag) e parâmetros personalizados.
O servidor processa o callback e responde

Seu servidor recebe o callback, opcionalmente verifica a assinatura da solicitação e deve retornar uma resposta JSON em até 5 segundos. HTTP 200 indica sucesso; qualquer outro código de status indica falha.
O OSS retorna o resultado do upload

O OSS encaminha o corpo da resposta do servidor de volta ao cliente como resultado do upload.

Implementação

Implemente e teste o lado do cliente e o lado do servidor separadamente. Em seguida, execute um teste de integração completo.

Implementação do lado do cliente

Estas seções abordam a construção dos parâmetros de callback. Para começar mais rapidamente, use os exemplos de SDK abaixo.

Inclua o parâmetro callback e o parâmetro opcional callback-var na solicitação de upload.

Construa o parâmetro de callback

Esse parâmetro é um objeto JSON codificado em Base64 que define a URL do servidor de aplicação e o formato do corpo da solicitação.
1. Exemplo de configuração básica:
```
{
"callbackUrl":"http://oss-demo.aliyuncs.com:23450",
"callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}"
}
```
  Neste exemplo:
  - callbackUrl: A URL do servidor de aplicação. Altere para a sua URL real. Por exemplo: http://oss-demo.aliyuncs.com:23450.
  - callbackBody: O conteúdo do corpo da solicitação de callback. Use placeholders como ${bucket} para o nome do bucket, ${object} para o caminho completo do arquivo e ${x:xxx} para variáveis personalizadas. O OSS substitui os placeholders pelos valores reais durante o callback. Os placeholders compatíveis estão listados em Parâmetros do sistema para callbackBody.
2. Exemplo de configuração avançada:
```
{
"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
}
```
  Cada campo está descrito em Parâmetros de callback.
Construa o parâmetro opcional callback-var

null
O parâmetro callback-var deve estar no formato JSON. A chave de cada parâmetro personalizado deve começar com x: e pode conter apenas letras minúsculas, por exemplo, x:uid.

Use esse parâmetro para enviar informações personalizadas ao servidor de aplicação, como um ID de usuário ou número de pedido:
```
{
  "x:uid": "12345",
  "x:order_id": "67890"
}
```
O parâmetro callback-var funciona em conjunto com callbackBody. Referencie variáveis personalizadas usando o placeholder ${x:xxx} em callbackBody:
```
{
  "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
  "callbackBody": "uid=${x:uid}&order=${x:order_id}"
}
```
Quando o callback é acionado, o OSS envia o seguinte conteúdo, considerando que callbackBodyType é application/x-www-form-urlencoded:
```
uid=12345&order=67890
```

Codifique os parâmetros callback e callback-var em Base64

Exemplo: Codifique o parâmetro callback

Parâmetro callback original:

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

Resultado codificado em Base64:

eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

Exemplo: Codifique o parâmetro callback-var

Parâmetro callback-var original:
```
{
  "x:uid": "12345",
  "x:order_id": "67890"
}
```
Resultado codificado em Base64:
```
eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=
```

Anexe os parâmetros codificados à sua solicitação

Após codificar os parâmetros, você pode enviá-los ao OSS de uma das seguintes formas.

Header (recomendado)

Recomendado para uploads via SDK ou backend. Envie os parâmetros de callback nos headers HTTP x-oss-callback e x-oss-callback-var:

x-oss-callback: O parâmetro callback codificado em Base64.
x-oss-callback-var (opcional): O parâmetro callback-var codificado em Base64.

Nota: Inclua esses dois headers nos headers canônicos ao calcular a assinatura da solicitação.

Exemplo: Envie parâmetros de callback no 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

Corpo do POST

Este método se aplica somente a uploads que usam a operação de API PostObject. Os parâmetros de callback devem ser enviados como campos de formulário no corpo da solicitação POST.

Parâmetro de callback: Envie a configuração JSON codificada em Base64 como um campo de formulário separado.

--9431149156168
Content-Disposition: form-data; name="callback"
eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

Parâmetro callback-var (variáveis personalizadas): Cada parâmetro personalizado deve ser enviado como um campo de formulário separado; não é possível combiná-los em um único campo callback-var.

Por exemplo, considere as variáveis personalizadas uid e order_id:
```
{
  "x:uid": "12345",
  "x:order_id": "67890"
}
```
Converta-os em dois campos de formulário separados.
```
--9431149156168
Content-Disposition: form-data; name="x:uid"
12345
--9431149156168
Content-Disposition: form-data; name="x:order_id"
67890
```

Valide o parâmetro de callback (opcional): Você pode especificar condições na política para validar o parâmetro callback. Se nenhuma condição for definida, o parâmetro não será validado durante o upload. Por exemplo:

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

URL

Usado para fazer upload de arquivos com uma URL pré-assinada. Aciona o callback anexando parâmetros de callback codificados em Base64 à URL. Isso expõe informações do callback na URL, portanto use apenas para acesso temporário ou cenários de baixa sensibilidade.

Se você enviar parâmetros de callback na URL, inclua o parâmetro callback (obrigatório) e opcionalmente callback-var. Ambos devem fazer parte da Canonical Query String para o cálculo da assinatura. Signature Version 4.

Exemplo:

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

Implementação do lado do servidor

Para exemplos de código em diferentes linguagens, consulte Exemplos de código do lado do servidor.

O servidor de aplicação deve:

Receber solicitações POST do OSS

Após um upload bem-sucedido, o OSS envia uma solicitação POST para a URL de callback:

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**********vY2FsbGJeV192MS5wZW0=
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

Verificar a assinatura da solicitação para segurança (opcional)

Para confirmar que a solicitação é do OSS, verifique a assinatura no servidor de aplicação. Consulte Configurações recomendadas.

null
A verificação de assinatura é opcional.
Retornar uma resposta de callback

O servidor de aplicação deve retornar uma resposta ao OSS que atenda aos seguintes requisitos:
- O servidor de aplicação deve retornar HTTP/1.1 200 OK.
- O header da resposta deve incluir Content-Length.
- O corpo da resposta aceita os formatos JSON ou XML. O exemplo neste tópico usa JSON. Para XML, adicione Content-Type: application/xml ao header da resposta.
Por exemplo, o servidor de aplicação pode retornar {"Status": "OK"}.

Nota: Este exemplo usa Python 2.7.6. Recomendamos usar Python 3 para novos desenvolvimentos.
```
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"}
```
O OSS encaminha o corpo dessa resposta ao cliente. O código a seguir mostra um exemplo:
```
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"}
```
null
Para uma solicitação CompleteMultipartUpload, se o corpo original da resposta contiver conteúdo (por exemplo, informações no formato JSON), esse conteúdo será sobrescrito pela resposta do callback de upload após a ativação do recurso, por exemplo, por {"Status": "OK"}.

Configurações recomendadas

Verificar a assinatura da solicitação

O OSS envia uma solicitação POST para a callbackUrl após um upload. Verifique a assinatura da solicitação para confirmar que ela foi enviada pelo OSS.

Como o OSS assina a solicitação de callback

O OSS assina a solicitação usando RSA com um hash MD5 e coloca a assinatura codificada em Base64 no header authorization.
- A assinatura é calculada da seguinte forma:
```
authorization = base64_encode(rsa_sign(private_key, url_decode(path) + query_string + '\n' + body, md5))
```
  null
  Nesta fórmula, private_key é a chave privada, path é o caminho do recurso da solicitação de callback, query_string é a string de consulta, e body é o corpo do callback.
- As etapas para gerar a assinatura são:
  1. Construa a string a ser assinada concatenando o caminho do recurso decodificado via URL, a string de consulta original, um caractere de nova linha e o corpo do callback.
  2. Assine a string com RSA: Use a chave para assinar a string. A função de hash para a assinatura é MD5.
  3. Codifique o resultado assinado em Base64 para obter a assinatura final. Em seguida, coloque a assinatura no header authorization da solicitação de callback.
- Exemplo de geração de assinatura:
```
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
```
  O path é /index.php, a query_string é ?id=1&index=2, o body é bucket=examplebucket, e o resultado final da assinatura é kKQeGTRccDKyHB3H9vF+xYMSrmhMZjzzl2/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****.
Como o servidor verifica a assinatura

Verifique a assinatura da solicitação para confirmar a autenticidade:
1. Obtenha a chave pública:
  
  Obtenha e decodifique em Base64 a URL da chave pública a partir do header x-oss-pub-key-url da solicitação.
```
public_key = urlopen(base64_decode(value of x-oss-pub-key-url header))
```
  Valor de exemplo antes da decodificação:
```
aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ==
```
  Após a decodificação:
```
http://gosspublic.alicdn.com/callback_pub_key_v1.pem
```
  null
  A URL da chave pública deve começar com http://gosspublic.alicdn.com/ ou https://gosspublic.alicdn.com/. Faça cache da chave pública localmente para evitar interrupções causadas por problemas de rede.
2. Decodifique a assinatura.
  
  Obtenha e decodifique em Base64 a assinatura a partir do header authorization da solicitação:
```
signature = base64_decode(value of authorization header)
```
3. Construa a string de verificação.
  
  Concatene o caminho do recurso, a string de consulta, um caractere de nova linha e o corpo do callback no seguinte formato:
```
sign_str = url_decode(path) + query_string + '\n' + body
```
4. Verifique a assinatura.
  
  Use um hash MD5 com a chave pública RSA para a verificação:
```
result = rsa_verify(public_key, md5(sign_str), signature)
```

Exemplo de verificação de assinatura

O exemplo a seguir em Python 3 mostra como verificar uma assinatura em um servidor de aplicação. Este exemplo requer a biblioteca 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):
        # Get the public key.
        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)
            # We recommend that you cache the public key content based on the public key URL to improve performance.
            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

        # Get the signature.
        authorization_base64 = self.headers['authorization']
        authorization = base64.b64decode(authorization_base64)
        # Get the callback body.
        content_length = self.headers['content-length']
        callback_body = self.rfile.read(int(content_length))
        # Compose the string for signature verification.
        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)
        # Verify the 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

        # Process the request based on the callback body.
        # Respond to 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()

A tabela a seguir lista o código do lado do servidor para outras linguagens.

Linguagem	Descrição
Java	URL de download: Java Para executar o aplicativo, descompacte o pacote e execute o comando `java -jar oss-callback-server-demo.jar 9000` (9000 é o número da porta, que pode ser alterado).
Python	URL de download: Python Descompacte o pacote e execute `python callback_app_server.py`. Este programa requer a instalação das dependências RSA.
PHP	URL de download: PHP Faça deploy em um ambiente Apache. Alguns headers de dados variam conforme o ambiente. Ajuste o código de acordo.
.NET	URL de download: .NET Para executar: Descompacte o pacote e consulte o `README.md`.
Node.js	URL de download: Node.js Para executar, descompacte o pacote e execute `node example.js`.
Ruby	URL de download: Ruby Como executar: `ruby aliyun_oss_callback_server.rb`

Parâmetros de callback

A tabela a seguir descreve os parâmetros de callback que configuram a solicitação de callback enviada pelo OSS após um upload bem-sucedido.

Campo	Obrigatório	Descrição
callbackUrl	Sim	A URL para a qual o OSS envia uma solicitação POST após um upload de arquivo bem-sucedido. Você pode configurar até cinco URLs, separadas por ponto e vírgula (;). O OSS envia solicitações sequencialmente até a primeira retornar uma resposta bem-sucedida. URLs HTTPS são compatíveis. Não é possível especificar um endereço IPv6 ou um nome de domínio que resolva para um endereço IPv6. Para garantir que caracteres como chinês sejam processados corretamente, a callbackUrl deve ter codificação URL. Por exemplo, `https://example.com/中文.php?key=value&中文名称=中文值` deve ser codificada como `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	Sim	O conteúdo do corpo da solicitação de callback. O formato deve corresponder ao valor do parâmetro `callbackBodyType`: Quando `callbackType` é o valor padrão `application/x-www-form-urlencoded`, callbackBody deve estar no formato de pares chave-valor, por exemplo: `bucket=${bucket}&object=${object}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}` Se `callbackType` for `application/json`, `callbackBody` deve estar no formato JSON. Por exemplo: `{\"bucket\":${bucket},\"object\":${object},\"mimeType\":${mimeType},\"size\":${size},\"my_var1\":${x:my_var1},\"my_var2\":${x:my_var2}}` `callbackBody` aceita referências a parâmetros do sistema do OSS, variáveis personalizadas e constantes. Para a descrição dos parâmetros do sistema, consulte Parâmetros do sistema para callbackBody.
callbackHost	Não	O valor do header Host na solicitação de callback. O valor pode ser um nome de domínio ou um endereço IP. Se você não definir `callbackHost`, o OSS extrairá o host de `callbackUrl` e usará como valor de `callbackHost`.
callbackSNI	Não	Especifica se a Server Name Indication (SNI) deve ser incluída na solicitação de callback. A SNI é usada em uma solicitação HTTPS para identificar o nome de domínio e retornar o certificado correto. Se `callbackUrl` usar HTTPS, recomendamos ativar esse parâmetro. Caso contrário, o callback pode falhar devido a uma incompatibilidade de certificado (por exemplo, `502 callback failed`). Os valores válidos são: `true`: Envia SNI. `false` (Padrão): Não envia SNI. null A região UK (London) sempre envia SNI, independentemente da configuração deste parâmetro.
callbackBodyType	Não	O Content-Type da solicitação de callback, que é o formato de dados do `callbackBody`. Os seguintes tipos são compatíveis: `application/x-www-form-urlencoded` (Padrão) Substitui as variáveis em `callbackBody` pelos valores codificados via URL. `application/json` Substitui as variáveis em `callbackBody` no formato JSON.

Parâmetros do sistema para callbackBody

O campo callbackBody aceita os seguintes parâmetros do sistema para enviar informações do arquivo carregado na solicitação de callback.

Parâmetro	Descrição
bucket	O nome do bucket.
object	O caminho completo do objeto (arquivo).
etag	O ETag do arquivo. Este é o mesmo valor de ETag retornado ao usuário.
size	O tamanho do objeto. Para uma chamada `CompleteMultipartUpload`, este é o tamanho do objeto inteiro.
mimeType	O tipo do recurso. Por exemplo, o tipo de recurso de uma imagem JPEG é `image/jpeg`.
imageInfo.height	A altura da imagem. Vazio para arquivos que não são imagens.
imageInfo.width	A largura da imagem. Vazio para arquivos que não são imagens.
imageInfo.format	O formato da imagem (JPG, PNG, etc.). Vazio para arquivos que não são imagens.
crc64	Esse valor é igual ao valor do header `x-oss-hash-crc64ecma` retornado após o upload do arquivo.
contentMd5	Esse valor é igual ao valor do header `Content-MD5` retornado após o upload do arquivo. null Essa variável não está vazia somente quando o upload do arquivo é feito usando a operação de API `PutObject` ou `PostObject`.
vpcId	O ID da VPC do cliente solicitante. Essa variável estará vazia se a solicitação não tiver origem em uma VPC.
clientIp	O endereço IP do cliente que iniciou a solicitação.
reqId	O ID da solicitação.
operation	O nome da operação de API chamada, como `PutObject` ou `PostObject`.

SDK

Demos de implementação de callback do lado do cliente:

	Upload simples (usa a operação de API PutObject)	Upload multipart (usa a operação de API CompleteMultipartUpload)	Upload usando uma URL pré-assinada (usa a operação de API PutObject)
Java	demo	demo	demo
Python V2	demo	-	demo
Go V2	demo	demo	demo

Solução de problemas

As mensagens de erro do OSS incluem um código EC para solução de problemas. Os códigos EC relacionados a callbacks estão listados em 07-CALLBACK.

Perguntas frequentes

Callback em caso de falha no upload

Não. Os callbacks são acionados somente para uploads bem-sucedidos. Para uploads que falharam, o OSS retorna um erro diretamente ao cliente em vez de acionar um callback.

Erro de formato JSON inválido

Uma exceção no servidor de aplicação faz com que ele retorne um corpo de resposta em formato JSON inválido. A figura a seguir mostra um exemplo.

Solução:
- Execute o seguinte comando para confirmar o conteúdo.
```
curl -d "<Content>" <CallbackServerURL> -v
```
- Capture pacotes para confirmar o conteúdo.
  
  No Windows, recomendamos usar o Wireshark para capturar pacotes. No Linux, execute o comando tcpdump.
O corpo que o servidor de aplicação retorna ao OSS contém um byte order mark (BOM).

Esse erro é comum em aplicações PHP. O SDK PHP pode retornar um byte order mark (BOM), adicionando três bytes extras ao corpo da resposta e invalidando o formato JSON. Conforme mostrado na figura a seguir, os três bytes ef bb bf são o BOM.

Solução: Remova o BOM do corpo da resposta do servidor de aplicação.