:Como solucionar erros de callback de upload?

Sobre callbacks de upload

Ao fazer upload de um arquivo, o OSS pode fornecer um Callback para o seu servidor de callback. Para implementar o callback de upload, inclua os parâmetros relevantes na solicitação de upload. As APIs que suportam callback de upload são PutObject, PostObject e CompleteMultipartUpload. Para obter mais informações, consulte Upload callback e Callback API no Guia do Desenvolvedor.

Cenários de aplicação

Fluxo de dados

A tabela a seguir descreve os fluxos de dados.

SDK/PostObject

Durante o upload do arquivo, defina os parâmetros de callback para especificar a URL do servidor de callback, os dados a serem enviados a ele e o formato dos dados. Quando o servidor de callback processa um callback, algumas informações de contexto, como bucket e object, são especificadas usando variáveis de sistema. Outras informações de contexto usam variáveis personalizadas.

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

Variáveis de sistema e variáveis personalizadas

Variáveis para CallbackJson, como ${bucket}, ${object} e ${size}, no exemplo de CallbackJson são variáveis de sistema definidas pelo OSS. Durante o callback, o OSS substitui as variáveis de sistema pelos valores reais. A tabela a seguir lista as variáveis de sistema definidas pelo OSS.

Variáveis para CallbackJson, como ${x:my_var}, no exemplo de CallbackJson são variáveis personalizadas. Durante o callback, o OSS substitui as variáveis personalizadas pelos valores personalizados. Defina e inclua os valores das variáveis personalizadas na solicitação de upload de uma das duas maneiras a seguir:

• Inclua as variáveis personalizadas via x-oss-callback-var no cabeçalho da mensagem. Esta é uma maneira comum e recomendada.

• Inclua as variáveis personalizadas via callback-var na QueryString.

As regras para gerar os valores de x-oss-callback-var ou callback-var são as seguintes:

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

Exemplos de valores de CallbackVarJson:

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

Exemplo de uso do SDK

Alguns SDKs, como JAVA e JS, encapsulam as etapas anteriores. Outros, como Python, PHP e C, exigem o uso das regras acima para gerar os parâmetros de callback de upload e as variáveis personalizadas. A tabela a seguir lista exemplos de uso do SDK.

Exemplo de uso do PostObject

O PostObject suporta callback de upload, cujos parâmetros são transmitidos pelo campo de formulário callback, enquanto as variáveis personalizadas são transmitidas por um campo de formulário independente. Para obter mais informações, consulte PostObjet.

A tabela a seguir lista exemplos de uso do PostObject.

Servidor de callback

O servidor de callback é um servidor HTTP que processa solicitações de callback e mensagens POST enviadas pelo OSS. A URL do servidor de callback corresponde ao valor do parâmetro de callback de upload callbackUrl. Implemente sua própria lógica de processamento no servidor de callback para registro, revisão, processamento e geração de estatísticas dos dados enviados.

Procedimento de depuração

A depuração do callback de upload inclui a depuração do cliente que faz o upload do arquivo e do servidor de callback que o processa. Recomendamos depurar primeiro o cliente e depois o servidor de callback. Após depurar as duas partes independentemente, realize o callback de upload completo.

• Depuração do cliente

  Utilize o servidor de callback http://oss-demo.aliyuncs.com:23450 fornecido pelo OSS, ou seja, o parâmetro de callback callbackUrl para depurar o cliente. Esse servidor apenas verifica a assinatura da solicitação de callback, sem processá-la. Para solicitações com assinatura verificada com êxito, o servidor retorna {"Status":"OK"}. Para solicitações cuja verificação de assinatura falha, o servidor retorna 400 Bad Request. Para solicitações que não sejam POST, o servidor retorna 501 Unsupported method. Para obter mais informações sobre o código do exemplo de servidor de callback, consulte callback_app_server.py.zip.

• Depuração do servidor de callback

  O servidor de callback é um servidor HTTP capaz de processar solicitações POST. Modifique o servidor de callback com base no exemplo fornecido pelo OSS ou implemente-o por conta própria. A tabela a seguir descreve os exemplos de servidor de callback fornecidos pelo OSS.

  Linguagem	Exemplo	Método de execução
  JAVA	AppCallbackServer.zip	Descompacte o pacote e execute java -jar oss-callback-server-demo.jar 9000.
  PHP	callback-php-demo.zip	Implante e execute o programa no ambiente Apache
  Python	callback_app_server.py.zip	Descompacte o pacote e execute python callback_app_server.py.
  C#	callback-server-dotnet.zip	Compile o programa e execute aliyun-oss-net-callback-server.exe 127.0.0.1 80.
  Go	callback-server-go.zip	Compile o programa e execute aliyun_oss_callback_server.
  Ruby	oss-callback-server	Execute ruby aliyun_oss_callback_server.rb.

  Depure o servidor de callback executando o comando cURL. Use os seguintes comandos:

  # 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

  Nota

  • Ao depurar o servidor de callback, ignore a verificação de assinatura, pois é difícil para o cURL simular a função de assinatura.

  • O exemplo do OSS já fornece a função de verificação de assinatura. Recomendamos usá-la diretamente.

  • Recomendamos que o servidor de callback forneça a função de log para registrar todas as mensagens, facilitando a depuração e o rastreamento.

  • Após processar corretamente uma solicitação de callback, o servidor deve retornar 200 em vez de 20x.

  • O corpo da mensagem enviado do servidor de callback para o OSS deve estar no formato JSON, e Content-Type deve ser definido como application/json.

