Les modèles WebServices

Généralités

Un modèle Webservice permet de se connecter à :

Un WebService de type REST (pour lesquels données sont accessibles via une seule URL)
Renvoyant des données au formats JSON, XML ou CSV
Ayant un protocole d'identification login/password ou OAuth 2.0

La configuration d'une connexion à un WebService doit respecter la documentation du WebService : chaque WebService a ses propres règles de nommage, d'authentification, de pagination, et de structure des données retournées.

Paramétrage des modèles

Important

Le nom du modèle étant utilisé comme nom de table (et donc dans la requête pseudo SQL), il ne faut pas utiliser ne nom réservé, de caractère spéciaux, ou d'espace dans les noms de modèle.

Complément d'URL

Complément d'URL : ce paramètre modifie la propriété "URL" de la ConnexionString définie dans la connexion du modèle.
L'URL finale est construite à partir de la concaténation de l'URI de la connexion REST avec complément d'url d'accès aux données.
Cette modification permet de factoriser la partie commune d'une URL de connexion au niveau de la connexion, et de ne définir dans le modèle que la partie dépendante des données à acceder

Chaine de connexion (ConnexionString)

Cette propriété permet de personnaliser la ConnexionString de la connexion pour le modèle.
Il est possible d'ajouter de nouveaux paramètres, ou d'écraser un/des paramètre(s) de la connexion.

Les paramètres

Ils s'ajoutent à l'URL d'accès aux données.
Ces paramètres sont consolidés avec ceux de la connexion WebService.
Lorsque des paramètres ont le même nom, ceux du modèle écrasent ceux de la connexion.

Tableau 4.1. Exemples de paramètres ConnexionString :

Libellé	Valeur	Description
CustomHeaders	par exemple :Authorization:	permet l'ajout de paramètres supplémentaires dans le header de la requête.
CustomURLParams	par exemple : fields=xxx, xxxx, xxxx	permet l'ajout de paramètres supplémentaires dans l'url de la requête.
Timeout	par exemple : 60	permet de configurer le délai à attendre si le nombre maximum de requêtes est atteint (Code erreur 429 : Too many requests). Ce délai a une valeur par défaut de 60 secondes et il y aura 4 essais avant de retourner une erreur.
Other	par exemple : TableName=NomdeLaTable	Permet de spécifier des paramètres. Par Exemple : Le nom de la table généré automatiquement portera le nom du modèle. Il est possible de paramétrer manuellement le nom de la table.

Avertissement

Le renommage des tables du mapping d'un modèle sur une Connexion REST est impossible depuis le menu contextuel ou par raccourci clavier.

Types de paginations

MyReport gère plusieurs types de paginations :

