Ressource (sdata)

Version du 28 janvier 2021 à 15:42

Ressource (GET)

Dans l'interface SData les ressources sont les objets de l'application.

Une ressource est identifié par son uri qui représente le chemin de la ressource.

L'uri est composé du chemin de la classe et d'un sélecteur qui est l'oid de l'objet.

Exemple :

GET http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000000285DAE')
Response: 200 OK
{
   "$baseUrl":"http://localhost:8080/sdata/l1000/gentiers/-/",
   "$title":"TTiers - -",
   "$updated":"2020-12-22T08:10:09.740Z",
   "$resources":[
      {
         "$url":"TTiers('9D33A23CFA6A005500F6000000285DAE')",
         "$title":"ABI Jardin",
         "$updated":"2010-03-23T15:37:46.000Z",
         "$etag":"9D33A23CFA6A005500F6000000285DAE-000002C60000421C",
         "$key":"9D33A23CFA6A005500F6000000285DAE",
         "$baseUrl":"http://localhost:8080/sdata/l1000/GenTiers/-/",
         "stamp":"000002C60000421C",
         .... Attribute list ...
      }
   ]
}

Sélecteur de ressource

Un sélecteur permet de retrouver une ressource spécifique, il est possible de rechercher une ressource par clé ou clause

Code de retour HTTP

Gestion des rôles

La gestion des rôles de la ressource dépend du type de rôle :

• Pour un rôle composition la ressource "composant" est retournée par valeur dans le corps de la ressource "composée"
• Pour un rôle qui n'est pas une composition la ressource "composant" est retournée par référence dans le corps de la ressource "composée"

Gestion du périmètre société

Par défaut, les requêtes s'exécutent dans le contexte société défini dans le jeton d'authentification.

Vous pouvez définir le contexte société dans le l'url de la requête :

  METHOD https://host/sdata/society/package/class ...

Requête sur les ressources (GET)

Une requête sur les ressources est une requête sur une classe du modèle.

GET http://localhost:8080/sdata/gentiers/ttiers?parameters

Paramètres de la requête

Les valeurs passées en paramètre doivent être encodées en HTML

Exemple :

where=code eq 'ABI 007'

doit être encodée en :

where=code%20eq%20%27ABI%20007%27

Select

Select permet de définir les attributs a retourner, par défaut tous les attributs non vide sont retournés

GET http://localhost:8080/sdata/gentiers/ttiers?select=code,caption

La présence du paramètre select conditionne la façon d'exécuter la requête.

Les formats possibles sont :

Une vue sera utilisée si au moins un des membres de select nécessite l'utilisation d'une vue.

Notez :

• La sélection d'attribut référencé non défini peut générer l'absence de ressources dans le résultat, pour éviter ceci utilisez un spécificateur de jointure externe.
• La sélection d'attribut référencé par un rôle liste peut générer plusieurs ressources dans le résultat correspondant à chaque ressource liée par la relation.
• Lorsqu'une vue est utilisée, les filtres et ordre de tri sont exprimés par rapport à la vue.

Par exemple :

• TCompteGeneral?select=codeCompte&where=codeCompte ge '4'&orderBy=codeCompte

mais

• TCompteGeneral?select=code as codeCompte&where=code ge '4'&orderBy=code

Filtre

Opérateurs:

Valeurs des paramètres:

Les valeurs des paramètres sont passées en littérale

Ordre de tri

Tri ascendant :

orderby=code

Tri descendant :

orderby=code%20desc

GET http://localhost:8080/sdata/gentiers/ttiers?orderBy=code%20desc

Pagination par page

Utiliser orderBy, count et startIndex

GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=0
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=10
GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startIndex=20
  ...

Tip : Incrémentez startIndex du nombre de ressource retourné par la requête

Pagination par clé

Utiliser orderBy, startKey et keyDirection

GET http://localhost:8080/sdata/gentiers/ttiers?select=code&orderby=code&count=10&startKey=1B28EFFFF1C3000200F6000000230893&keyDirection=lt

Création de ressource (POST)

