Aller au contenu

Téléchargement de Fichier

Résumé

  • Nom interne : DownloadTask
  • Catégorie : Communication
  • Objectif : Télécharger un fichier depuis une URL distante et l'enregistrer dans un chemin local sur l'appareil Android, 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
    • WRITE_EXTERNAL_STORAGE

Description détaillée

La tâche Téléchargement de Fichier ouvre une connexion HTTP/HTTPS vers l'url spécifiée et diffuse le corps de la réponse vers le fichier local indiqué par path, en utilisant OkHttp via FileTransferClient.downloadToFile(). 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.

url et path 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 valide — 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 local absolu (ex. /sdcard/Download/fichier.zip) — 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 téléchargé 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).

Exceptions

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

Diagramme d'exécution

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

    ResolveParams --> CallClient[🌐 FileTransferClient.downloadToFile\nOkHttp — 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 :

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

Exemples de code

Exemple 1 — Télécharger un fichier avec le délai par défaut

{
  "DownloadTask": [
    {
      "id": "1",
      "title": "Télécharger firmware",
      "url": "https://example.com/firmware.zip",
      "path": "/sdcard/Downloads/firmware.zip",
      "file_size_output": "$octets_telecharges",
      "duration_ms_output": "$duree_dl_ms",
      "bitrate_output": "$debit_dl"
    }
  ]
}

Exemple 2 — Télécharger avec variables de workflow

{
  "DownloadTask": [
    {
      "id": "2",
      "title": "Télécharger cible dynamique",
      "url": "$url_telechargement",
      "path": "$chemin_local",
      "file_size_output": "$taille_fichier",
      "duration_ms_output": "$temps_dl",
      "bitrate_output": "$debit"
    }
  ]
}

Exemple 3 — Télécharger avec délai personnalisé

{
  "DownloadTask": [
    {
      "id": "3",
      "title": "Télécharger avec délai 30s",
      "url": "https://example.com/large-dataset.csv",
      "path": "/sdcard/data/dataset.csv",
      "timeout_ms": 30000,
      "file_size_output": "$taille_csv",
      "duration_ms_output": "$csv_dl_ms",
      "bitrate_output": "$csv_debit"
    }
  ]
}

Exemple 4 — Télécharger et mesurer la vitesse

{
  "DownloadTask": [
    {
      "id": "4",
      "title": "Test de vitesse de téléchargement",
      "url": "https://example.com/testfile.bin",
      "path": "/sdcard/Downloads/testfile.bin",
      "timeout_ms": 15000,
      "file_size_output": "$octets_recus",
      "duration_ms_output": "$elapsed_ms",
      "bitrate_output": "$vitesse_bps"
    }
  ]
}

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

1. url — URL de téléchargement

L'URL HTTP ou HTTPS complète de la ressource distante à télécharger. Doit être une URL non vide et bien formée incluant le schéma (http:// ou https://).

Supporte les références $variable_workflow — résolues à l'exécution avant le début du transfert.

Valide Invalide
https://example.com/file.zip file.zip (pas de schéma)
http://192.168.1.1/data.bin ftp://example.com/file (schéma non supporté)
$url_telechargement "" (vide)
  • Défaut : ""

2. path — Chemin local de destination

Le chemin absolu sur l'appareil Android où le fichier téléchargé sera sauvegardé. Le répertoire parent doit exister et l'application doit avoir les droits d'écriture.

  • Doit être absolu : les chemins ne commençant pas par / ne sont pas valides
  • Le répertoire parent doit exister : la tâche ne crée pas les répertoires intermédiaires manquants
  • Supporte les variables : Oui — ex. /sdcard/$nom_fichier
  • Défaut : ""

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

Temps maximum en millisecondes alloué à l'ensemble de l'opération de téléchargement (connexion et transfert de données inclus). Si dépassé, une AndromateTimeoutException est levée.

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

Détails des paramètres de sortie

file_size_output — Taille du fichier téléchargé

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

  • Écrit uniquement en cas de succès
  • Valeur = nombre d'octets écrits sur le disque (ex. 204800 pour 200 Ko)

duration_ms_output — Durée du transfert

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

  • Mesuré depuis le début du transfert jusqu'au dernier octet écrit sur le disque

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 réseau

Exemple JSON complet

{
  "DownloadTask": [
    {
      "id": "1",
      "title": "Télécharger fichier de test",
      "url": "https://speed.example.com/10mb.bin",
      "path": "/sdcard/Download/10mb.bin",
      "timeout_ms": 30000,
      "file_size_output": "$octets_dl",
      "duration_ms_output": "$temps_dl_ms",
      "bitrate_output": "$debit_bps"
    }
  ]
}