Aucune : Le Webservice ne nécessite aucune pagination (toutes les données sont retournées lors d'un seul appel).
Numéro de page: Le Webservice nécessite un paramètre qui définit le numéro de la page demandée. Il est possible de choisir si le premier appel à besoin de ce paramètre.
Nombre d'éléments par page : Le Webservice nécessite de savoir à partir de quel élément il doit retourner des données. L'offset à définir est utilisé pour savoir à partir de quel élément la page doit commencer. A chaque appel, l'offset est augmenté de la valeur choisie. Il est aussi possible de choisir si l'offset doit être utilisé lors du premier appel, et avec quelle valeur.
URL suivante: Le Webservice fournit l'URL à appeler pour la prochaine page.
MyReport doit connaitre la propriété à lire pour récupérer l'URL des pages suivantes.
Attention
Si le nom de la propriété est mal saisi, il n'y aura pas d'erreur, si la propriété n'existe pas dans la réponse, cela signifie simplement que c'était la dernière page de données.
Le chemin d'accès à cette propriété n'est pas dépendant du nœud racine qui peut être sélectionné.
Pagination en Numéro de page :
Le Webservice nécessite un paramètre qui définit le numéro de la page demandée.
- Type de pagination : Numéro de page
- Nom du paramètre de page : paramètre qui définit le numéro de la page demandée
- Nom du paramètre du nombre d'éléments par page :
- Nombre d'éléments par page : la valeur par défaut est fixée à 1
Pagination en Nombre d'éléments par page :
Le Webservice nécessite de savoir à partir de quel élément il doit retourner des données.
- Type de pagination : Nombre d'éléments par page
- Nom du paramètre d'offset : L'offset à définir est utilisé pour savoir à partir de quel élément la page doit commencer
- Nom du paramètre du nombre d'éléments par page : A chaque appel, l'offset est augmenté de la valeur choisie.
- Nombre d'éléments par page : la valeur par défaut est fixée à 1
Pagination en URL Suivante :
Le Webservice fournit l'URL à appeler pour la prochaine page. MyReport doit connaitre la propriété à lire pour récupérer l'URL des pages suivantes.
- Type de pagination : URL Suivante
- Chemin d'URL : propriété à lire pour récupérer l'URL des pages suivantes (p.e. /link)
- Attention
  Si le nom de la propriété est mal saisi, il n'y aura pas d'erreur, si la propriété n'existe pas dans la réponse, cela signifie simplement que c'était la dernière page de données.
  Le chemin d'accès à cette propriété n'est pas dépendant du nœud racine qui peut être sélectionné.

Paramétrage avancé, à travers un Schéma (Fichier .rsd)

Généralités

La ConnexionString ne permet pas un contrôle total sur le WebService, avec, par exemple, l'impossibilité de faire de la pagination.

Pour pallier à ces besoins, CData propose la définition d'un fichier Schéma (.rsd) dans le but de personnaliser et de scripter la manière de requêter le WebService.

Important

Un Schéma est lié à la manière de récupérer complètement les données d'un WebService, et ne gère pas de système de surcharge. Il faut donc un fichier .rsd par table et par modèle modèle.

Note

Dans la suite du chapitre, nous n'utiliserons la ConnexionString dans le seul but de générer le Schéma par défaut, et utiliser des Schémas personnalisé.

Nous n'utilisons pas, les paramètres au niveau de la connexion.

Génération du Schéma par défaut tel que détecté par CData

Dans les propriétés du modèle, il faut configurer la Chaine de connexion comme suit (paramètres minimum requis):

URL=[URL du webService]; Location=[Dossier de génération du RSD]; GenerateSchemaFiles=OnStart

Exemple :
URL=http://localhost/users; Location=C:\myschemas\MesUsers; GenerateSchemaFiles=OnStart

Note

Attention à définir un dossier vide, crée spécifiquement pour le modèle.

A la validation de la fenêtre, un fichier rsd se crée dans le dossier "Location"

Utilisation d'un Schéma préalablement généré

Dans les propriétés du modèle, il faut configurer la Chaine de connexion comme suit (paramètres minimum requis):

Location=[Dossier de génération du RSD]

Exemple :
Location=C:\myschemas\MesUsers

Important

Attention à ne plus avoir le paramètre "GenerateSchemaFiles". Sinon vous risquez perde votre personnalisation du Schéma.

Note

La modification du Schéma après le paramétrage du modèle n'est pas encore bien géré : les champs ne sont pas actualisés.

Comment rafraichir MyReport Data :

Modifier la connexionString en ajoutant un espace en fin par exemple
Si cette manipulation ne suffit pas, il faut redémarrer le service MyReport et retenter la modification de la ConnexionString

Structure d'un Schéma

Important

Il est fortement recommandé de se référer à la documentation CData pour modifier un schéma CData ADO.NET Provider for REST

Attention

Toute valeur possédant des caractères spéciaux ou réservé à une URL (espace, point d'interrogation) doit être encodé au format URL (espace : "%20", point d'interrogation : "%3F")

Lien utile pour l'encodage : w3schools.com

Un Schéma est un fichier XML explicitant la manière de récupérer les données d'une API, et de les transformer.

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

	<api:info title="Users" desc="Mes utilisateurs" xmlns:other="http://apiscript.com/ns?v1">
		<attr name="Id" xs:type="int" other:xPath="/Id"/>
		<attr name="Nom" xs:type="string" other:xPath="/name"/>
		<attr name="Prénom" xs:type="string" other:xPath="/firstname"/>
	</api:info>

	<api:set attr="URI" value="http://localhost/users"/>
	<api:set attr="XPath" value="$."/>
        <api:set attr="method" value="GET"/>
	
	<api:script method="GET">
		<api:call op="jsonproviderGet">
			<api:push/>
		</api:call>
	</api:script>

</api:script>

Explication

<api:info />
Permet de définir comment les valeurs sont récupérées
- <attr name="Id" xs:type="int" other:xPath="/Id" />
  Définit le nom et le type du champ table à créer
  Définit le Path dans le JSON/XML de l'API
<api:set />
Permet de définir les propriétés de connexions et de récupérations
<api:script method="GET">
Permet de définir comment appeler le WebService lorsque MyReport Data fait une requête "SELECT"
<api:call op="jsonproviderGet">
Permet de définir l'appel en lui explicitant le type de données à récupérer (JSon ou XML)
<api:push/>
Permet la transformation des données de "api:call" en "api:info". C'est la récupération des données utiles et structurées.

Astuce

Il est possible de passer la valeur [_connection.URI] dans la partie URI du RSD comme tel : <api:set attr="URI" value="[_connection.URI]"/>, pour directement récupérer la valeur renseignée dans le champ URI de la connexion.

Exemples de Schéma répondant à des problématiques particulières

Exemple basique

Soit un WebService retournant les données suivantes :

{
    "Data": [
        {
            "Id": "0",
            "Id client": "10",
            "Client": "CLIENT 3",
            "CA": "716,29"
        },
        {
            "Id": "1",
            "Id client": "10",
            "Client": "CLIENT 3",
            "CA": "38,27"
        }
    ]
}

Tableau 4.2. Nous voulons récupérer les données sous se format :

Id	Client	CA
0	Client 3	716,29
1	Client 3	38,27

Voici le schéma à utiliser :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  <api:info title="myapi" desc="" xmlns:other="http://apiscript.com/ns?v1">
    <attr name="Id Facture" xs:type="string" other:xPath="/json/Data/Id" />
    <attr name="Client" xs:type="string" other:xPath="/json/Data/Client" />
    <attr name="CA" xs:type="string" other:xPath="/json/Data/CA" />
    <-- ... -->
  </api:info>

  <!-- URL d'accès au webService -->
  <api:set attr="URI" value="https://myapi.com" />

  <!-- Les paramètres sont passés dans l'URL -->
  <api:set attr="method" value="GET"/>

  <!-- Comment sont transformées en données tabulaires -->
  <api:set attr="DataModel" value="DOCUMENT" />

  <!-- Définition du noeud principal des données utiles -->
  <api:set attr="JSONPath" value="$.Data" />
  
  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  <api:script method="GET">

    <!-- Appel du WebService avec le moteur de traitement "JSon" -->
    <api:call op="jsonproviderGet">

      <!-- Récupération des champs utiles -->
      <api:push/>

    </api:call>
  </api:script>

</api:script>

Points clés :

<api:info title="myapi" desc="" xmlns:other="http://apiscript.com/ns?v1"> : La table dans MyReport Data s'appellera "myapi"
<attr name="Id Facture" xs:type="string" other:xPath="/json/Data/Id" />
- name="Id Facture" : Le champ table s'appellera "Id Facture" (alors que l'API le nomme "Id")
- xs:type="string" : CData gère plusieurs type de données, mais il est conseiller de gérer ces types avec MyReport Data. Nous mettons donc toujours "string", pour récupérer la donnée brute.
- other:xPath="/json/Data/Id" : Définition du chemin du champ à partir de la racine du JSon
<api:script method="GET"> : Appel du WebService lors d'un SELECT ("GET" des données)
<api:call op="jsonproviderGet"> : Récupération des données brutes sous forme de JSon (il est possible de récupérer aussi du XML)
<api:push/> Envoi des données à MyReport Data, en fonction des champs définis au début

