:¿Cómo soluciono errores de callback de carga?

Acerca de los callbacks de carga

Cuando se carga un archivo, OSS puede proporcionar una Callback a su servidor de callback. Para implementar el callback de carga, incluya los parámetros de callback correspondientes en la solicitud de carga. Las API que admiten callback de carga son PutObject, PostObject y CompleteMultipartUpload. Para obtener más información, consulte Upload callback y Callback API en la Guía para desarrolladores.

Escenarios de aplicación

Flujo de datos

La siguiente tabla describe los flujos de datos.

SDK/PostObject

Durante la carga del archivo, puede establecer los parámetros de callback para especificar la URL del servidor de callback, los datos que se enviarán a dicho servidor y el formato de los datos. Cuando el servidor de callback procesa un callback, cierta información de contexto, como el bucket y el object, se especifica mediante variables del sistema. Otra información de contexto se especifica mediante variables 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}"
                

Variables del sistema y variables personalizadas

Las variables para CallbackJson, como ${bucket}, ${object} y ${size} en el ejemplo de CallbackJson, son variables del sistema definidas por OSS. Durante el callback, OSS reemplaza las variables del sistema con los valores reales. La siguiente tabla enumera las variables del sistema definidas por OSS.

Las variables para CallbackJson, como ${x:my_var} en el ejemplo de CallbackJson, son variables personalizadas. Durante el callback, OSS reemplaza las variables personalizadas con valores personalizados. Los valores de las variables personalizadas se definen e incluyen en la solicitud de carga de una de las dos maneras siguientes:

• Las variables personalizadas se incluyen en x-oss-callback-var dentro del encabezado del mensaje. Esta es una forma común y recomendada.

• Las variables personalizadas se incluyen en callback-var dentro de QueryString.

Las reglas para generar los valores de x-oss-callback-var o callback-var son las siguientes:

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

A continuación se muestran ejemplos de valores de CallbackVarJson:

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

Ejemplo de uso del SDK

Algunos SDK, como JAVA y JS, encapsulan los pasos anteriores. Otros SDK, como Python, PHP y C, requieren el uso de las reglas anteriores para generar los parámetros de callback de carga y las variables personalizadas. La siguiente tabla muestra ejemplos de uso del SDK.

Ejemplo de uso de PostObject

PostObject admite el callback de carga, cuyos parámetros de callback se incluyen en el campo de formulario callback, mientras que las variables personalizadas se incluyen en un campo de formulario independiente. Para obtener más información, consulte PostObjet.

La siguiente tabla muestra ejemplos de uso de PostObject.

Servidor de callback

El servidor de callback es un servidor HTTP que procesa las solicitudes de callback y los mensajes POST enviados desde OSS. La URL del servidor de callback es el valor del parámetro de callback de carga callbackUrl. Puede implementar su propia lógica de procesamiento en el servidor de callback para registrar, revisar, procesar y generar estadísticas de los datos cargados.

Procedimiento de depuración

La depuración del callback de carga incluye la depuración del cliente que carga el archivo y del servidor de callback que lo procesa. Se recomienda depurar primero el cliente y luego el servidor de callback. Después de depurar ambas partes de forma independiente, realice el callback de carga completo.

• Depuración del cliente

  Puede usar el servidor de callback http://oss-demo.aliyuncs.com:23450 proporcionado por OSS; es decir, el parámetro de callback callbackUrl para depurar el cliente. Este servidor de callback solo verifica la firma de la solicitud de callback, pero no la procesa. Para las solicitudes de callback cuya firma se verifica correctamente, el servidor devuelve {"Status":"OK"}. Para las solicitudes cuya firma no se puede verificar, devuelve 400 Bad Request. Para solicitudes que no son POST, devuelve 501 Unsupported method. Para obtener más información sobre el código del ejemplo de servidor de callback, consulte callback_app_server.py.zip.

• Depuración del servidor de callback

  El servidor de callback es un servidor HTTP capaz de procesar la solicitud POST. Puede modificar el servidor de callback basándose en el ejemplo proporcionado por OSS o implementarlo usted mismo. La siguiente tabla describe los ejemplos de servidores de callback proporcionados por OSS.

  Lenguaje	Ejemplo	Método de ejecución
  JAVA	AppCallbackServer.zip	Descomprima el paquete y ejecute java -jar oss-callback-server-demo.jar 9000.
  PHP	callback-php-demo.zip	Despliegue y ejecute el programa en un entorno de Apache
  Python	callback_app_server.py.zip	Descomprima el paquete y ejecute python callback_app_server.py.
  C#	callback-server-dotnet.zip	Compile el programa y ejecute aliyun-oss-net-callback-server.exe 127.0.0.1 80.
  Go	callback-server-go.zip	Compile el programa y ejecute aliyun_oss_callback_server.
  Ruby	oss-callback-server	Ejecute ruby aliyun_oss_callback_server.rb.

  El servidor de callback se puede depurar ejecutando el comando cURL. Es posible utilizar los siguientes 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

  • Al depurar el servidor de callback, ignore la verificación de firma porque resulta difícil para cURL simular la función de firma.

  • El ejemplo de OSS ya proporciona la función de verificación de firma. Se recomienda utilizarla directamente.

  • Se recomienda que el servidor de callback proporcione la función de registro para guardar todos los mensajes, lo cual facilita la depuración y el seguimiento.

  • Después de procesar correctamente una solicitud de callback, el servidor de callback debe devolver 200 en lugar de 20x.

  • El cuerpo del mensaje enviado desde el servidor de callback a OSS debe estar en formato JSON, y Content-Type debe establecerse en application/json.

