ONYX - 9.0 - Utilisation - mapSoapRunStreamFromPost

Différence entre versions

De MappingDoc
(Open Api Specification 3 (YAML))
 
(18 révisions intermédiaires par 2 utilisateurs non affichées)
Ligne 1 : Ligne 1 :
===Introduction===
+
<languages/>
 +
<translate>
 +
===Introduction=== <!--T:1-->
 
mapSoapRunStreamFromPost est une méthode du WebService "mapsoapserver.exe"
 
mapSoapRunStreamFromPost est une méthode du WebService "mapsoapserver.exe"
  
 +
<!--T:2-->
 
Cas d'usage :
 
Cas d'usage :
  
*Envoyer un fichier à Mapping pour récupérer de manière synchrone un fichier réponse (par exemple transmission d'un XML et réception d'un PDF en retour)
+
<!--T:3-->
*Envoyer un fichier de grande taille à Mapping, pour un traitement asynchrone
+
*Envoyer un fichier à Mapping pour récupérer de manière synchrone un fichier réponse (par exemple transmission d'un XML et réception d'un PDF en retour).
 +
*Envoyer un fichier de grande taille à Mapping, pour un traitement asynchrone. Tous types de fichiers sont acceptés.
  
===Utilisation===  
+
===Utilisation=== <!--T:4-->
  
*Methode POST
+
<!--T:5-->
 +
*Methode POST ou GET
 +
:<small>''Si la méthode POST est à privilégier, il reste cependant possible d'utiliser également la méthode GET. Cette dernière étant nécessaire pour passer les paramètres dans l'URL en cas d'invocation du WebService directement à partir d'un formulaire HTML pour réaliser des opérations simples et sans upload de fichier : <code><form action="http://mappingserver/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost" method="get"></code>''</small>
 +
*Paramètres :
 +
:- Workflow : nom du workflow Mapping à invoquer
 +
:- Couples key/value : méta données
 +
:- Fichier à envoyer
 +
:- Type de réponse (XML avec fichier encodé en base64, ou directement le fichier)
 +
::Exemples : XML, PDF, XPS, TXT, CSV, EXE, JPG, PNG, ZIP etc...
 +
 
 +
<!--T:6-->
 
*Contrairement à la méthode mapUploadFile, l'utilisation de mapSoapRunStreamFromPost permet d'invoquer un workflow
 
*Contrairement à la méthode mapUploadFile, l'utilisation de mapSoapRunStreamFromPost permet d'invoquer un workflow
*Le contenu du fichier doit être passé directement à la place de l'enveloppe XML, tel quel (pas d'encodage en base64)
+
*Le contenu du fichier doit être passé directement dans le corps, sans enveloppe et sans encodage en base64.
*Tous les paramètres <key/value> doivent être passés exclusivement dans l'URL (il n'y a pas d'enveloppe XML)
+
*Tous les paramètres <key/value> doivent être passés exclusivement dans l'URL (il n'y a pas d'enveloppe XML pour le corps, ni de prise en charge du multipart/form-data)
 
*Dans le workflow :
 
*Dans le workflow :
**Les couples key/value sont récupérables sous forme de variables [%xxxx%]
+
**Les couples key/value sont utilisables dans le workflow sous forme de variables [%xxxx%]
**Le fichier est identifié par [%MAP_FILE_IN%]
+
**Le fichier est identifié par la variable [%MAP_FILE_IN%]
 +
* Si le paramètre "getobject=1" est ajouté à l'URL, le corps de la réponse contient directement le fichier issu du workflow sans enveloppe XML ni encodage en base64.
  
===Exemple de requête SOAP===
+
===Exemple de requête SOAP ou REST=== <!--T:7-->
  
 +
<!--T:8-->
 
'''Avec un fichier PDF'''
 
'''Avec un fichier PDF'''
  