Erros comuns e causas

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

  Nota

  As configurações do parâmetro de callback estão incorretas ou o formato do parâmetro é inválido. O erro comum é que os parâmetros de callback em ArgumentValue não estejam em um formato JSON válido. Em JSON, \ e " são caracteres de escape. Por exemplo, "callbackBody":"{"bucket":${bucket},"object":${object}}" deve ser "callbackBody":"{\"bucket\":${bucket},\"object\":${object}}". Para obter mais informações sobre os SDKs, consulte os exemplos de callback de upload na seção Exemplo de uso do SDK.

  Caractere após escape	Caractere antes do escape
  \\	\\\\
  “	\\\”
  \b	\\b
  \f	\\f
  \n	\\n
  \r	\\r
  \t	\\t

• CallbackFailed

  Exemplos de erro CallbackFailed:

  • Exemplo 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>

    Nota

    O corpo da mensagem enviado do servidor de callback para o OSS não está no formato JSON. Confirme o conteúdo executando curl -d "<Content>" <CallbackServerURL> -v ou capturando pacotes. Recomendamos usar o Wireshark para capturar pacotes no Windows e o tcpdump para capturar pacotes no Linux. Mensagens de retorno inválidas incluem: OK e \357\273\277{"Status":"OK"} (o cabeçalho BOM contendo os bytes ef bb bf).

  • Exemplo 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>

    Nota

    O tempo de processamento do servidor de callback excede cinco segundos. Consequentemente, o OSS determina que ocorreu um tempo limite. Recomendamos modificar a lógica de processamento do servidor de callback para processamento assíncrono, garantindo que ele conclua o processamento dentro de cinco segundos e retorne o resultado ao OSS.

  • Exemplo 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>

    Nota

    O tempo de processamento do servidor de callback excede cinco segundos. Consequentemente, o OSS determina que ocorreu um tempo limite.

  • Exemplo 4

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

    Nota

    O código de status da mensagem enviada do servidor de callback para o OSS é 400. Verifique a lógica de processamento do servidor de callback.

  • Exemplo 5

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

    Nota

    O servidor de callback não foi iniciado, CallbackUrl está ausente nos parâmetros de callback ou a rede entre a instância do OSS e o servidor de callback está desconectada. Recomendamos implantar o servidor de callback no ECS, que pertence à mesma intranet que o OSS, para economizar custos de tráfego e garantir a qualidade da rede.

• O corpo da resposta não está no formato JSON.

  Por exemplo:

  

  Este erro pode ter os seguintes motivos:

  • O corpo da resposta retornado pelo servidor de aplicativos para o OSS não está no formato JSON, conforme mostrado na figura a seguir:

    O OSS relata o erro se resp_body não estiver em um formato JSON válido. Além disso, outros fatores subjacentes podem causar esse erro, como o servidor de aplicativos retornando um rastreamento de pilha em vez de uma resposta normal ao OSS devido a exceções.

  • O corpo da resposta retornado pelo servidor de aplicativos para o OSS carrega um BOM no cabeçalho.

    Esse problema geralmente ocorre em servidores de aplicativos codificados em PHP, que incluem um cabeçalho BOM na resposta retornada ao OSS. Portanto, o OSS relata o erro porque três bytes adicionais (ou seja, o cabeçalho BOM) estão incluídos na resposta, o que não está em conformidade com o formato JSON. A figura a seguir mostra o conteúdo incluído no pacote enviado pelo servidor de aplicativos.

    

    Na figura anterior, os bytes ef bb bf são os três bytes adicionais do cabeçalho BOM.

    Nota

    Para resolver esse problema, remova o cabeçalho BOM na resposta retornada pelo servidor de aplicativos ao OSS.

• Status de erro

  Códigos de status de erro, como 502 e 400, indicam erros retornados devido a funções de callback incorretas, conforme mostrado na figura a seguir.

  

  Nota

  Um código de status de erro, como 400, 404 ou 403, indica o status HTTP retornado pelo servidor de aplicativos ao OSS. O código de status 200 indica operação bem-sucedida.

  O código de status de erro 502 é retornado quando o serviço Web não está habilitado no servidor de aplicativos, o que significa que o servidor não pode receber a solicitação de callback enviada pelo OSS.

• Tempo limite

  A figura a seguir mostra um erro de tempo limite.

  

  Nota

  Por motivos de segurança, o OSS aguarda o recebimento da resposta de callback por no máximo 5 segundos. Se a resposta não for retornada, o OSS se desconecta do servidor de aplicativos e retorna um erro de tempo limite ao cliente. Ignore o endereço IP incluído na mensagem de erro.