Important

Il faut bien différencier les 2 éléments suivants :

<api:set attr="method" value="GET"/>
<api:script method="GET">

Le premier définit comment est appelé le WebService. Le deuxième explicite les actions à faire lors d'un "SELECT" ("GET" des données)

Passage de paramètres

Il existe plusieurs possibilités de définir des paramètres d'URL ;

Dans l'URL de connexion (GET)
Dans des tableaux de paramètres
- d'URL (GET)
- d'en-tête (HEAD)
- de Body (POST)

Dans l'URL de connexion (GET) :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- URL d'accès au webService -->
  <api:set attr="URI" value="https://myapi.com?Id=103&amp;verbosity=true" />

  <!-- Les paramètres sont passés dans l'URL -->
  <api:set attr="method" value="GET"/>

  ...

</api:script>

Dans un tableau de paramètres :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- URL d'accès au webService sans paramètre -->
  <api:set attr="URI" value="https://myapi.com" />

  <!-- Définition des paramètres d'URL -->
  <api:set attr="ParamName#" value="Id" />
  <api:set attr="ParamValue#" value="103" />
  <api:set attr="ParamName#" value="verbosity" />
  <api:set attr="ParamValue#" value="true" />

  <!-- Définition des paramètres d'entête -->
  <api:set attr="Header:Name#"  value="Authorization" />
  <api:set attr="Header:Value#" value="Bearer ***" />
  <api:set attr="Header:Name#"  value="DossierConnect" />
  <api:set attr="Header:Value#" value="000000" />

  <!-- Ajout des paramètres POST -->
  <api:set attr="method" value="POST" />
  <api:set attr="Content-Type" value="application/json" />
  <api:set attr="Data">
{ 
  "filter" : "Id",
  "col" : "Id",
  "val" : "1"
}
  </api:set>


  ...