<code>curl -u mapadmin:mapadmin -X POST --data-binary "@/tmp/mon_fichier.pdf" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?key=workflow&value=testsoap&key=macle1&value=mavaleur1&key=macle2&value=mavaleur2"</code>
+
<!--T:9-->
 +
<code>curl -u mapadmin:mapadmin -X POST --data-binary "@/tmp/mon_fichier.pdf" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?workflow=testsoap&key=macle1&value=mavaleur1&key=macle2&value=mavaleur2"</code>
  
 +
<!--T:10-->
 
'''Avec un fichier XML'''
 
'''Avec un fichier XML'''
  
<code>curl -u mapadmin:mapadmin -X POST --data "@/tmp/mon_fichier.xml" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?key=workflow&value=testsoap&key=typdoc&value=facture&key=enseigne&value=mag_paris"</code>
+
<!--T:11-->
 +
<code>curl -u mapadmin:mapadmin -X POST --data "@/tmp/mon_fichier.xml" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?workflow=testsoap&key=typdoc&value=facture&key=enseigne&value=mag_paris&getobject=1"</code>
  
  
 +
<!--T:12-->
 
<u>Remarques</u> :  
 
<u>Remarques</u> :  
  
 +
<!--T:13-->
 
*Le paramètre "'''worfklow'''", permet de spécifier le nom du workflow à invoquer. S'il n'est pas renseigné, c'est le workflow "root" qui est appelé.
 
*Le paramètre "'''worfklow'''", permet de spécifier le nom du workflow à invoquer. S'il n'est pas renseigné, c'est le workflow "root" qui est appelé.
*"macle1", "mapcle2", typdoc et enseigne sont des exemples de méta données récupérables dans le workflow, permettant à Mapping d'effectuer le traitement adapté au fichier.
+
*"macle1", "mapcle2", "typdoc" et "enseigne" sont des exemples de méta données récupérables dans le workflow, permettant à Mapping d'effectuer le traitement adapté au fichier.
 
*La présence du @ dans l'option --data-binary permet de spécifier qu'il s'agit d'un fichier.
 
*La présence du @ dans l'option --data-binary permet de spécifier qu'il s'agit d'un fichier.
 
*Dans le premier exemple, le fichier transmis étant un PDF, l'option utilisée est --data-binary , mais pour les fichiers "texte", comme l'exemple XML, l'option pourrait être "--data"
 
*Dans le premier exemple, le fichier transmis étant un PDF, l'option utilisée est --data-binary , mais pour les fichiers "texte", comme l'exemple XML, l'option pourrait être "--data"
 +
* Dans le 2ème exemple, le paramètre "getobject=1" permet d'avoir une réponse de type "octet-stream", sans enveloppe XML ni encodage en base64
  
===Exemple de workflow pour traitement asynchrone===
+
===Exemple de workflow pour traitement asynchrone=== <!--T:14-->
  
 +
<!--T:15-->
 
*La variable param1 récupère le contenu de macle1 (boite paramètre)
 
*La variable param1 récupère le contenu de macle1 (boite paramètre)
 
*La variable param2 récupère le contenu de macle2 (boite paramètre)
 
*La variable param2 récupère le contenu de macle2 (boite paramètre)
Ligne 43 : Ligne 66 :
 
**La coche "Ajouter les paramètres courants" permettent de transmettre les variables param1 et param2 avec le fichier dans la file d'attente "MON_ENTRY"
 
**La coche "Ajouter les paramètres courants" permettent de transmettre les variables param1 et param2 avec le fichier dans la file d'attente "MON_ENTRY"
  
 +
<!--T:16-->
 
<br />
 
<br />
 
[[Fichier:OX S workflow mapsoaprunstreamfrompost1.png|alt=|centré|354x354px|sans_cadre]]
 
[[Fichier:OX S workflow mapsoaprunstreamfrompost1.png|alt=|centré|354x354px|sans_cadre]]
 
[[Fichier:OX S Workflow mapsoaprunstreamfrompost2.png|alt=|centré|828x828px|sans_cadre]]
 
