Retourner des images par Service Web (via SOAP)

David Adams

4e Dimension propose la conversion automatique de pratiquement tous les types natifs 4D pour envoi dans une réponse SOAP, à l’exception des images. Heureusement, il est possible d’inclure des BLOBs dans les réponses SOAP de sorte que l’on peut inclure des images en les convertissant au préalable à l’aide de la commande IMAGE VERS BLOB. ♪

- Titre : Retourner des images par Service Web (via SOAP)

- Auteur : David Adams

- Parution : 1 mars 2005

- Licence : Ce document est issu de https://www.developpez.com et reste la propriété exclusive de son auteur. La copie, modification et/ou distribution par quelque moyen que ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.

Sommaire

- I. Introduction

- II. Résumé du système

- III. Écouter et répondre aux requêtes SOAP

- IV. Fournir une liste des images disponibles

- Table Image

- GetPictureList

- Fournir une liste des formats d’images disponibles

- V. Charger, convertir et retourner des images

- VI. Tâche de client SOAP : récupérer une image

- VII. Retourner des informations additionnelles

- VIII. Bases exemples

I - Introduction

4e Dimension version 2003 et ultérieure, propose la publication de méthodes comme Services Web. Concrètement les requêtes et réponses de Services Web sont des messages SOAP (Simple Object Access Protocol) qui suivent les règles d’encodage des données XML. 4e Dimension propose la conversion automatique de pratiquement tous les types natifs 4D pour envoi dans une réponse SOAP, à l’exception des images. Heureusement, il est possible d’inclure des BLOBs dans les réponses SOAP de sorte qu’il est possible d’inclure des images en les convertissant au préalable à l’aide de la commande IMAGE VERS BLOB.

Le retour d’images via SOAP est utile dans plusieurs situations, par exemple les scénarios suivants :

- un système de publication Web demande des images statiques ou dynamiques par SOAP pour les inclure dans des pages Web ;

- un système de base de données centralisé 4e Dimension joue le rôle d’une bibliothèque d’images ou d’archivage pour un nombre indéterminé de clients SOAP ;

- un système de base de données centralisé 4e Dimension jour le rôle de pivot de distribution d’images pour un nombre indéterminé de clients.

Cette note technique détaille les mécanismes de conversion et « d’empaquetage » d’images dans les réponses SOAP. La base de démo comprend du code fonctionnel réalisant un système simple de serveur d’images reposant sur SOAP.

Note : pour plus d’information sur les types de données supportés par SOAP, référez-vous au manuel de référence du langage de 4e Dimension ou à la note technique 4D-200503-07-FR « Retourner des données par Web Service (via SOAP) ».

II - Résumé du système

Le serveur d’image accomplit les tâches suivantes :

- écouter et répondre aux requêtes SOAP ;

- fournir une liste des images disponibles ;

- fournir une liste des formats d’images possibles ;

- charger, convertir et retourner les images.

Nous allons commenter chacune de ces tâches plus en détail.

III - Écouter et répondre aux requêtes SOAP

Pour publier des méthodes comme Services Web, les conditions suivantes doivent être remplies :

1. Le serveur Web natif de 4e Dimension doit fonctionner ;

2. Les préférences ci-dessous doivent être activées :
Préférences -> Web -> Web Services -> Autoriser requêtes Web Services ;

3. La propriété ci-dessous doit être activée pour chaque méthode publiée :
Propriétés de la méthode/Offert comme Web Service.

Une fois ces étapes de configuration effectuées, 4e Dimension gère automatiquement tous les aspects d’écoute et de réponse aux requêtes SOAP.

IV - Fournir une liste des images disponibles

Table Image

La démo propose des images stockées dans une table nommée [Images], représentée ci-dessous :

Le champ Name sert de clé unique pour les enregistrements de la table. En environnement de production, une clé du type entier long unique et non modifiable serait un meilleur choix. Une version améliorée du système pourrait gérer des attributs supplémentaires comme la date de prise de la photo, des notes sur le matériel photo et les réglages utilisés, le lieu de la prise de vue, des informations de contact, des mots-clés et le détail de la licence.

GetPictureList

La démo propose une méthode de Web Service SOAP nommée GetPictureList qui retourne un tableau comprenant les noms de toutes les images disponibles sous forme d’enregistrements dans la base. Voici un exemple de contenu de ce tableau :