</api:script>

Note

L'attribut Content-Type est très souvent nécessaire par les API's.
Certaines API nécessite d'utiliser le paramètre "ContentType" au lieu de "Content-Type"
Dans des données JSon envoyées en "POST", les crochets doivent être échappées avec le caractère \ (antislash).

Gestion des noms des colonnes dans un tableau séparé des données (type GoogleAnalytics)

Chapitre "JSONFormat"

Soit un WebService retournant les données suivantes :

{
  "columns": [
    {
      "name":"first_name",
      "type":"text"
    },
    {
      "name":"last_name",
      "type":"text"
    }
  ],
  "rows": [
    [
      "John",
      "Doe"
    ],
    [
      "David",
      "Thomas"
    ]
  ]
}

Tableau 4.3. Nous voulons récupérer les données sous se format :

first_name	last_name
John	Doe
David	Thomas

Voici le schéma à utiliser :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <api:info title="MyAPI" desc="" xmlns:other="http://apiscript.com/ns?v1">
    
    <attr name="first_name" xs:type="integer" other:xPath="first_name" />
    <attr name="last_name"  xs:type="string"  other:xPath="last_name"  />

  </api:info>

  <api:set attr="JSONFormat" value="JSONROWS" />
  <api:set attr="URI" value="http://myapi.com" />

  <api:set attr="JSONPath" value="column:/columns;columnname:/columns.name;row:/rows" />

  <api:script method="GET">
    <api:set attr="method" value="GET"/>
    <api:call op="jsonproviderGet">
      <api:push/>
    </api:call>
  </api:script>

</api:script>

Gestion d'un retour de type "Objet d'objets"

Soit un WebService retournant des données sous forme d'objet, et non de tableau

