Envoi de Fichier

Résumé

Nom interne : UploadTask
Catégorie : Communication
Objectif : Envoyer un fichier local depuis l'appareil Android vers un serveur distant via un envoi HTTP multipart, avec rapport des statistiques de transfert.
Type de tâche : Normale

Compatibilité

Version AndroMate minimale : 1.1.0
Version AndroMate maximale : 1.1.0
Android minimum : Android 13 (API 33)
Android maximum testé : Android 16 (API 36)
Fabricants supportés :
- ✅ Samsung (One UI 6.x / 7.x / 8.x)
- ✅ Google Pixel (Android Stock)
- ⚠️ Autres fabricants — non testés
Permissions requises :
- INTERNET
- ACCESS_NETWORK_STATE
- READ_EXTERNAL_STORAGE

Description détaillée

La tâche Envoi de Fichier lit un fichier local depuis path et l'envoie au serveur distant à l'url spécifiée via un envoi HTTP multipart grâce à FileTransferClient.uploadMultipart() (OkHttp). L'appel est asynchrone et attend le callback. La progression est journalisée sous la forme bytes/totalBytes dans le rapport de la tâche.

Le paramètre path est le fichier local à envoyer ; url est le point de terminaison serveur qui reçoit le fichier. Les deux supportent les références $variable_workflow — résolues à l'exécution avant le début du transfert. L'opération est limitée par timeout_ms. Si le délai est dépassé, une AndromateTimeoutException est levée. Si le transfert échoue pour toute autre raison, l'exception DOWNLOAD-UPLOAD-ERROR-001 est levée.

En cas de succès, la tâche écrit la taille du fichier, la durée du transfert et le débit dans les trois variables de sortie issues de TransferStatResult.

Paramètres d'entrée

Paramètre	Type	Obligatoire	Valeurs possibles	Compatibilité Android	Compatibilité AndroMate	Défaut
`url`	Chaîne	Oui	URL HTTP/HTTPS du point de terminaison serveur — supporte les références `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`path`	Chaîne	Oui	Chemin absolu du fichier local à envoyer — supporte les références `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`timeout_ms`	Long	Non	Délai d'attente en millisecondes	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`5000`

Paramètres de sortie

