:Comment résoudre les erreurs de rappel de téléchargement ?

À propos des rappels de téléchargement

Lors du téléchargement d'un fichier, l'OSS peut envoyer un rappel à votre serveur de rappel. Vous pouvez inclure les paramètres de rappel pertinents dans la requête de téléchargement pour mettre en œuvre cette fonctionnalité. Les API qui prennent en charge le rappel de téléchargement sont PutObject, PostObject et CompleteMultipartUpload. Pour plus d'informations, consultez les sections Rappel de téléchargement et API de rappel du Guide du développeur.

Scénarios d'application

Flux de données

Le tableau suivant décrit les flux de données.

SDK/PostObject

Lors du téléchargement du fichier, vous pouvez définir les paramètres de rappel pour spécifier l'URL du serveur de rappel, les données à envoyer à ce serveur ainsi que leur format. Lorsque le serveur de rappel traite un appel, certaines informations contextuelles, telles que le bucket et l'object, sont spécifiées à l'aide de variables système. D'autres informations contextuelles sont définies via des variables personnalisées.

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 système et variables personnalisées

Les variables présentes dans CallbackJson, telles que ${bucket}, ${object} et ${size} dans l'exemple de CallbackJson, sont des variables système définies par l'OSS. Lors du rappel, l'OSS remplace ces variables système par leurs valeurs réelles. Le tableau ci-dessous répertorie les variables système définies par l'OSS.

Les variables présentes dans CallbackJson, telles que ${x:my_var} dans l'exemple de CallbackJson, sont des variables personnalisées. Lors du rappel, l'OSS remplace ces variables personnalisées par les valeurs définies. Les valeurs des variables personnalisées sont définies et transmises par la requête de téléchargement de l'une des deux manières suivantes :

• Les variables personnalisées sont transmises via x-oss-callback-var dans l'en-tête du message. Cette méthode est courante et recommandée.

• Les variables personnalisées sont transmises via callback-var dans la QueryString.

Les règles de génération des valeurs x-oss-callback-var ou callback-var sont les suivantes :

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

Voici des exemples de valeurs pour CallbackVarJson :

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

Exemple d'utilisation du SDK

Certains SDK, tels que JAVA et JS, encapsulent les étapes précédentes. D'autres SDK, comme Python, PHP et C, nécessitent l'application des règles susmentionnées pour générer les paramètres de rappel de téléchargement et les variables personnalisées. Le tableau ci-dessous présente des exemples d'utilisation des SDK.

Exemple d'utilisation de PostObject

PostObject prend en charge le rappel de téléchargement (upload callback). Les paramètres de rappel sont transmis via le champ de formulaire callback, tandis que les variables personnalisées sont transmises via un champ de formulaire indépendant. Pour plus d'informations, consultez la rubrique PostObjet.

Le tableau suivant présente des exemples d'utilisation de PostObject.

Serveur de rappel

Le serveur de rappel est un serveur HTTP qui traite les requêtes de rappel et les messages POST envoyés par OSS. L'URL du serveur de rappel correspond à la valeur du paramètre de rappel de téléchargement callbackUrl. Vous pouvez implémenter votre propre logique de traitement sur le serveur de rappel pour l'enregistrement, la révision, le traitement et les statistiques des données téléchargées.

Procédure de débogage

Le débogage du rappel de téléchargement implique le client qui télécharge le fichier et le serveur de rappel qui traite le rappel. Nous vous recommandons de déboguer d'abord le client, puis le serveur de rappel. Après avoir débogué indépendamment ces deux parties, effectuez le rappel de téléchargement complet.

• Débogage du client

  Vous pouvez utiliser le serveur de rappel http://oss-demo.aliyuncs.com:23450 fourni par OSS, c'est-à-dire le paramètre de rappel callbackUrl, pour déboguer le client. Ce serveur de rappel vérifie uniquement la signature de la requête de rappel et ne traite pas la requête elle-même. Pour les requêtes dont la signature est correctement vérifiée, le serveur renvoie {"Status":"OK"}. Pour les requêtes dont la vérification de signature échoue, il renvoie 400 Bad Request. Pour les requêtes autres que POST, le serveur renvoie 501 Unsupported method. Pour plus d'informations sur le code de l'exemple de serveur de rappel, consultez callback_app_server.py.zip.

• Débogage du serveur de rappel

  Le serveur de rappel est un serveur HTTP capable de traiter les requêtes POST. Vous pouvez modifier le serveur de rappel en vous basant sur l'exemple fourni par OSS ou l'implémenter vous-même. Le tableau suivant décrit les exemples de serveurs de rappel fournis par OSS.

  Langage	Exemple	Méthode d'exécution
  JAVA	AppCallbackServer.zip	Décompressez le package et exécutez java -jar oss-callback-server-demo.jar 9000.
  PHP	callback-php-demo.zip	Déployez et exécutez le programme dans un environnement Apache
  Python	callback_app_server.py.zip	Décompressez le package et exécutez python callback_app_server.py.
  C#	callback-server-dotnet.zip	Compilez le programme et exécutez aliyun-oss-net-callback-server.exe 127.0.0.1 80.
  Go	callback-server-go.zip	Compilez le programme et exécutez aliyun_oss_callback_server.
  Ruby	oss-callback-server	Exécutez ruby aliyun_oss_callback_server.rb.

  Le serveur de rappel peut être débogé en exécutant la commande cURL. Voici les commandes susceptibles d'être utilisées :

  # 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

  Remarque

  • Lors du débogage du serveur de rappel, ignorez la vérification de signature, car il est difficile pour cURL de simuler la fonction de signature.

  • L'exemple OSS fournit déjà la fonction de vérification de signature. Nous vous recommandons de l'utiliser directement.

  • Nous vous recommandons que le serveur de rappel dispose d'une fonction de journalisation pour enregistrer tous les messages, ce qui facilite le débogage et le suivi.

  • Après avoir traité correctement une requête de rappel, le serveur de rappel doit renvoyer 200 et non 20x.

  • Le corps du message envoyé par le serveur de rappel à OSS doit être au format JSON, et Content-Type doit être défini sur application/json.