{
    "36172": {
        "i_cli_id": 1037,
        "i_veh_statut": 303,
        "s_veh_makname": "SKODA"
    },
    "36171": {
        "i_cli_id": 1037,
        "i_veh_statut": 303,
        "s_veh_makname": "CUPRA"
    },
    "36170": {
        "i_cli_id": 1030,
        "i_veh_statut": 303,
        "s_veh_makname": "TOYOTA"
    }
}

Tableau 4.4. Nous voulons récupérer les données sous se format :

key	i_cli_id	i_veh_statut	s_veh_makname
36172	1037	303	SKODA
36171	1037	303	CUPRA
36170	1030	303	TOYOTA

Voici le schéma à utiliser :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <api:info title="Vehicules" desc="" xmlns:other="http://apiscript.com/ns?v1">
    <attr name="key"           xs:type="string" other:xPath="/json/%" other:pushelementname="true" />
    <attr name="i_cli_id"      xs:type="string" other:xPath="/json/%/i_cli_id"                     />
    <attr name="i_veh_statut"  xs:type="string" other:xPath="/json/%/i_veh_statut"                 />
    <attr name="s_veh_makname" xs:type="string" other:xPath="/json/%/s_veh_makname"                />
  </api:info>
  
  <api:set attr="DataModel" value="DOCUMENT" />
  <api:set attr="URI" value="https://myapi" />
  <api:set attr="JSONPath" value="$.*" />
  
  <api:script method="GET">
    <api:set attr="method" value="GET" />
    <api:call op="jsonproviderGet">
      <api:push />
    </api:call>
  </api:script>

</api:script>

Points clés :

JSONPath = "$.*" : Il faut boucler à partir de la racine (le signe générique est "*")
<attr name="key" xs:type="string" other:xPath="/json/%" other:pushelementname="true"
- other:xPath="/json/%" : définit sur un élément qui n'a pas de nom (ici le signe générique est "%")
- name="key" : l'élément s'appellera "key"
- other:pushelementname="true" : Force la création du champs même s'il n'est pas nommé

Pagination

Documentation CData

Chapitre "Implement Paging"

Pagination par numéro de page

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  ...
  
  <!-- Activation de la pagination -->
  <api:set attr="EnablePaging" value="TRUE" />
  
  <!-- Définition du paramètre à donner au webService pour le numéro de page -->
  <api:set attr="pagenumberparam" value="page" />
  
  <!-- Définition du paramètre de la taille d'une page (optionnel si le WebService permet de le configurer)
  <api:set attr="pagesizeparam" value="nbItemByPage" />
  
  <!-- Définition de la taille d'une page (A adapter en fonction des possibilités du WebService)
  <api:set attr="pagesize" value="1000" />

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  ...

</api:script>

Pagination par offset

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  ...
  
  <!-- Activation de la pagination -->
  <api:set attr="EnablePaging" value="TRUE" />
  
  <!-- Définition du paramètre à donner au webService pour le numéro de page -->
  <api:set attr="pageoffsetparam" value="offset" />
  
  <!-- Définition du paramètre de la taille d'une page (optionnel si le WebService permet de le configurer)
  <api:set attr="pagesizeparam" value="nbItems" />
  
  <!-- Définition de la taille d'une page (A adapter en fonction des possibilités du WebService)
  <api:set attr="pagesize" value="500" />

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  ...

</api:script>

Pagination par URL

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  ...
  
  <!-- Activation de la pagination -->
  <api:set attr="EnablePaging" value="TRUE" />
  
  <!-- Définition du chemin de récupération de l'URL suivante -->
  <api:set  attr="pageurlpath" value="/link" />

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  ...

</api:script>