Errores comunes y 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

  La configuración de los parámetros de callback es incorrecta, o bien el formato del parámetro no es válido. Un error común es que los parámetros de callback en ArgumentValue no tengan un formato JSON válido. En JSON, \ y " son caracteres de escape. Por ejemplo, "callbackBody":"{"bucket":${bucket},"object":${object}}" debe escribirse como "callbackBody":"{\"bucket\":${bucket},\"object\":${object}}". Para obtener más información sobre los SDK, consulte los ejemplos de callback de carga en la sección SDK usage example.

  Carácter después del escape	Carácter antes del escape
  \\	\\\\
  “	\\\”
  \b	\\b
  \f	\\f
  \n	\\n
  \r	\\r
  \t	\\t

• CallbackFailed

  A continuación se describen ejemplos del error CallbackFailed:

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

    El cuerpo del mensaje enviado desde el servidor de callback a OSS no está en formato JSON. Puede confirmar el contenido ejecutando curl -d "<Content>" <CallbackServerURL> -v o capturando paquetes. Se recomienda usar Wireshark para capturar paquetes en Windows y tcpdump para capturar paquetes en Linux. Los mensajes devueltos no válidos incluyen: OK y \357\273\277{"Status":"OK"} (el encabezado BOM que contiene los bytes ef bb bf).

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

    El tiempo de procesamiento del servidor de callback supera los cinco segundos. Por lo tanto, OSS determina que se ha producido un tiempo de espera agotado. Se recomienda modificar la lógica de procesamiento del servidor de callback a un procesamiento asíncrono para garantizar que pueda completar el procesamiento dentro de cinco segundos y devolver el resultado a OSS.

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

    El tiempo de procesamiento del servidor de callback supera los cinco segundos. Por lo tanto, OSS determina que se ha producido un tiempo de espera agotado.

  • Ejemplo 4

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

    Nota

    El código de estado del mensaje enviado desde el servidor de callback a OSS es 400. Compruebe la lógica de procesamiento del servidor de callback.

  • Ejemplo 5

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

    Nota

    El servidor de callback no se ha iniciado, falta CallbackUrl en los parámetros de callback, o la red entre la instancia de OSS y el servidor de callback está desconectada. Se recomienda desplegar el servidor de callback en ECS, dentro de la misma red interna que OSS, para ahorrar costos de tráfico y garantizar la calidad de la red.

• El cuerpo de la respuesta no está en formato JSON.

  Por ejemplo:

  

  Este error puede deberse a las siguientes razones:

  • El cuerpo de la respuesta devuelto por el servidor de aplicaciones a OSS no está en formato JSON, como se muestra en la siguiente figura:

    OSS reporta el error si resp_body no tiene un formato JSON válido. Además, este error puede deberse a otros factores subyacentes, como que el servidor de aplicaciones devuelva un seguimiento de pila en lugar de una respuesta normal a OSS debido a excepciones.

  • El cuerpo de la respuesta devuelto por el servidor de aplicaciones a OSS lleva un BOM en el encabezado.

    Este problema generalmente ocurre en servidores de aplicaciones programados en PHP, que incluyen un encabezado BOM en la respuesta devuelta a OSS. Por lo tanto, OSS reporta el error porque se incluyen tres bytes adicionales (es decir, el encabezado BOM) en la respuesta, lo cual no cumple con el formato JSON. La siguiente figura muestra el contenido incluido en el paquete enviado por el servidor de aplicaciones.

    

    En la figura anterior, los bytes ef bb bf son los tres bytes adicionales del encabezado BOM.

    Nota

    Para resolver este problema, elimine el encabezado BOM en la respuesta devuelta por el servidor de aplicaciones a OSS.

• Estado de error

  Los códigos de estado de error, como 502 y 400, son errores que se devuelven debido a funciones de callback incorrectas, como se muestra en la siguiente figura.

  

  Nota

  Se devuelve un código de estado de error, como 400, 404 o 403, para indicar el estado HTTP devuelto por el servidor de aplicaciones a OSS. Una devolución de código de estado 200 indica que la operación se realizó correctamente.

  El código de estado de error 502 se devuelve cuando el servicio web no está habilitado en el servidor de aplicaciones, lo que significa que el servidor no puede recibir la solicitud de callback enviada por OSS.

• Tiempo de espera agotado

  La siguiente figura muestra un error de tiempo de espera agotado.

  

  Nota

  Por motivos de seguridad, OSS espera recibir la respuesta de callback durante un máximo de 5 segundos. Si no se devuelve la respuesta, OSS se desconecta del servidor de aplicaciones y devuelve un error de tiempo de espera agotado al cliente. La dirección IP incluida en el mensaje de error se puede ignorar.