[[Fichier:OX S Workflow mapsoaprunstreamfrompost2.png|alt=|centré|828x828px|sans_cadre]]
  
 +
<!--T:17-->
 
              
 
              
  
===Exemple de workflow pour traitement synchrone===
+
===Exemple de workflow pour traitement synchrone=== <!--T:18-->
  
 +
<!--T:19-->
 
*La variable param1 récupère le contenu de macle1 (boite paramètre)
 
*La variable param1 récupère le contenu de macle1 (boite paramètre)
 
*La variable param2 récupère le contenu de macle2 (boite paramètre)
 
*La variable param2 récupère le contenu de macle2 (boite paramètre)
Ligne 58 : Ligne 84 :
  
  
 +
<!--T:20-->
 
{{warning}} La boite permettant de renvoyer le résultat au consommateur doit se trouver dans le Workflow déclenché par le WebService. Elle ne peut en aucun cas se trouver dans un sous workflow invoqué par un "call".
 
{{warning}} La boite permettant de renvoyer le résultat au consommateur doit se trouver dans le Workflow déclenché par le WebService. Elle ne peut en aucun cas se trouver dans un sous workflow invoqué par un "call".
 
+
</translate>
  
 
[[Fichier:OX S mapsoaprunstreamfrompost.png|centré|350x350px|alt=|sans_cadre]]
 
[[Fichier:OX S mapsoaprunstreamfrompost.png|centré|350x350px|alt=|sans_cadre]]
Ligne 67 : Ligne 94 :
 
===Open Api Specification 3 (YAML)===
 
===Open Api Specification 3 (YAML)===
  
openapi: "3.0.0"  
+
<syntaxhighlight lang="yaml">
info:
+
  openapi: "3.0.0"  
  title: mapSoapRunStreamFromPost
+
  info:
  description: Send a file to Mapping
+
    title: mapSoapRunStreamFromPost
  version: "0.0.0"
+
    description: Send a file to Mapping
servers:
+
    version: "0.0.0"
  - url: "{protocol}://{server}:{port}/mapsoapserver.exe"
+
  servers:
    description: Local Server
+
    - url: "{protocol}://{server}:{port}/mapsoapserver.exe"
paths:
+
      description: Local Server
  /mapSoapRunStreamFromPost:
+
      variables:
    post:
+
        protocol:
      summary: Send a file to a Mapping Workflow
+
          default: 'http'
      tags:
+
        server:
        - mapSoapRunStreamFromPost
+
          default: '127.0.0.1'
      parameters:  
+
        port:
        - name: workflow
+
          default: '8002'
          in: query
+
  paths:
          required: false
+
    /mapSoapRunStreamFromPost:
          description: Name of the workflow to call
+
      post:
          schema:
+
        summary: Send a file to a Mapping Workflow
            type: string
+
        tags:
            example: my_workflow
+
          - mapSoapRunStreamFromPost
        - name: metadatas
+
        parameters:  
          in: query
+
          - name: workflow
          required: false
+
            in: query
          description: array of metadatas [key/value]
+
            required: false
          schema:
+
            description: Name of the workflow to call
            type: array
+
            schema:
            items:
+
              type: string
              type: object
+
              example: my_workflow
              properties:
+
          - name: key
                key:
+
            in: query
                  type: string
+
            required: false
                value:
+
            description: key
                  type: string
+
            explode: true
      responses:
+
            style: form
        '200':
+
            schema:
          description: Base64 response from sent by the Workflow
+
              type: array
          content:
+
              items:
            application/xml:
+
                type: string
              schema:
+
              example: my_key
                type: object
+
          - name: value
                xml:  
+
            in: query
                  name: 'Envelope'
+
            required: false
                  prefix: 'soap'
+
            description: value
                  namespace: "http://schemas.xmlsoap.org/soap/envelope/"
+
            explode: true
                properties:
+
            style: form
                  Body:
+
            schema:
                    type: object