Pagination custom

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  <api:info title="Page" desc="" xmlns:other="http://apiscript.com/ns?v1">
    <attr name="# Facture" xs:type="int" other:xPath="/json/Id" />
    <attr name="Client" xs:type="string" other:xPath="/json/Client" />

    <!-- Ajout d'un paramètre input pour la pagination (CData nécessite qu'il s'appelle "rows@next" pour boucler)
    <input name="rows@next" default="" />
  </api:info>

  <!-- définition de l'URL de base commune à chaque page -->
  <api:set attr="urlbase" value="https://myreport-api.net/factures" />

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  <api:set attr="DataModel" value="DOCUMENT" />
  <api:set attr="JSONPath" value="$." />
  <api:set attr="method" value="GET" />
  

  <!-- Activation de la pagination -->
  <api:set attr="EnablePaging" value="true"/>

  <!-- Récupération des résultats utiles à la pagination -->
  <api:set attr="ElementMapPath#" value="/json/vid-offset" />
  <api:set attr="ElementMapName#" value="vidOffset" />

  <api:set attr="ElementMapPath#" value="/json/has-more" />
  <api:set attr="ElementMapName#" value="hasMore" />
  
  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  <api:script method="GET">

    <!-- Définition de l'URL de la page
    <api:set attr="uri" value="[urlbase][_input.rows@next]"/>

    <!-- Appel du WebService avec le moteur de traitement "JSon" -->
    <api:call op="jsonproviderGet" out="result">

      <!-- Calcul de la prochaine page -->
      <api:check attr="result.hasMore">
        <api:if attr="result.hasMore" value="true" operator="equals">
          <api:set attr="result.rows@next" value="?vidOffset=[result.vidOffset]" />
        </api:if>
      </api:check>

      <!-- Récupération des champs utiles -->
      <api:push item="result" />

     </api:call>

  </api:script>

</api:script>

Important

Dans ce mode de pagination, le nom des champs ne doivent pas posséder le caractère "Point" (.)

Gestion des boucles (Under-fetching)

Boucle sur un premier appel

Le but est d'appeler une première API, puis d'appeler une deuxième avec des données du premier appel

