Français
Conventions
Variables
Nous utilisons une convention de nommage personnalisée basée sur le type des variables.
Chaque nom de variable est composé d'un maximum de 6 composantes :
- Tableau (Optionnel) a_ lorsqu'il s'agit d'un tableau (array).
- Clé (Optionnel) pk lorsqu'il s'agit d'une clé primaire (primary key), fk pour une clé étrangère (foreign key), dfk pour une clé sur un discriminant ou efk pour une clé étrangère vers un système externe.
- Type Toujours en minuscules et représente le type de la variable.
- Table La première lettre en majuscule et le reste en minuscules. Représente le nom de la table d'où provient la variable.
- Champ (Optionnel) La première lettre est en majuscule et le reste en minuscules. Représente le nom du champ. Exception : si le nom du champ est « ID », il sera conservé en majuscules afin d'indiquer qu'il s'agit d'un identifiant unique.
- Discriminateur (Optionnel) Présent uniquement lorsque deux champs identiques sont stockés dans la même table afin de les différencier l'un de l'autre.
Voici un tableau récapitulatif expliquant la convention.
| Tableau | Clé | Type | Table | Champ | Discriminateur | |
|---|---|---|---|---|---|---|
| Optionnel | Oui | Oui | Non | Non | Oui | Oui |
| Nommage | Fixe | Fixe | Minuscules | Première lettre en majuscule et le reste en minuscules | Première lettre en majuscule et le reste en minuscules, sauf pour le champ ID qui est toujours en majuscules | Première lettre en majuscule et le reste en minuscules |
| Valeurs | a_ | pk fk dfk efk | s (string) t (text) c (char) sha (sha-1 string) md5 (md5 string) bin (binary string) i (integer) f (float) d (decimal) e (enum) dt (date or datetime) b (boolean) obj (object) m (mixed) | Toute valeur | Toute valeur | Toute valeur |
Voici des exemples de noms de variables typiques.
| Nom de variable | Tableau | Clé | Type | Table | Champ | Discriminateur | Explication | Exemple |
|---|---|---|---|---|---|---|---|---|
| pkiContactID | pk | i | Contact | ID | Clé primaire de type entier pour le champ ID dans la table Contact | 133 | ||
| fkiContactID | fk | i | Contact | ID | Clé étrangère de type entier pointant vers le champ pkiContactID dans la table Contact | 133 | ||
| efkiContactID | efk | i | Contact | ID | Clé étrangère externe de type entier pointant vers le champ pkiContactID dans la table Contact | 133 | ||
| fkiContactIDOwner | fk | i | Contact | ID | Owner | Clé étrangère de type entier pointant vers le champ pkiContactID dans la table Contact avec un discriminateur Owner | 266 | |
| sContactFirstname | s | Contact | Firstname | Chaîne de caractères pour le champ Firstname dans la table Contact | John | |||
| bPurchaseIspaid | b | Purchase | Ispaid | Valeur booléenne pour le champ Ispaid dans la table Purchase | Vrai | |||
| dPurchaseTotal | d | Purchase | Total | Nombre décimal pour le champ Total dans la table Purchase | 2199.78 | |||
| objEzsignfolder | obj | Esignfolder | Objet de type Ezsignfolder | {"pkiEzsignfolderID": 122, "sEzsignfolderName": "Test"} | ||||
| a_objEzsignfolder | a_ | obj | Ezsignfolder | Tableau d'objets de type Ezsignfolder | [{"pkiEzsignfolderID": 122, "sEzsignfolderName": "Test"}, {"pkiEzsignfolderID": 234, "sEzsignfolderName": "Test 2"}] | |||
| a_sContactFirstname | a_ | s | Contact | Firstname | Tableau de chaînes de caractères pour le champ Firstname dans la table Contact | ['John', 'Mary', 'Jane'] | ||
| a_fkiContactIDOwner | a_ | fk | i | Contact | ID | Owner | Tableau de clés étrangères de type entier pointant vers le champ pkiContactID dans la table Contact avec un discriminateur Owner | [266, 277, 288] |
Filtre de liste
Chaque point de terminaison GetList possède un paramètre de requête sFilter qui peut être utilisé pour filtrer les éléments retournés.
La syntaxe du paramètre sFilter n'est pas documentée au niveau de chaque point de terminaison, car cela serait redondant. Cette section décrit la syntaxe.
- Chaque propriété retournée par le point de terminaison peut être utilisée pour construire la chaîne sFilter, à l'exception de rares exceptions.
- Chaque filtre peut être combiné à l'aide de l'opérateur and.
- Toutes les propriétés ne prennent pas en charge tous les opérateurs. La liste des opérateurs valides dépend du type de variable. Par exemple, seuls les types chaîne de caractères prennent en charge l'opérateur like. Vous pouvez consulter l'article Variables dans la section Conventions de la documentation pour connaître les types de variables et leur représentation dans les noms de variables.
- Les variables de type Enum possèdent une liste prédéfinie de filtres qui sera documentée au niveau du point de terminaison.
- La valeur de sFilter doit être encodée dans l'URL.
- Les valeurs de type chaîne de caractères doivent être entourées d'apostrophes simples.
Opérateurs valides pour les valeurs booléennes :
| Opérateur | Description | Exemples |
|---|---|---|
| eq | Égal à | bEzsigndocumentEzsignclause eq true bEzsigndocumentEzsignclause eq false |
Opérateurs valides pour les valeurs entières :
| Opérateur | Description | Exemples |
|---|---|---|
| eq | Égal à | iEzsigndocumentPagetotal eq 10 |
| gt | Supérieur à | iEzsigndocumentPagetotal gt 10 |
| gte | Supérieur ou égal à | iEzsigndocumentPagetotal gte 10 |
| lt | Inférieur à | iEzsigndocumentPagetotal lt 100 |
| lte | Inférieur ou égal à | iEzsigndocumentPagetotal lte 100 |
| in | Dans la liste | fkiEzsignfoldertypeID in '1,2,3' |
Opérateurs valides pour les valeurs de type date et date-heure :
| Opérateur | Description | Exemples |
|---|---|---|
| eq | Égal à | dtEzsigndocumentDuedate eq '2005-07-01 18:15:59' dtEzsigndocumentDuedate eq '2005-07-01' |
| gt | Supérieur à | dtEzsigndocumentDuedate gt '2001-01-01 00:00:00' dtEzsigndocumentDuedate gt '2001-01-01' |
| gte | Supérieur ou égal à | dtEzsigndocumentDuedate gte '2001-01-01 00:00:00' dtEzsigndocumentDuedate gte '2001-01-01' |
| lt | Inférieur à | dtEzsigndocumentDuedate lt '2025-12-31 23:59:59' dtEzsigndocumentDuedate lt '2025-12-31' |
| lte | Inférieur ou égal à | dtEzsigndocumentDuedate lte '2025-12-31 23:59:59' dtEzsigndocumentDuedate lte '2025-12-31' |
| rg | Dans la liste voir la documentation sur l'opérateur de plage | dtEzsigndocumentDuedate rg '=m,=m+7d' |
Opérateurs valides pour les valeurs de type chaîne de caractères :
| Opérateur | Description | Exemples |
|---|---|---|
| eq | Égal à | sEzsigndocumentName eq 'Test contract' |
| like | Rechercher une chaîne de caractères partielle à l'aide du caractère générique % | sEzsigndocumentName like 'Test contra%' sEzsigndocumentName like '%contract' sEzsigndocumentName like '%con%' |
Opérateurs valides pour les valeurs de type enum (les valeurs valides sont documentées au niveau du point de terminaison) :
| Opérateur | Description | Exemples |
|---|---|---|
| eq | Égal à | eEzsigndocumentStep eq 'PartiallySigned' |
| in | Dans la liste | eEzsigndocumentStep in 'PartiallySigned,Archived' |
Exemple de combinaison de plusieurs filtres :
text
Filter=bEzsigndocumentEzsignclause eq true and iEzsigndocumentPagetotal gt 10 and iEzsigndocumentPagetotal lte 100 and dtEzsigndocumentDuedate gt '2001-01-01 00:00:00' and dtEzsigndocumentDuedate lte '2025-12-31 23:59:59' and sEzsigndocumentName like '%con%' and eEzsigndocumentStep eq 'PartiallySigned' and fkiEzsignfoldertypeID in '1,2,3' and dtEzsigndocumentDuedate rg '=m,=m+7d'`1
Même exemple, mais correctement encodé pour une URL :
text
Filter=bEzsigndocumentEzsignclause%20eq%20true%20and%20iEzsigndocumentPagetotal%20gt%2010%20and%20iEzsigndocumentPagetotal%20lte%20100%20and%20dtEzsigndocumentDuedate%20gt%20%272001-01-01%2000%3A00%3A00%27%20and%20dtEzsigndocumentDuedate%20lte%20%272025-12-31%2023%3A59%3A59%27%20and%20sEzsigndocumentName%20%20like%20%27%25con%25%27%20and%20eEzsigndocumentStep%20eq%20%27PartiallySigned%27%20and%20fkiEzsignfoldertypeID%20in%20%271%2C2%2C3%27%20and%20dtEzsigndocumentDuedate%20rg%20%27%3Dm%2C%3Dm%2B7d%27`1
Opérateur de plage
Les dates utilisées dans les filtres de liste peuvent utiliser l'opérateur rg pour définir des plages. Cela permet de filtrer les données en fonction de dates relatives. L'opérateur de plage constitue simplement une autre façon de calculer les dates utilisées dans les filtres.
Pour le reste de cette section, supposons que la date d'aujourd'hui est le 25 février 2019 et que l'heure est 10 h 15 min 37 s. Supposons que nous souhaitons filtrer le champ dtInvoiceDate.
Si nous voulions obtenir toutes les factures qui ont été générées au cours du mois précédent, nous pourrions utiliser (non encodé pour faciliter la lecture) : sFilter=dtInvoiceDate gte '2019-01-01 00:00:00' and dtInvoiceDate lte '2019-01-31 23:59:59'
L'opérateur de plage permet de transférer la complexité du calcul des dates à l'API plutôt que de la gérer dans l'application appelante.
Le format général de l'opérateur de plage est le suivant : dtInvoiceDate rg '[STARTDATE],[ENDDATE]'
Les [STARTDATE] et [ENDDATE] utilisent le même format, soit une séquence d'une ou plusieurs [SUBSECTION]. Par exemple, nous pourrions avoir : dtInvoiceDate rg '[SUBSECTION],[SUBSECTION][SUBSECTION][SUBSECTION][SUBSECTION]'
Les [STARTDATE] et [ENDDATE] ont tous deux une heure de début correspondant à l'heure actuelle (donc, dans cet exemple, 2019-02-25 10:15:37).
Une [SUBSECTION] commence par un opérateur qui peut être = pour réinitialiser le pointeur, + pour avancer dans le temps ou - pour reculer dans le temps.
L'opérateur = peut être suivi directement d'une lettre représentant la [PERIOD] (p. ex. =m) pour initialiser la date au début ou à la fin de la période, ou d'un nombre et d'une lettre représentant la [PERIOD] (p. ex. =7m) pour définir la [PERIOD] sur une valeur précise.
Les opérateurs + et - sont suivis d'un nombre, puis d'une lettre représentant la [PERIOD] (p. ex. +7d ou -1m).
Voici une liste des [PERIOD] valides :
| [PERIOD] | Description |
|---|---|
| y | année (year) |
| m | mois (month) |
| w | semaine (week) |
| d | jour (day) |
| h | heure (hour) |
| i | minute (minute) |
| s | seconde (second) |
L'opérateur = sans nombre réinitialise le pointeur au début ou à la fin de la [PERIOD], selon qu'il est utilisé dans [STARTDATE] ou [ENDDATE]. Le tableau suivant indique à quel moment le pointeur est réinitialisé.
| Syntaxe | Description | [STARTDATE] | [ENDDATE] |
|---|---|---|---|
| =y | année (year) | 2019-01-01 00:00:00 | 2019-12-31 23:59:59 |
| =m | mois (month) | 2019-02-01 00:00:00 | 2019-02-28 23:59:59 |
| =w | semaine (week) | 2019-02-24 00:00:00 | 2019-03-02 23:59:59 |
| =d | jour (day) | 2019-02-25 00:00:00 | 2019-02-25 23:59:59 |
| =h | heure (hour) | 2019-02-25 10:00:00 | 2019-02-25 10:59:59 |
| =i | minute (minute) | 2019-02-25 10:15:00 | 2019-02-25 10:15:59 |
| =s | seconde (second) | 2019-02-25 10:15:37 | 2019-02-25 10:15:37 |
INFO
Le jour de début de la semaine est configurable pour chaque utilisateur.
L'opérateur = suivi d'un nombre réinitialise la [PERIOD] à une valeur précise et fonctionne de la même façon pour [STARTDATE] et [ENDDATE]. Voici quelques exemples. Veuillez noter qu'il n'est pas possible de réinitialiser la semaine de cette façon (p. ex. =7w).
| Syntaxe | Description | Nouvelle date |
|---|---|---|
| =2025y | année (year) | 2025-02-25 10:15:37 |
| =11m | mois (month) | 2019-11-25 10:15:37 |
| =7d | jour (day) | 2019-02-07 10:15:37 |
| =17h | heure (hour) | 2019-02-25 17:15:37 |
| =1i | minute (minute) | 2019-02-25 10:01:37 |
| =18s | seconde (second) | 2019-02-25 10:15:18 |
Combinaison de [SUBSECTION]
Vous pouvez combiner plusieurs [SUBSECTION] sous le même opérateur. Par exemple :
- Au lieu d'utiliser =m=7d=8h=6m=32s, vous pouvez simplifier l'expression en =m7d8h6m32s.
- Au lieu d'utiliser +7d+7h+7m+7s, vous pouvez simplifier l'expression en +7d7h7m7s.
- Au lieu d'utiliser =3m=m, vous pouvez simplifier l'expression en =3mm.
Ordre de priorité
[STARTDATE] et [ENDDATE] sont évalués de gauche à droite. L'ordre est important. Par exemple, les valeurs suivantes donneraient des résultats différents dans [ENDDATE] :
- =m-1m donnerait 2019-01-28 23:59:59
- -1m=m donnerait 2019-01-31 23:59:59
Exemples d'utilisation
| Syntaxe | Explication | Date de début | Date de fin |
|---|---|---|---|
| sFilter=dtInvoice rg '-7d,=s' | Factures des 7 derniers jours jusqu'à maintenant | 2019-02-18 10:15:37 | 2019-02-25 10:15:37 |
| sFilter=dtInvoice rg '=d-7d,=s' | Factures des 7 derniers jours à partir de 00:00:00 jusqu'à maintenant | 2019-02-18 00:00:00 | 2019-02-25 10:15:37 |
| sFilter=dtInvoice rg '=m-1m,=m-1m' | Factures du dernier mois | 2019-01-01 00:00:00 | 2019-01-31 23:59:59 |
| sFilter=dtInvoice rg '=m,=m' | Factures de ce mois-ci | 2019-02-01 00:00:00 | 2019-02-28 23:59:59 |
| sFilter=dtInvoice rg '=m-1m+10d,=s' | Factures depuis le 10 du mois dernier jusqu'à maintenant | 2019-01-10 00:00:00 | 2019-02-25 10:15:37 |
| sFilter=dtInvoice rg '-10h,=d8h+1d1s' | Factures des 10 dernières heures jusqu'à 9h00 demain matin | 2019-02-25 00:15:37 | 2019-02-26 09:00:00 |
| sFilter=dtInvoice rg '-1y=4mm,=3mm' | Factures du deuxième semestre de l'année dernière jusqu'au premier trimestre de cette année | 2018-04-01 00:00:00 | 2019-03-31 23:59:59 |
| sFilter=dtInvoice rg '=w-3w,=w' | Factures des 3 dernières semaines (le jour de début de la semaine civile est le dimanche) jusqu'à la fin de la semaine | 2019-02-03 00:00:00 | 2019-03-02 23:59:59 |
| sFilter=dtInvoice rg '=y,=3mm' | Factures du premier semestre | 2019-01-01 00:00:00 | 2019-03-31 23:59:59 |
| sFilter=dtInvoice rg '=4mm,=6mm' | Factures du deuxième semestre | 2019-04-01 00:00:00 | 2019-06-30 23:59:59 |
| sFilter=dtInvoice rg '=7mm,=9mm' | Factures du troisième semestre | 2019-07-01 00:00:00 | 2019-09-30 23:59:59 |
| sFilter=dtInvoice rg '=10mm,=y' | Factures du dernier semestre | 2019-10-01 00:00:00 | 2019-12-31 23:59:59 |