+
              type: array
                    xml:
+
              items:
                      prefix: soap
+
                type: string
                    properties:
+
              example: my_value
                      mapSoapRunStreamFromPostResponse:
+
        requestBody:
                        type: object
+
          required: true
                        properties:
+
          content:
                          mapSoapRunStreamFromPostResult:
+
            application/octet-stream:
                            type: object
+
              schema:
                            properties:
+
                type: string
                              document:
+
                format: binary
                                type: string
+
        responses:
                                format: byte
+
          '200':
                                description: base64 content
+
            description: Base64 response sent by the Workflow
 +
            content:
 +
              application/xml:
 +
                schema:
 +
                  type: object
 +
                  xml:  
 +
                    name: 'Envelope'
 +
                    prefix: 'soap'
 +
                    namespace: "http://schemas.xmlsoap.org/soap/envelope/"
 +
                  properties:
 +
                    Body:
 +
                      type: object
 +
                      xml:
 +
                        prefix: soap
 +
                      properties:
 +
                        mapSoapRunStreamFromPostResponse:
 +
                          type: object
 +
                          properties:
 +
                            mapSoapRunStreamFromPostResult:
 +
                              type: object
 +
                              properties:
 +
                                document:
 +
                                  type: string
 +
                                  format: byte
 +
                                  description: base64 content
 +
              application/octet-stream:
 +
                schema:
 +
                  type: string
 +
                  format: binary
 +
</syntaxhighlight>

Version actuelle datée du 4 mars 2021 à 11:08

Autres langues :
English • ‎français

Introduction

mapSoapRunStreamFromPost est une méthode du WebService "mapsoapserver.exe"

Cas d'usage :

  • Envoyer un fichier à Mapping pour récupérer de manière synchrone un fichier réponse (par exemple transmission d'un XML et réception d'un PDF en retour).
  • Envoyer un fichier de grande taille à Mapping, pour un traitement asynchrone. Tous types de fichiers sont acceptés.

Utilisation

  • Methode POST ou GET
Si la méthode POST est à privilégier, il reste cependant possible d'utiliser également la méthode GET. Cette dernière étant nécessaire pour passer les paramètres dans l'URL en cas d'invocation du WebService directement à partir d'un formulaire HTML pour réaliser des opérations simples et sans upload de fichier : <form action="http://mappingserver/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost" method="get">
  • Paramètres :
- Workflow : nom du workflow Mapping à invoquer
- Couples key/value : méta données
- Fichier à envoyer
- Type de réponse (XML avec fichier encodé en base64, ou directement le fichier)
Exemples : XML, PDF, XPS, TXT, CSV, EXE, JPG, PNG, ZIP etc...
  • Contrairement à la méthode mapUploadFile, l'utilisation de mapSoapRunStreamFromPost permet d'invoquer un workflow
  • Le contenu du fichier doit être passé directement dans le corps, sans enveloppe et sans encodage en base64.
  • Tous les paramètres <key/value> doivent être passés exclusivement dans l'URL (il n'y a pas d'enveloppe XML pour le corps, ni de prise en charge du multipart/form-data)
  • Dans le workflow :
    • Les couples key/value sont utilisables dans le workflow sous forme de variables [%xxxx%]
    • Le fichier est identifié par la variable [%MAP_FILE_IN%]
  • Si le paramètre "getobject=1" est ajouté à l'URL, le corps de la réponse contient directement le fichier issu du workflow sans enveloppe XML ni encodage en base64.

Exemple de requête SOAP ou REST

Avec un fichier PDF

curl -u mapadmin:mapadmin -X POST --data-binary "@/tmp/mon_fichier.pdf" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?workflow=testsoap&key=macle1&value=mavaleur1&key=macle2&value=mavaleur2"

Avec un fichier XML

curl -u mapadmin:mapadmin -X POST --data "@/tmp/mon_fichier.xml" "http://192.168.100.14:8002/cgi-bin/mapsoapserver.exe/mapSoapRunStreamFromPost?workflow=testsoap&key=typdoc&value=facture&key=enseigne&value=mag_paris&getobject=1"


