7.2 Importation de documents par XML
Ce chapitre indique comment importer des documents au format XML.
L'importation de document peut être faite à l'aide de fichiers XML tels que ceux produits par l'exportation XML.
Le type de fichier accepté est soit un fichiers XML avec la balise root
<documents>
, soit un fichier archive zip
contenant un ensemble de
fichiers XML. Ces fichiers XML doivent être conformes au schéma XML associé à la
famille de document.
7.2.1 Schéma XML d'une famille
En ligne de commande, l'action FDL:FDL_FAMILYSCHEMA
permet de récupérer ce
schéma XML. L'argument id
doit contenir l'identifiant de la
famille dont on veut le schéma.
./wsh.php --app=FDL --action=FDL_FAMILYSCHEMA --id=ZOO_ANIMAL > zoo_animal.xsd
Les fichiers XML à importer doivent être conforme au schéma de la famille. Il est recommandé de valider les fichiers XML produits à l'aide du schéma avant importation.
7.2.2 Relation
Pour déclarer une relation avec un autre document, l'attribut name
permet
d'indiquer la référence (nom logique) du document lié.
<an_classe name="Reptilia">Reptile</an_classe>
L'attribut id
permet d'indiquer la référence système (numérique). Ceci ne peut
fonctionner que sur une base de données identifiée car les références systèmes
varient d'une base à une autre.
<an_espece id="4563">Alligator</an_espece>
Si ni l'attribut name
ni l'attribut id
n'est indiqué, une recherche par
titre sera faite afin de trouver automatiquement le document qui a le même titre
en cohérence avec la famille déclarée dans la relation au niveau de la famille.
Si aucun identifiant n'est trouvé l'exportation sera abandonnée.
<an_espece>Alligator</an_espece>
7.2.3 Fichier inline
Des fichiers peuvent être enregistrés pour les attributs de type file ou image.
Les fichiers encodés contenus dans le XML sont insérés dans le document et remplace le fichier original. Le contenu du fichier doit être encodé en base64.
<zoo_animal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="zoo_animal.xsd" name="aliRotor" title="Rotor" > <an_identification><an_nom>Rotor</an_nom> <an_tatouage xsi:nil="true"/> <an_espece name="ZOO_ESP_ALLI">Alligator</an_espece <an_ordre>Crocodiliens</an_ordre> <an_classe name="Reptilia">Reptilia</an_classe> <an_sexe>M</an_sexe> <an_photo mime="image/jpeg; charset=binary" title="1387_IMG_1684AFC2.jpg">/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgQFFAH/9k=</an_photo> <an_gardien xsi:nil="true"/> <an_naissance>2012-08-03</an_naissance> <an_entree xsi:nil="true"/> <an_pere>Théodor</an_pere> <an_mere>Éléonore</an_mere> </an_identification> </zoo_animal>
Dans cet exemple la balise an_pĥoto
contient l'image. L'attribut title
contient le nom du fichier. S'il est vide, le nom du fichier sera noname
.
L'attribut mime
est obligatoire, il contient le typemime du
fichier attaché.
7.2.4 Entêtes des fichiers XML
L'entête d'un document importé en XML contient les informations suivantes :
<zoo_animal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="zoo_animal.xsd" title="Babette Junior" revision="1" modification-date="2012-08-01T09:51:14" version="" state="alive">
Les attributs title
, revision
, modification-date
, version
présents lors
d'une exportation XML sont calculés. Ils sont ignorés lors de l'importation.
De même l'attribut state n'est pas pris en compte. En revanche, les valeurs
de ces attributs sont disponibles en informations complémentaires dans
les méthodes ::preImport()
et ::postImport()
pour réaliser un traitement
particulier.
Les attributs optionnels id
, name
, folders
sont pris en compte lors de
l'importation.
- name
-
Indique l'identifiant logique d'un document.
L'utilisation de cette propriété indique qu'on va créer un document avec ce nom logique ou mettre à jour le document portant ce nom logique.
- folders
-
Indique les noms logiques des dossiers dans lesquels le document doit être inséré.
S'il y a plusieurs dossiers, il faut séparer les noms par des virgules.
- id
-
Indique l'identifiant système d'un document.
L'utilisation de cette propriété indique qu'on va créer ou mettre à jour le document portant cet identifiant.
En son absence, la base génère un nouvel identifiant.
Attention : cet identifiant est propre à une base, et ne peut qu'exceptionnellement être utilisé d'une base à l'autre.
Note : Si l'id
et le name
sont présent simultanément alors l'id
est utilisé
et pas le name
.
7.2.5 Clefs d'importation XML
Avec la politique de mise à jour de document (par défaut), les documents sans
identifiants recherchent un document similaire avec les clefs d'importation. La
clef d'importation par défaut est title
. Si un document et un seul de la même
famille avec le même titre a été trouvé alors il sera considéré comme une mise à
jour.
La clef d'importation peut être changée en utilisant l'attribut key
:
<zoo_animal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="zoo_animal.xsd" key="an_tatouage" revision="0" modification-date="2010-06-16T09:07:37" version="" state=""> <an_identification> <an_nom>Gérard</an_nom> <an_espece id="1131">Antilope</an_espece> <an_tatouage>32</an_tatouage> <an_enfant_t><an_enfant id="1148">Totor Alligator</an_enfant></an_enfant_t> <an_enfant_t><an_enfant id="1147">Alli Alligator</an_enfant></an_enfant_t> </an_identification> </zoo_animal>
Dans cet exemple, ce sera le tatouage qui sera pris comme référence. Si un
animal de même tatouage est trouvé il sera mis à jour sinon il sera ajouté. Il
est possible d'avoir une clef secondaire en ajoutant après une virgule un
deuxième attribut : key="an_tatouage,an_espece"
.
Cette directive est équivalente à la clef KEYS
de l'importation CSV.
7.2.6 Importer des documents avec un simple fichier XML
Le fichier XML à importer doit contenir l'ensemble des documents correspondants.
La balise principale est documents
.
animaux.xml
<documents> <zoo_animal> <an_identification> <an_nom>Gérard</an_nom> <an_espece id="1131">Alligator</an_espece> <an_tatouage>32</an_tatouage> <an_enfant_t><an_enfant id="1148">Totor Alligator</an_enfant></an_enfant_t> <an_enfant_t><an_enfant id="1147">Alli Alligator</an_enfant></an_enfant_t> </an_identification> </zoo_animal> <zoo_animal> <an_identification> <an_nom>Bob</an_nom> <an_espece id="1134">Agouti</an_espece> <an_tatouage>31</an_tatouage> </an_identification> </zoo_animal> </documents>
La commande à lancer pour l'importation en console est :
./wsh.php --api=importDocuments --file=animaux.xml
7.2.7 Importer des documents en XML avec une archive
7.2.7.1 Structure de l'archive XML
La structure de l'archive doit contenir un ensemble de fichiers XML correspondant chacun à un seul document. Chaque fichier est un XML qui est conforme au schéma XML de la famille. Les fichiers XML doivent être placés uniquement à la racine de l'archive. Le format du fichier archive pour l'importation XML est de type zip.
Exemple :
$ unzip -l animals.zip Archive: animals.zip Length Date Time Name --------- ---------- ----- ---- 983 2013-05-29 10:19 Gator.xml 947 2013-05-29 10:29 Olgator.xml 15159 2013-05-29 09:59 zoo_animal.xsd --------- ------- 17089 3 files
Cette archive contient deux documents. Le fichier schéma zoo_animal.xsd
est
facultatif. Il est enregistré à titre indicatif pour pouvoir l'utiliser dans des
éditeurs XML. Il est ignoré lors de l'importation.
La commande à lancer pour l'importation en console est :
./wsh.php --api=importDocuments --file=animals.zip
Note : L'option --archive=yes
n'est pas à utiliser dans ce cas. Elle est
réservée à l'importation d'archive.
7.2.7.2 Insérer un fichier avec le format d'archive XML
Les fichiers attachés peuvent être insérés inline ou par référence à un fichier local à l'archive.
Les fichiers à attacher doivent être insérés dans des sous-répertoires.
$ unzip -l animals.zip Archive: animals.zip Length Date Time Name --------- ---------- ----- ---- 0 2013-05-29 10:27 Photos/ 2523262 2013-05-29 09:53 Photos/Gator.png 168900 2013-05-29 10:27 Photos/Reptilia_American_alligator.jpg 983 2013-05-29 10:19 Gator.xml 947 2013-05-29 10:29 Olgator.xml 15159 2013-05-29 09:59 zoo_animal.xsd --------- ------- 2709251 6 files
Dans ce exemple, les deux photos à insérer dans les documents sont dans le répertoire Photos.
Gator.xml
<?xml version="1.0" encoding="UTF-8"?> <zoo_animal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > <an_identification> <an_nom>Gator</an_nom> <an_tatouage xsi:nil="true"/> <an_espece name="ZOO_ESP_ALLI">Alligator</an_espece> <an_ordre>Crocodiliens</an_ordre> <an_classe name="Reptilia">Reptilia</an_classe> <an_sexe>F</an_sexe> <an_photo mime="image/png; charset=binary" href="Photos/Gator.png" title="Gator.png"/> </an_identification> </zoo_animal>
Le fichier lié doit être indiqué dans l'attribut XML href
correspondant à la
balise de l'attribut fichier. Dans ce cas, il faut que la balise XML soit
autofermante, sinon cela sera considéré comme un fichier inline et une erreur
d'importation se produira car le fichier inline ne doit pas contenir
d'attribut href
.