Champ	Type	Condition de déclenchement	Compatibilité Android	Compatibilité AndroMate	Défaut
`file_size_output`	Long	Toujours en cas de succès — taille du fichier envoyé en octets	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`
`duration_ms_output`	Long	Toujours en cas de succès — durée du transfert en millisecondes	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`
`bitrate_output`	Double	Toujours en cas de succès — débit du transfert en octets/seconde	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`

Remarque : Les variables de sortie ne sont écrites que si la variable workflow correspondante existe déjà dans le contexte d'exécution (déclarée dans la tâche Start). Les sorties sont des statistiques de transfert de fichier, pas des données de réponse HTTP.

Exceptions

Code	Déclenchement
`DOWNLOAD-UPLOAD-ERROR-001`	Erreur de transfert de fichier (depuis `AndromateExceptionTypes.FILE_TRANSFER_ERROR`). Levée lors de tout échec d'envoi.
Timeout	`AndromateTimeoutException` — l'opération a dépassé `timeout_ms`. Aucun code d'exception spécifique.

Diagramme d'exécution

flowchart TD
    Start([▶ UploadTask]) --> ResolveParams[🔄 Résoudre url + path\n+ timeout_ms]

    ResolveParams --> CallClient[🌐 FileTransferClient.uploadMultipart\nOkHttp — envoi multipart asynchrone]

    CallClient --> WaitCallback[⏳ Attendre le callback asynchrone]

    WaitCallback -->|timeout_ms dépassé| ETimeout[❌ Timeout\nAndromateTimeoutException]
    WaitCallback -->|Erreur de transfert| E1[❌ DOWNLOAD-UPLOAD-ERROR-001\nErreur de transfert]
    WaitCallback -->|Succès| WriteOutputs[💾 Écrire TransferStatResult\nfile_size_output\nduration_ms_output\nbitrate_output]

    WriteOutputs --> Success([✅ TransferStatResult])

    ETimeout --> Error([❌ Exception])
    E1 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style ETimeout fill:#ffcdd2
    style E1 fill:#ffcdd2
    style ResolveParams fill:#fff9c4
    style CallClient fill:#f3e5f5
    style WaitCallback fill:#f3e5f5
    style WriteOutputs fill:#c8e6c9

Fonctionnement :

Résoudre les paramètres : url, path et timeout_ms sont résolus depuis le contexte workflow
Appeler FileTransferClient : invoque FileTransferClient.uploadMultipart() via OkHttp — envoi HTTP multipart, asynchrone
Attendre le callback : bloque jusqu'à ce que le callback asynchrone se déclenche ou que timeout_ms soit dépassé
En cas de timeout : lève AndromateTimeoutException
En cas d'erreur : lève DOWNLOAD-UPLOAD-ERROR-001 (erreur de transfert de fichier)
En cas de succès : écrit file_size_output, duration_ms_output et bitrate_output depuis TransferStatResult
Résultat : retourne TransferStatResult

Exemples de code

Exemple 1 — Envoyer un fichier avec le délai par défaut

{
  "UploadTask": [
    {
      "id": "1",
      "title": "Envoyer rapport",
      "url": "https://api.example.com/upload",
      "path": "/sdcard/Download/rapport.json",
      "file_size_output": "$octets_envoyes",
      "duration_ms_output": "$duree_envoi_ms",
      "bitrate_output": "$debit_envoi"
    }
  ]
}

Exemple 2 — Envoyer avec variables de workflow

{
  "UploadTask": [
    {
      "id": "2",
      "title": "Envoyer fichier dynamique",
      "url": "$endpoint_upload",
      "path": "$chemin_fichier_local",
      "file_size_output": "$taille_fichier",
      "duration_ms_output": "$temps_envoi",
      "bitrate_output": "$debit"
    }
  ]
}

Exemple 3 — Envoyer avec délai personnalisé

{
  "UploadTask": [
    {
      "id": "3",
      "title": "Envoyer fichier volumineux avec délai 60s",
      "url": "https://stockage.example.com/resultats/run1.zip",
      "path": "/sdcard/resultats/run1.zip",
      "timeout_ms": 60000,
      "file_size_output": "$taille_zip",
      "duration_ms_output": "$envoi_zip_ms",
      "bitrate_output": "$debit_zip"
    }
  ]
}

Détails des paramètres d'entrée

1. `url` — Point de terminaison d'envoi

L'URL HTTP ou HTTPS du point de terminaison serveur qui reçoit le fichier envoyé. Supporte les références $variable_workflow.

Défaut : ""
Supporte les variables : Oui

2. `path` — Chemin du fichier local

Le chemin absolu du fichier sur l'appareil Android à envoyer. Le fichier doit exister et être lisible. Il s'agit du fichier local envoyé au serveur.

Valide	Invalide
`/sdcard/Download/rapport.json`	`rapport.json` (chemin relatif)
`/data/local/tmp/test.bin`	`sdcard/test.bin` (sans `/` initial)
`$chemin_fichier_local`	`""` (vide)

Défaut : ""
Supporte les variables : Oui

3. `timeout_ms` — Délai d'opération

Temps maximum en millisecondes alloué à l'ensemble de l'opération d'envoi. Si dépassé, une AndromateTimeoutException est levée.

Type : Long
Défaut : 5000 (5 secondes)
Pour les fichiers volumineux : augmenter à 60000 ou plus pour éviter les timeouts prématurés

Détails des paramètres de sortie

`file_size_output` — Taille du fichier envoyé

Stocke la taille totale du fichier envoyé en octets (Long), issue de TransferStatResult, dans la variable workflow spécifiée.

Écrit uniquement en cas de succès
Valeur = nombre d'octets du fichier local envoyé

`duration_ms_output` — Durée du transfert

Stocke le temps total écoulé pendant l'opération d'envoi en millisecondes (Long), issu de TransferStatResult.

Mesuré depuis le début du transfert jusqu'à la fin de l'envoi multipart

`bitrate_output` — Débit du transfert

Stocke le débit de transfert mesuré en octets par seconde (Double), issu de TransferStatResult.

Calculé comme taille_fichier / (duration_ms / 1000.0)
Utile pour les rapports de débit d'envoi réseau

Exemple JSON complet

{
  "UploadTask": [
    {
      "id": "1",
      "title": "Envoyer fichier rapport",
      "url": "https://api.example.com/upload",
      "path": "/sdcard/Download/rapport.json",
      "timeout_ms": 30000,
      "file_size_output": "$octets_envoyes",
      "duration_ms_output": "$envoi_ms",
      "bitrate_output": "$debit_envoi_bps"
    }
  ]
}