Baby Rhino and Mother
Baby White Rhino
Cache flushing image
Day Gekko
Dog
Leopard
Magnifying glass
Spotted Eagle Rays
Superb Fairy Wren
Three Elephants
Yellow-Tailed Black Cockatoos
Zebra

Le code pour la fonction GetPictureList est fourni ci-dessous :

1. TOUT SELECTIONNER([Images])

2. TRIER([Images];[Images]Name)

3. TABLEAU ALPHA(80;getPicture_ImageNames_as;0)

4. SELECTION VERS TABLEAU([Images]Name;getPicture_ImageNames_as)

5. LIBERER ENREGISTREMENT([Images])

7. DECLARATION SOAP(getPicture_ImageNames_as;Est un tableau chaîne ;SOAP sortie ;"outPictureNames")

Dans une version améliorée du système, la fonction GetPictureList pourrait être réécrite pour accepter des arguments de recherche par taille d’image, auteur ou d’autres attributs comme la date ou les mots-clés.

Fournir une liste des formats d’images disponibles

4e Dimension stocke et prévisualise nativement les images dans le format PICT. PICT constitue une famille de formats MacOS qui sont rarement visualisables dans les navigateurs Web ou sur d’autres plateformes. Heureusement, 4e Dimension sait convertir les images en GIF et, si QuickTime 4 ou supérieur est installé, dans n’importe quel format supporté par l’installation Quicktime du serveur. En utilisant la commande LISTE TYPES IMAGES, le serveur d’images peut détecter tous les formats disponibles et les retourner sous forme de liste aux clients du Service Web. Un bénéfice de cette approche réside dans le fait que seul le serveur centralisé d’images requiert QuickTime. Les clients SOAP peuvent demander l’image dans un format adapté à l’affichage sur leur système, que ce soit GIF ou JPEG…

Le code de la méthode GetPictureFormatList publiée comme méthode SOAP GetPictureFormatList :

1. TABLEAU TEXTE(getPictureFormatMimeTypes_at;0)

2. COPIER TABLEAU(<>pictureFormatMimeTypes_at;getPictureFormatMimeTypes_at)

3. DECLARATION SOAP(getPictureFormatMimeTypes_at;Est un tableau texte ;SOAP sortie ;"outSupportedMIMETypes")

Cette méthode copie un tableau interprocess nommé <>pictureFormatMimeTypes_at dans un tableau process nommé getPictureFormatMimeTypes_at. Les types MIME sont chargés une fois au démarrage dans le tableau interprocess. Ces valeurs doivent être copiées dans un tableau process, car les réponses SOAP ne peuvent retourner que le paramètre traditionnel $0, des variables ou des tableaux process.

Note : Pour plus d’information sur les sources de données supportées pour les réponses SOAP, référez-vous au manuel de référence du langage de 4e Dimension ou à la note technique 4D-200503-07-FR « Retourner des données par Service Web (via SOAP) ».

La liste des types MIME stockée dans le tableau <>pictureFormatMimeTypes_at array est remplie par une méthode 4D nommée pictureInitializeFormatCodes qui s’exécute au démarrage. La commande LISTE TYPES IMAGES retourne les codes de type QuickTime sur quatre caractères, non pas les types MIME. Les types MIME sont indépendants de plateforme et constituent un choix mieux adapté aux Services Web. La méthode pictureInitializeFormatCodes convertit les codes QuickTime en types MIME. Dans la démo, la conversion de code QuickTime en type MIME est assurée grâce à la table [Picture_Format_Codes], représentée ci-dessous :

Le code de la méthode pictureInitializeFormatCodes :

1. ` -----------------------------------------------------

2. ` Réception des codes d’images depuis Quicktime

3. ` -----------------------------------------------------

4. TABLEAU ALPHA(4;<>pictureFormatCodes_as;0)

5. LISTE TYPES IMAGES(<>pictureFormatCodes_as)

7. ` -----------------------------------------------------

8. ` Ajout de 'GIFf', si non présent, car il des supporté directement par 4D

9. ` -----------------------------------------------------

10. C_ENTIER LONG($index)

11. $index:=0

12. $index:=Chercher dans tableau(<>pictureFormatCodes_as;"GIFf") `GIF ne requiert pas Quicktime

13. Si ($index<1)

14. INSERER LIGNES(<>pictureFormatCodes_as;1;1)

15. <>pictureFormatCodes_as{1}:="GIFf"

16. Fin de si

19. ` -----------------------------------------------------

20. ` Construction d’un tableau des types MIME

21. ` -----------------------------------------------------