Erreurs courantes et causes

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

  Remarque

  Les paramètres de rappel sont incorrects ou leur format est invalide. L'erreur courante est que les paramètres de rappel dans ArgumentValue ne sont pas au format JSON valide. En JSON, \ et " sont des caractères d'échappement. Par exemple, "callbackBody":"{"bucket":${bucket},"object":${object}}" doit devenir "callbackBody":"{\"bucket\":${bucket},\"object\":${object}}". Pour plus d'informations sur les SDK, consultez les exemples de rappel de téléchargement dans la section Exemple d'utilisation du SDK.

  Caractère après échappement	Caractère avant échappement
  \\	\\\\
  “	\\\”
  \b	\\b
  \f	\\f
  \n	\\n
  \r	\\r
  \t	\\t

• CallbackFailed

  Voici des exemples d'erreur CallbackFailed :

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

    Remarque

    Le corps du message envoyé par le serveur de rappel à OSS n'est pas au format JSON. Vous pouvez confirmer le contenu en exécutant curl -d "<Content>" <CallbackServerURL> -v ou en capturant les paquets. Nous vous recommandons d'utiliser Wireshark pour la capture de paquets sous Windows, et tcpdump sous Linux. Les messages renvoyés invalides incluent : OK et \357\273\277{"Status":"OK"} (l'en-tête BOM contenant les octets ef bb bf).

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

    Remarque

    Le temps de traitement du serveur de rappel dépasse cinq secondes. Par conséquent, OSS considère qu'un délai d'expiration s'est produit. Nous vous recommandons de modifier la logique de traitement du serveur de rappel pour utiliser un traitement asynchrone, afin de garantir que le traitement se termine dans les cinq secondes et que le résultat soit renvoyé à OSS.

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

    Remarque

    Le temps de traitement du serveur de rappel dépasse cinq secondes. Par conséquent, OSS considère qu'un délai d'expiration s'est produit.

  • Exemple 4

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

    Remarque

    Le code d'état du message envoyé par le serveur de rappel à OSS est 400. Vérifiez la logique de traitement du serveur de rappel.

  • Exemple 5

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

    Remarque

    Le serveur de rappel n'est pas démarré, CallbackUrl est absent des paramètres de rappel, ou la connexion réseau entre l'instance OSS et le serveur de rappel est interrompue. Nous vous recommandons de déployer le serveur de rappel sur une instance ECS située sur le même intranet que OSS, afin de réduire les coûts de trafic et de garantir la qualité du réseau.

• Le corps de la réponse n'est pas au format JSON.

  Par exemple :

  

  Cette erreur peut être causée par les raisons suivantes :

  • Le corps de la réponse renvoyé par le serveur d'application à OSS n'est pas au format JSON, comme illustré dans la figure suivante :

    OSS signale l'erreur si resp_body n'est pas au format JSON valide. De plus, cette erreur peut être causée par d'autres facteurs sous-jacents, tels que le serveur d'application renvoyant une trace de pile au lieu d'une réponse normale à OSS en raison d'exceptions.

  • Le corps de la réponse renvoyé par le serveur d'application à OSS contient un en-tête BOM.

    Ce problème survient généralement sur les serveurs d'application codés en PHP, qui incluent un en-tête BOM dans la réponse renvoyée à OSS. Par conséquent, OSS signale l'erreur car trois octets supplémentaires (c'est-à-dire l'en-tête BOM) sont inclus dans la réponse, ce qui ne respecte pas le format JSON. La figure suivante montre le contenu inclus dans le paquet envoyé par le serveur d'application.

    

    Dans la figure précédente, les octets ef bb bf correspondent aux trois octets supplémentaires de l'en-tête BOM.

    Remarque

    Pour résoudre ce problème, supprimez l'en-tête BOM de la réponse renvoyée par le serveur d'application à OSS.

• État d'erreur

  Les codes d'état d'erreur, tels que 502 et 400, sont des erreurs renvoyées en raison de fonctions de rappel incorrectes, comme illustré dans la figure suivante.

  

  Remarque

  Un code d'état d'erreur, tel que 400, 404 ou 403, indique le statut HTTP renvoyé par le serveur d'application à OSS. Un code d'état 200 indique que l'opération a réussi.

  Le code d'état d'erreur 502 est renvoyé lorsque le service Web n'est pas activé sur le serveur d'application, ce qui signifie que le serveur ne peut pas recevoir la requête de rappel envoyée par OSS.

• Délai d'expiration

  La figure suivante illustre une erreur de délai d'expiration.

  

  Remarque

  Pour des raisons de sécurité, OSS attend la réception de la réponse de rappel pendant un maximum de 5 secondes. Si aucune réponse n'est renvoyée, OSS se déconnecte du serveur d'application et renvoie une erreur de délai d'expiration au client. L'adresse IP incluse dans le message d'erreur peut être ignorée.