Dans cet exemple, nous récupérons les Id de document, puis pour chaque Id, nous appelons une autre API pour récupérer plus d'informations sur le document

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer (idDoc venant du premier appel, les autres du deuxième appel -->
  <api:info title="boucle" desc="" xmlns:other="http://apiscript.com/ns?v1">

    <attr name="idDoc" xs:type="string" other:xPath="/json/documents/document/idDocument" />
    <attr name="idList" xs:type="string" other:xPath="/json/metadatas/metadata/idList" />
    <attr name="idMetadata" xs:type="string" other:xPath="/json/metadatas/metadata/idMetadata" />
    <attr name="multiValue" xs:type="string" other:xPath="/json/metadatas/metadata/multiValue" />
    <attr name="name" xs:type="string" other:xPath="/json/metadatas/metadata/name" />
    <attr name="type" xs:type="string" other:xPath="/json/metadatas/metadata/type" />
    <attr name="value" xs:type="string" other:xPath="/json/metadatas/metadata/value" />

  </api:info>

  <!-- Paramétrage du premier appel (stocké dans la variable callOne) -->
  <api:set attr="callOne.DataModel" value="DOCUMENT"/>
  <api:set attr="callOne.URI" value="https://myapi/search" />
  <api:set attr="callOne.JSONPath" value="$.documents"/>
  <api:set attr="callOne.method" value="GET"/>
  <api:set attr="callOne.enablePaging" value="TRUE" />

  <!-- Définition de la valeur à récupérer (Path JSon de idDocument) -->
  <api:set attr="callOne.ElementMapPath#" value="/json/documents/document/idDocument"/>
  <api:set attr="callOne.ElementMapName#" value="Doc_Id"/>

   <!-- Paramétrage du deuxième appel (stocké dans la variable callTwo) -->
  <api:set attr="callTwo.DataModel" value="DOCUMENT"/>
  <api:set attr="callTwo.JSONPath" value="$.metadatas"/>
  <api:set attr="callTwo.method" value="GET"/>
  <api:set attr="callTwo.enablePaging" value="TRUE" />

  <!-- Définition d'un Template d'URL avec un élement {Doc_Id} à remplacer par chaque valeurs du premier appel -->
  <api:set attr="callTwo.URITemplate" value="https://myapi/document/{Doc_Id}"/>

  <api:script method="GET">

    <!-- Premier appel de l'API avec stockage du résultat dans callOneOut -->
    <api:call op="jsonproviderGet" in="callOne" out="callOneOut">

      <!-- Récupération des valeurs "idDoc" -->
      <api:set attr="callTwo.Doc_Id" value="[callOneOut.idDoc]"/>

      <!-- Calcul de la bonne URL pour chaque valeurs -->
      <api:set attr="callTwo.URI" value="[callTwo.URITemplate | replace('{Doc_Id}', [callTwo.Doc_Id])]"/>

      <!-- Deuxième appel de l'API avec stockage du résultat dans callTwoOut -->
      <api:call op="jsonproviderGet" in="callTwo" out="callTwoOut">

        <!-- Définition du résultat final basé sur l'appel 1 -->
        <api:set attr="out.idDoc" value="[callOneOut.idDoc | allownull()]"/>

        <!-- Définition du résultat final basé sur l'appel 2 -->
        <api:set attr="out.idList" value="[callTwoOut.idList | allownull()]"/>
        <api:set attr="out.idMetadata" value="[callTwoOut.idMetadata | allownull()]"/>
        <api:set attr="out.multiValue" value="[callTwoOut.multiValue | allownull()]"/>
        <api:set attr="out.name" value="[callTwoOut.name | allownull()]"/>
        <api:set attr="out.type" value="[callTwoOut.type | allownull()]"/>
        <api:set attr="out.value" value="[callTwoOut.value | allownull()]"/>

        <!-- Récupération des champs utiles -->
        <api:push item="out"/>

      </api:call>

    </api:call>

  </api:script>

</api:script>

Boucle sur une liste de valeurs fixée

On souhaite appeler les URL suivantes :

https://myapi.com/factures?idClient=CLIENT_3
https://myapi.com/factures?idClient=CLIENT_4

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  <api:info title="PageFixe" desc="" xmlns:other="http://apiscript.com/ns?v1">

    <attr name="# Facture" xs:type="int"    other:xPath="/json/Id"     />
    <attr name="Client"    xs:type="string" other:xPath="/json/Client" />
    <attr name="CA"        xs:type="string" other:xPath="/json/CA"     />

  </api:info>

  <!-- définition de l'URL de base commune à chaque page -->
  <api:set attr="URI" value="https://myapi.com/factures" />

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  <api:set attr="method"       value="GET"      />
  <api:set attr="DataModel"    value="DOCUMENT" />
  <api:set attr="JSONPath"     value="$."       />

  <!-- Activation de la pagination -->
  <api:set attr="EnablePaging" value="true"     />

  <!-- Définition de la liste des valeurs "CLIENT_3, CLIENT_4" -->
  <api:set attr="clients#1" value="CLIENT_3" />
  <api:set attr="clients#2" value="CLIENT_4" />

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  <api:script method="GET">

    <!-- Boucle sur la liste de valeurs -->
    <api:enum attr="clients" expand="true">

      <!-- Ajout de la valeur récupérée en paramètre d'URL -->
      <api:set attr="ParamName#"  value="idClient" />
      <api:set attr="ParamValue#" value="[_value]" />

      <!-- Appel du WebService avec le moteur de traitement "JSon" -->
      <api:call op="jsonproviderGet">

        <!-- Récupération des champs utiles -->
        <api:push/>

      </api:call>

    </api:enum>

  </api:script>

</api:script>

Authentification

Généralités

Les fonctions d'authentifications sont disponibles au niveau de la ConnexionString, mais aussi depuis le Schéma.

Note

Lors de la génération du schéma avec une connexionString possédant l'authentification, le schéma ne possède pas les informations d'authentification

Login / Mot de passe

Configuration

connexionString : URL=http://localhost/users; AuthScheme=BASIC; User=MonLogin; Password=MonMotDePasse

Schéma :

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  ...

  <!-- Paramétrage de la connexion (URL, DataModel, ...)  -->
  ...
  
  <!-- Activation de la pagination -->
  <api:set attr="User" value="MonLogin"/>
  <api:set attr="Password" value="MonMotDePasse"/>
  <api:set attr="AuthScheme" value="BASIC"/>

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  ...

</api:script>

OAuth2.0 - Credential

Configuration

connexionString : OAuthParams="scope=basic email"; AuthScheme=OAuth; OAuthVersion=2.0; OAuthClientId=***; OAuthClientSecret=***; OAuthRefreshTokenURL=http://localhost/access_token; OAuthAccessTokenURL=http://localhost/Oauth/access_token; CallbackURL=http://localhost:8000/callback; OAuthGrantType=CLIENT

Schéma : L'authentification passe par plusieurs appels. La définition des paramètres se fait par appel

<api:script xmlns:api="http://apiscript.com/ns?v1" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <!-- Définition des champs à récupérer -->
  <api:info title="OAuthCredential" desc="" xmlns:other="http://apiscript.com/ns?v1">
    <attr name="Id" xs:type="int" other:xPath="/json/id"/>
    <attr name="name" xs:type="string" other:xPath="/json/name"/>
    <attr name="email" xs:type="string" other:xPath="/json/email"/>
  </api:info>

  <!-- Paramétrage de la connexion aux données (URL, DataModel, ...)  -->
  <!-- Les attributs sont préfixé par un nom (ici "myapi.") pour les utiliser dans le bon appel
  <api:set attr="myapi.URI" value="https://localhost/users"/>
  <api:set attr="myapi.DataModel" value="DOCUMENT"/>
  <api:set attr="myapi.JSONPath" value="$."/>
  <api:set attr="myapi.method" value="GET"/>

  <!-- Paramétrage de la connexion OAuth2.0  -->
  <api:set attr="auth.AuthScheme" value="OAuth"/>
  <api:set attr="auth.OAuthVersion" value="2.0"/>
  <api:set attr="auth.GrantType" value="CLIENT"/>
  <api:set attr="auth.OAuthRefreshTokenURL" value="https://localhost/access_token"/>
  <api:set attr="auth.OAuthAccessTokenURL" value="https://localhost/access_token"/>
  <api:set attr="auth.OAuthAuthorizationURL" value="https://localhost/authorize"/>
  <api:set attr="auth.CallbackURL" value="http://localhost:8000/callback"/>
  <api:set attr="auth.OAuthClientId" value="***"/>
  <api:set attr="auth.OAuthClientSecret" value="***"/>
  <api:set attr="auth.OAuthParam:scope" value="***" />

  <!-- Définition de l'appel du WebService lorsque Data fait un SELECT (GET des données) -->
  <api:script method="GET">

    <!-- Appel de l'authentification avec le parametrage "auth" -->
    <api:call op="oauthGetAccessToken" in="auth">

      <!-- Injection du token dans les paramètre "myapi" (ajout du Header "Authorization= Bearer MyAcceToken") -->
      <!-- [_out1.OAuthAccessToken] se traduit comme suit : "_out1" -> Résultat du premier appel  "OAuthAccessToken" -> chemin JSon de l'accessToken dans le retour -->
      <api:set attr="myapi.Header:Name#" value="Authorization"/>
      <api:set attr="myapi.Header:Value#" value="Bearer [_out1.OAuthAccessToken]"/>

    </api:call>

    <!-- Appel du WebService avec le moteur de traitement "JSon" et le parametrage "myapi"  -->
    <api:call op="jsonproviderGet" in="myapi">
      <api:push/>
    </api:call>

  </api:script>

</api:script>

OAuth Code

Précédent	Niveau supérieur	Suivant
	Sommaire

Les modèles WebServicesChapitre 4. Les connexions REST API