22. C_ENTIER LONG($count)

23. $count:=0

24. $count:=Taille tableau(<>pictureFormatCodes_as)

26. TABLEAU TEXTE(<>pictureFormatMimeTypes_at;$count)

28. C_ALPHA(4;$type_s)

29. Boucle ($index;$count;1;-1) ` Bouclons à l’envers, car il se peut que nous détruisions des éléments en chemin

30. $type_s:=<>pictureFormatCodes_as{$index}

31. CHERCHER([Picture_Format_Codes];[Picture_Format_Codes]Code=$type_s)

33. Si (Enregistrements trouves([Picture_Format_Codes])=1)

34. <>pictureFormatMimeTypes_at{$index}:=[Picture_Format_Codes]MIME_Type

35. Sinon

36. SUPPRIMER LIGNES(<>pictureFormatCodes_as;$index;1)

37. SUPPRIMER LIGNES(<>pictureFormatMimeTypes_at;$index;1)

38. Fin de si

40. LIBERER ENREGISTREMENT([Picture_Format_Codes])

42. Fin de boucle

V - Charger, convertir et retourner des images

La démo propose plusieurs fonctions de Services Web pour retourner des images et des données sur les images. La plus simple est la méthode getPicture publiée comme méthode SOAP getPicture. La méthode attend deux paramètres d’entrée, un nom d’image et un type MIME d’image. Un développeur de client de Service Web peut découvrir les valeurs acceptées pour ces deux arguments en appelant les fonctions GetPictureList et GetPictureFormatList. Cette approche permet aux clients de construire dynamiquement et interactivement des requêtes valides afin d’obtenir des images dans des formats spécifiques.

Ci-dessous une version résumée de la méthode getPicture :

1. ` -----------------------------------------------------

2. ` Déclare les entrées/sorties pour 4DWSDL et la construction du message SOAP

3. ` -----------------------------------------------------

4. DECLARATION SOAP($1;Est un texte ;SOAP entrée ;"inPictureName")

5. DECLARATION SOAP($2;Est un texte ;SOAP entrée ;"inPictureMimeType")

6. DECLARATION SOAP(getPicture_ResultPicture_x;Est un BLOB ;SOAP sortie ;"outPictureBlob")

8. ` -----------------------------------------------------

9. ` Déclare les paramètres pour l’exécution et la compilation

10. ` -----------------------------------------------------

11. C_TEXTE($1;$pictureName_t)

12. C_TEXTE($2;$pictureMimeType_t)

14. ` -----------------------------------------------------

15. ` Prépare les valeurs de retour

16. ` -----------------------------------------------------

17. C_BLOB(getPicture_ResultPicture_x)

18. ` <-- variable de sortie (nous n’utilisons pas $0 car les images peuvent être importantes)

19. FIXER TAILLE BLOB(getPicture_ResultPicture_x;0)

21. ` -----------------------------------------------------

22. ` Effectue le contrôle d’erreur sur les entrées

23. ` -----------------------------------------------------

24. C_ENTIER LONG($errorCode_l)

25. $errorCode_l:=0

27. C_ENTIER LONG($soapFaultType_l)

28. $soapFaultType_l:=SOAP erreur client

30. Si (Nombre de parametres<2)

31. $errorCode_l:=1 ` Pas assez de paramètres

33. Sinon

34. $pictureName_t:=$1

35. $pictureMimeType_t:=$2

36. CHERCHER([Images];[Images]Name=$pictureName_t)

37. C_ALPHA(4;$format_s)

38. $format_s:=""

39. $format_s:=pictureGet4DCodeFromMimeType ($pictureMimeType_t)

41. Au cas ou

42. : ($format_s="")

43. $errorCode_l:=2 ` Type MIME demandé non supporté ou non reconnu

44. : (Enregistrements trouves([Images])=0)

45. $errorCode_l:=3 ` Image demandée non trouvée

46. : (Enregistrements trouves([Images])>1)

47. $errorCode_l:=4 ` Trouvé plusieurs images

48. Fin de cas

50. Fin de si ` (Nombre de parametres<2)

53. Si ($errorCode_l=0)

54. ` -----------------------------------------------------

55. ` Corps de la méthode

56. ` -----------------------------------------------------