Remarques :

  • Le paramètre "worfklow", permet de spécifier le nom du workflow à invoquer. S'il n'est pas renseigné, c'est le workflow "root" qui est appelé.
  • "macle1", "mapcle2", "typdoc" et "enseigne" sont des exemples de méta données récupérables dans le workflow, permettant à Mapping d'effectuer le traitement adapté au fichier.
  • La présence du @ dans l'option --data-binary permet de spécifier qu'il s'agit d'un fichier.
  • Dans le premier exemple, le fichier transmis étant un PDF, l'option utilisée est --data-binary , mais pour les fichiers "texte", comme l'exemple XML, l'option pourrait être "--data"
  • Dans le 2ème exemple, le paramètre "getobject=1" permet d'avoir une réponse de type "octet-stream", sans enveloppe XML ni encodage en base64

Exemple de workflow pour traitement asynchrone

  • La variable param1 récupère le contenu de macle1 (boite paramètre)
  • La variable param2 récupère le contenu de macle2 (boite paramètre)
  • La boite "Print" permet d'envoyer le fichier dans la file d'attente "MON_ENTRY" (boite "Imprimer")
    • Le fichier transmis dans le flux du WebService est [%MAP_FILE_IN%]
    • La coche "Ajouter les paramètres courants" permettent de transmettre les variables param1 et param2 avec le fichier dans la file d'attente "MON_ENTRY"


            

Exemple de workflow pour traitement synchrone

  • La variable param1 récupère le contenu de macle1 (boite paramètre)
  • La variable param2 récupère le contenu de macle2 (boite paramètre)
  • Composition du document XML en XPS (boite Designer)
  • Conversion du XPS en PDF (Boite de conversion vers PDF)
  • Envoi du résultat dans la réponse de la requête SOAP (Boite "Affichage dans le navigateur")


Warning-300px.png La boite permettant de renvoyer le résultat au consommateur doit se trouver dans le Workflow déclenché par le WebService. Elle ne peut en aucun cas se trouver dans un sous workflow invoqué par un "call".


Open Api Specification 3 (YAML)

  openapi: "3.0.0" 
  info:
    title: mapSoapRunStreamFromPost
    description: Send a file to Mapping
    version: "0.0.0"
  servers:
    - url: "{protocol}://{server}:{port}/mapsoapserver.exe"
      description: Local Server
      variables:
        protocol:
          default: 'http'
        server:
          default: '127.0.0.1'
        port:
          default: '8002'
  paths:
    /mapSoapRunStreamFromPost:
      post:
        summary: Send a file to a Mapping Workflow
        tags:
          - mapSoapRunStreamFromPost
        parameters: 
          - name: workflow
            in: query
            required: false
            description: Name of the workflow to call
            schema:
              type: string
              example: my_workflow
          - name: key
            in: query
            required: false
            description: key
            explode: true
            style: form
            schema:
              type: array
              items:
                type: string
              example: my_key
          - name: value
            in: query
            required: false
            description: value
            explode: true
            style: form
            schema:
              type: array
              items:
                type: string
              example: my_value
        requestBody:
          required: true
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        responses:
          '200':
            description: Base64 response sent by the Workflow
            content:
              application/xml:
                schema:
                  type: object
                  xml: 
                    name: 'Envelope'
                    prefix: 'soap'
                    namespace: "http://schemas.xmlsoap.org/soap/envelope/"
                  properties:
                    Body:
                      type: object
                      xml:
                        prefix: soap
                      properties:
                        mapSoapRunStreamFromPostResponse:
                          type: object
                          properties:
                            mapSoapRunStreamFromPostResult:
                              type: object
                              properties:
                                document:
                                  type: string
                                  format: byte
                                  description: base64 content
              application/octet-stream:
                schema:
                  type: string
                  format: binary