POST http://localhost:8080/sdata/gentiers/ttiers
Request:
{
   "code":"SYFRE1",
   "caption":"syfre 1",
   "sitesList":[
      {
         "code":"SITE1",
         "caption":"site1 de syfre1",
         "adresse":{
            "nomRueVoie":"rue de la pompe",
            "ville":"Clichy",
            "codePostal":"92100",
            "pays":{
               "$key":"9D33A23CFA6A005500150000001700FD"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E20022",
            "$url": "http://localhost:8080/sdata/l1000/gentiers/-/TTiers('9D33A23CFA6A005500F6000001E20022')",
            ... attribute list ...
        } 
     ]
}

Gestion du périmètre de partage

Le niveau de partage d'une ressource de niveau activité peut être contrôlé par des propriétés de contrôle au niveau de la définition de la ressource :

POST https://localhost/sdata/S3/gentiers/ttiers
Request:
{
   "$shareLevel":2,
   "code":"SYFRES3-2",
   "caption":"syfre S3-2",
   "sitesList":[
      {
         "code":"SITE1",
         "caption":"site 1",
         "adresse":{
            "nomRueVoie":"rue de la pompe",
            "ville":"Clichy",
            "codePostal":"92100",
            "pays":{
               "$key":"9D33A23CFA6A005500150000001700FD"
            }
         }
      }
   ]
}
Response : 201 OK

Tip : Par défaut la ressource sera créée au niveau activité

Gestion des rôles

La création de ressource dans les rôles dépend de la nature du rôle.

• Pour les rôles de type composition les ressources liées sont créés simultanément.
• Pour les rôles qui ne sont pas des compositions les ressources liées sont rattachés.

Identification des références

Par clé:

{
  "pays":{
    "$key":"9D33A23CFA6A005500150000001700FD"
  }
}

Par uri:

{
  "pays":{
    "$url":TPays("9D33A23CFA6A005500150000001700FD")
  }
}

Par expression:

{
  "pays":{
    "$where":"codeISO = 'FRA'",
    "$orderby":"codeISO"
  }
}

Lorsqu'une expression est utilisée la première ressource retournée par l'expression est utilisée.

Modification de ressource (PUT)

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request:
{
"codeSIRET":"12345678"
}
Response: 200 OK
[
{ 
.... resource modified ...
}
]

Modification de rôle liste composition

Par défaut les rôles composition sont gérés en remplacement, pour contrôler le mode de gestion des rôles utilisez un élément de contrôle "$" pour le rôle :

Exemple : Modification du rôle par remplacement des composants :

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "sitesList":[
      {
         "code":"SITE3",
         "caption":"site3 de syfre1",
         "adresse":{
            "nomRueVoie":"rue Mogador",
            "ville":"Paris",
            "codePostal":"75008",
            "pays":{
               "$where":"codeISO = 'FRA'",
               "$orderby":"codeISO"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E30019",
            "$url": "/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E30019')",
            "stamp": "000001710000002A",
            ....
            "sitesList": [
            ... Site3 has been added, other sites has been removed.
            ... There is one site left in the list
           ]
    ]
}

Exemple : Modification du rôle par ajout de composant :

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "$":{
     "sitesList:["create"]
   },
   "sitesList":[
      {
         "code":"SITE3",
         "caption":"site3 de syfre1",
         "adresse":{
            "nomRueVoie":"rue Mogador",
            "ville":"Paris",
            "codePostal":"75008",
            "pays":{
               "$where":"codeISO = 'FRA'",
               "$orderby":"codeISO"
            }
         }
      }
   ]
}
Response: 200 OK
{
    "$resources": [
        {
            "$key": "9D33A23CFA6A005500F6000001E30019",
            "$url": "/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E30019')",
            "stamp": "000001710000002A",
            ....
            "sitesList": [
                ... Site3 has been added, other sites are not affected
                ... There is one site more in the list
            }
           ]
    ]
}

Exemple : Modification du rôle par mise à jour de composant :

PUT http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Request :
{
   "$":{
     "sitesList:["update"]
   },
   "sitesList":[
      {
         "$key":"9D33A23CFA6A005500F6000001E30019", 
         "caption":"Site maj",
      }
   ]
}

La valeur par défaut est "create","update","delete"

Modification des attributs privés

Par défaut les attributs privés sont modifiés sur le niveau de partage correspondant au périmètre société, pour contrôler le niveau de partage des attributs privés utilisez un élément de contrôle $sharePrivateLevel.

Tip : Le périmètre courant de l'objet dépend de l'état de l'objet. Par exemple, si l'objet est de niveau activité et n'a pas de propriété défini pour la société courante, le périmètre courant sera l'activité, mais si l'objet a des propriétés définies pour la société courante alors le périmètre courant sera la société. Ne pas définir explicitement le niveau de partage peut amener à des ambiguïtés.

Modification de la valeur de l'attribut privé pour les sociétés de l'activité du Tiers (le tiers n'a pas de propriété défini pour la société S3):

PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
{
"modeReglementDecaissement":{"$where":"code eq 'CHQ'"},
}

Modification de la valeur de l'attribut privé pour la société S3 :

PUT http://localhost:8080/sdata/S3/gentiers/ttiers(code eq 'ABI 00007')
{
"$sharePrivateLevel":2,
"modeReglementDecaissement":{"$where":"code eq 'CBB'"},
}

Suppression de ressource (DELETE)

DELETE http://localhost:8080/sdata/gentiers/ttiers('9D33A23CFA6A005500F6000001E20018')
Response: 200 OK

Opération sur une ressource (POST)

Les opérations des ressources correspondent aux méthodes publiques de cette ressource.

Méthode d'instance de ressource

POST http://localhost:8080/sdata/testsyfrewf/wfclassea('B5A28A92EB0C00020010000000DB0006')/testmethode
Request:
{
"pString":"value1",
"pInteger":1,
"pFloat":1.2,
"pEnum":1,
"pBoolean":false
}

Response: 200 OK
{
    "result": "pString:value1 pInteger:1 pBoolean:false pFloat:1,2 pEnum:1"
}

Méthode de classe de ressource, ou méthode de classe non persistante

POST http://localhost:8080/sdata/testsyfrewf/myProcessus/testmethode
Request:
{
"pString":"value1",
"pInteger":1,
"pFloat":1.2,
"pEnum":1,
"pBoolean":false
}

Response: 200 OK
{
    "result": "pString:value1 pInteger:1 pBoolean:false pFloat:1,2 pEnum:1"
}

Les paramètres sont passés par nom et valeur.

Les types de paramètres et de retour supportés sont :

Initialisation de la ressource

Il est possible d'initialiser la ressource avant d'exécuter la méthode, par exemple pour un processus :

Type
  TmyProcessus = class
  public
   procedure Execute(p:string);
   property attString:string;
   property attInt:Integer;
   property attRef:TRefClass;
  end;

POST http://localhost:8080/sdata/testsyfrewf/myProcessus/execute
Request:
{
"$resource":{
 "attString":"value 1",
 "attInt":100,
 "attRef":{"$url":"TRefClass('xxx')"},
},
"p":"value",
}
Response: 200 OK
{
    "result":""
}

Requête Batch (POST $batch)

Une requête Batch permet de réaliser plusieurs opérations de type POST/PUT/DELETE/EXEC en une seule fois.

Une requête Batch contient un tableau de ressources, pour chaque ressource l'action et l'uri doivent être précisées :

POST http://.../sdata/$batch
{
   "$resources":[
      {
         "$httpMethod":"POST",
         "$url":"gentiers/ttiers",
         "code":"SYFRE2",
         "caption":"syfre 2",
         "sitesList":[
            {
               "code":"SITE1",
               "caption":"site2 de syfre2",
               "adresse":{
                  "nomRueVoie":"rue de la pompe",
                  "ville":"Clichy",
                  "codePostal":"92100",
                  "pays":{
                     "$where":"codeISO = 'FRA'",
                     "$orderby":"codeISO"
                  }
               }
            }
         ]
      }
   ]
}

Gestion de la transaction dans un batch

Par défaut les opérations réalisées sont unitaires (une transaction par ressource).

Pour réaliser une opération Batch atomique (une seule transaction longue) utilisez un élément de contrôle transaction :

Lorsque l'opération est atomique la réponse contient un élément $batch indiquant le statut de l'opération.

Le code de retour http est le code de retour de la dernière opération réalisée.

POST http://localhost:8080/sdata/$batch
{
   "$": {"$transaction":["atomic"]},
   "$resources":[
      {
         "$httpMethod":"PUT",
         "$url":"gentiers/ttiers('9D33A23CFA6A005500F6000000285DAE')",
         "$uuid":"1",
         "capital":{"value":7200,"CodeDevise":"USD"}
      },
      {
         "$httpMethod":"PUT",
         "$url":"gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
         "$uuid":"2",
         "capital":{"value":1000,"CodeDevise":"EUR"}
      }
   ]
}
Response : 401
{
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
    "$title": "$batch - -",
    "$resources": [
        {
            "$httpStatus": 200,
            "$httpMethod": "PUT",
            "$httpMessage": "OK",
            "$etag": "9D33A23CFA6A005500F6000000285DAE-0000018C00000001"
        },
        {
            "$httpStatus": 410,
            "$httpMessage": "Already Deleted",
            "$uuid": "2",
            "$url": "gentiers/ttiers('9D33A23CFA6A005500F600000023048C')",
            "$": {
                "$diagnoses": [
                    {
                        "severity": "error",
                        "message": "Already Deleted",
                        "sdataCode": "ApplicationDiagnosis"
                    }
                ]
            }
        }
    ],
    "$batch": {
        "$httpStatus": 400,
        "$httpMessage": "ROLLBACK",
        "$": {
            "$diagnoses": [
                {
                    "severity": "error",
                    "message": "Already Deleted",
                    "sdataCode": "ApplicationDiagnosis",
                    "entry": {
                        "number": 2,
                        "uuid": "2"
                    }
                }
            ]
        }
    }
}

$transaction :

Tip : L'élément de contrôle de transaction peut être placé au niveau d'un ordre du lot.

Execution de méthode dans un batch

Utiliser le verbe EXEC pour exécuter une méthode

POST http://localhost:8080/sdata/$batch
{
   "$resources":[
      {
         "$httpMethod":"EXEC",
         "$url":"testsyfrewf/wfprocessus/testmethod",
         "$resource":{
            "uneChaine":"value 1"
         },
         "p":"value 2"
      }
   ]
}
Response : 200 OK
{
    "$baseUrl": "http://localhost:8080/sdata/l1000/-/-/",
    "$title": "$batch - -",
    "$resources": [
        {
            "$httpStatus": 200,
            "$httpMethod": "POST",
            "$httpMessage": "Executed",
            "$url": "testsyfrewf/wfprocessus/testmethod",
            "$uuid": "",
            "result": "value 1 value 2"
        }
    ]
}

Schéma d'une ressource (GET $schema)

Le schéma d'une ressource retourne la structure de la classe.

GET http://localhost:8080/sdata/testsyfrewf/wfclassea/$schema
Response : 200 OK
{
    "title": "Libellé de la Classe A",
    "properties": {
        "unBool": {
            "type": "boolean",
            "title": "Un Bool"
        },
        "unCode": {
            "type": "string",
            "title": "Un code"
        },
        "unCompteur": {
            "type": "string"
        },
        "unDerive": {
            "type": "string",
            "title": "Un dérivé"
        },
        "unDouble": {
            "type": "double",
            "title": "Un double"
        },
        "uneChaine": {
            "type": "string",
            "title": "une chaine"
        },
        "unEmail": {
            "type": "string",
            "title": "Un email"
        },
        "unEntier": {
            "type": "int",
            "title": "Un Entier"
        },
        "unEtat": {
            "type": "integer",
            "title": "Un Etat"
        },
        "unStatus": {
            "type": "int",
            "title": "Statut de l'objet (Panel)"
        },
        "WFClasseBRef": {
            "type": {
                "$ref": "http://localhost:8080/sdata/l1000/testsyfrewf/-/WFClasseB/$schema",
                "$relationship": "reference"
            },
            "title": "Référence B"
        },
        "WFClasseCList": {
            "type": "array",
            "item": {
                "title": "Classe C",
                "properties": {
                    "uneChaine": {
                        "type": "string",
                        "title": "une chaine"
                    },
                    "unEntier": {
                        "type": "int",
                        "title": "un entier"
                    }
                }
            }
        }
    },
    "$url": "http://localhost:8080/sdata/l1000/testsyfrewf/-/WFClasseA/$schema"
}

Modèle de ressource (GET $template)

Le modèle de ressource retourne une ressource initialisée

GET http://localhost:8080/sdata/gcimport/TImportContratCommercial/$template
Response : 200 OK

{
    "$url": "http://localhost:8080/sdata/l1000/gcimport/-/TImportContratCommercial",
    "stamp": "000001D900000001",
    "acompte": 0,
    "affaire": "",
    "budget": "",
    "Caption": "",
    "commandeEngagement": false,
    "commercial": "",
    "coursDevise": {
        "value": 1,
        "CodeDevise": "",
        "Date": "1899-12-30T00:00:00.000Z",
        "TCConv": "",
        "TCValue": 0,
        "RPConv": "",
        "RPValue": 0
    },
    "coursNegocie": false,
    "dateCommande": "1899-12-30T00:00:00.000Z",
    "dateLivraison": "1899-12-30T00:00:00.000Z",
    "devise": "",
    "donneeEDI1": "",
    "donneeEDI2": "",
    "donneeEDI3": "",
    "donneeEDI4": "",
    "donneeEDI5": "",
    "echeancement": "",
    "etablissement": "",
    "exonereTaxe": "",
    "exonereTVA": "",
    "gestionTransport": {
        "value": 0,
        "title": "Automatique"
    },
    "immobilisation": {
        "value": 0,
        "title": "B&S"
    },
    "ImportCCDetailList": [],
    "importeGMAO": false,
    "importerRemisePied": false,
    "ImportSiteAdresse": {},
    "incoterm": "",
    "MentionExonerationTVA": "",
    "posteBudgetaire": "",
    "pourcentAcompte": {
        "value": 0,
        "Decimales": 2
    },
    "pourcentRemisePied": {
        "value": 0,
        "Decimales": 2
    },
    "reference": "",
    "referenceMandat": "",
    "regimeTVA": "",
    "roleTiers": "",
    "roleTiersLivre": "",
    "SessionImportation": {},
    "typeFacturation": {
        "value": 0,
        "title": "HT"
    }
}

Voir aussi les exemples suivants :

• Interrogation des écritures avec l'API SData
• Interrogation des fournisseurs avec l'API SData
• Création d'un fournisseur avec l'API SData
• Import de commandes avec l'API SData
• Import d'écritures avec l'API SData