57. ` Pas de $0 nécessaire. 4D lit les déclarations de sortie SOAP et retourne les valeurs des variables

58. IMAGE VERS BLOB([Images]Picture;getPicture_ResultPicture_x;$format_s)

59. LIBERER ENREGISTREMENT([Images])

60. Fin de si

62. Si ($errorCode_l#0)

63. C_TEXTE($errorText_t)

64. $errorText_t:=getPictureErrorText ($errorCode_l)

65. ENVOYER ERREUR SOAP($soapFaultType_l;$errorText_t)

66. Fin de si

VI - Tâche de client SOAP : récupérer une image

Les BLObs inclus dans les messages SOAP sont convertis en textes base64 pour le transfert. Dans 4e Dimension retrouver l’image initiale s’effectue simplement, comme le montre l’exemple de méthode proxy de client SOAP ci-dessous :

1. C_TEXTE($1;$name_t)

2. C_TEXTE($2;$mimeType_t)

3. C_POINTEUR($3;$picture_p)

4. $name_t:=$1

5. $mimeType_t:=$2

6. $picture_p:=$3

7. FIXER PARAMETRE WEB SERVICE("inPictureName";$name_t)

8. FIXER PARAMETRE WEB SERVICE("inPictureMimeType";$mimeType_t)

10. APPELER WEB SERVICE(requestGetAccessURL ;"ReturningPicturesWithSoap#getPicture";

11. "getPicture";"http://www.4d.com/namespace/default";Web Service dynamique )

13. Si (OK=1)

14. C_BLOB($pictureBlob_x)

15. LIRE RESULTAT WEB SERVICE($pictureBlob_x;"outPictureBlob";*) ` Nettoyage mémoire

16. BLOB VERS IMAGE($pictureBlob_x;$picture_p->)

18. ` NOTE:

19. ` BLOB VERS IMAGE peut seulement convertir les formats compatibles Quickime 4 et au-delà

20. ` Par exemple, les images MacPaint ( code = 'PNTG', MIME type = image/x-macpaint)

21. ` ne sont pas toujours converties correctement. Dans de tels cas, le BLOB est formé correctement,

22. ` mais l’image résultante est vide. Si vous disposez d’autres codes de traitement d’images ou d’un plug-in

23. ` vous pouvez les appliquer au BLOB au lieu d’utiliser BLOB VERS IMAGE

24. Fin de si

VII - Retourner des informations additionnelles

La table [Images] de la base de données de démo comprend plusieurs attributs de l’image : hauteur, largeur, taille brute, auteurs et description. En utilisant SOAP, il est facile d’écrire des méthodes qui retournent l’un ou plusieurs de ces attributs à la fois. Ces fonctions permettent aux clients SOAP d’agir plus intelligemment et sélectivement. Par exemple, demander une vignette avant de charger des images lourdes, préconstruire les balises HTML d’images avec les largeurs et hauteurs ou charger une description de l’image, tout cela est possible simplement avec les Services Web.

La démo implémente quelques-unes de ces idées avec les commandes décrites ci-dessous :

- getPictureDate retourne une description de l’image, de sa taille, sa largeur, sa hauteur et des auteurs ;

- getPictureListExtended étend la commande getPictureList pour inclure la description, la taille, la largeur, la hauteur et les auteurs de chaque image ;

- getPictureWithType retourne l’image avec son code de type MIME ;

- getThumbnail retourne une vignette de l’image générée dynamiquement.

Note de réalisation : les sources d’images

La démo charge les images depuis les enregistrements pour des raisons de simplicité du code. Dans un système de production, il est souvent beaucoup plus efficace de stocker les images lourdes en dehors de la base de données dans des documents et de ne stocker dans la base que les chemins d’accès à ces images. Des plug-ins comme 4D Chart et 4D Draw sont très utiles pour créer des images à partir de données dynamiques ou saisies.

En pratique les images peuvent provenir de n’importe laquelle des sources ci-dessous :

Sources

Commandes à utiliser

4D Chart et autres plug-ins:

ch Zone vers image

Documents sur disque :

Ouvrir document et RECEVOIR PAQUET ou DOCUMENT VERS BLOB ou LIRE FICHIER IMAGE ou CHARGER ET COMPRESSER IMAGE

Documents sur réseau :

TCP_Open et TCP_receiveBLOB

Ressources PICT :

LIRE RESSOURCE IMAGE

Images de Bibliothèque :

LIRE IMAGE DANS BIBLIOTHEQUE

Enregistrements :

Les images peuvent être stockées de manière native dans des enregistrements.

VIII - Bases exemples

Téléchargez les bases exemples :

Base 4D 2004

Base 4D 2003 Windows

Base 4D 2003 MacOS