5. Data Action | Cirrus Shield Help

URL: /RestApi/DataAction/<objectName>?authToken=<authToken>&action=<insert|update|upsert|delete>&matchingFieldName=<matchingFieldName>&useExternalId=<false|true>

Méthode: POST

Paramères de l’URL:

objectName [string] [Required]=le nom de l’objet que l’utilisateur veut insérer/mettreà jour/upserter/supprimer
authToken [string] [Required]=l’authentication token
action [string] [Required]=l’action que l’utilisateur veut appliquert (insertion, mise à jour, insertion et mise à jour ou suppression)
matchingFieldName [string] [Required]=le nom du champ qui est considéré comme champ unique dans l’enregistrement envoyé.
Le paramètre « useExternalId » est optionel. Et s’il n’est pas envoyé dans l’URL, il prend la valeur par défaut qui est « True » (Vrai)

Notes sur l’utilisation du paramètre “useExternalId”

Si « useExternalId »=true alors en important les données à travers la Rest API, les champs de relations de recherche doivent être définit au champ “External Id” de l’enregistrement de relation de recherche.

Si « useExternalId »=false ou il n’y a pas de champ “External Id” paramétré sur l’objet parent, alors, en important les données à travers la Rest API, les champs de relation de recherche doivent être définit au champ « Id » de l’enregistrement de la relation de recherche.

Exemple: s’il faut importer le contact suivant à travers la Rest API (le champ “Account” est une relation de recherhce à l’objet parent “Account” et le champ “Name” sur l’objet “Account” est un champ “External Id”):

1- Si useExternalId n’est pas défini ou définit comme “true”:

<Data>
  <Contact>
    <FirstName>Sarah</FirstName>
    <LastName>Johnson</LastName>
    <Account>Test Account 1</Account>
  </Contact>
</Data>

2- Si useExternalId est définit comme “false”:

<Data>
  <Contact>
    <FirstName>Sarah</FirstName>
    <LastName>Johnson</LastName>
    <Account>2458939956261816452</Account>
  </Contact>
</Data>

où l’enregistrement de relation de recherhce “Account” est:

Nom	Id
Test Account 1	2458939956261816452

Paramètres de données:

xmlData [XML]=les données de l’enregistrement à insérert/mettre à jour/upserter/supprimer

Recommandation d'usage de l'API de Cirrus Shield

Afin de faire une utilisation « saine » de la REST API de Cirrus Shield et pour une meilleure performance de votre code, nous recommandons d’envoyer les données en mode “bulk” à l’API de Cirrus Shield, c’est-à-dire en mettant dans un seul XML plusieurs données au lieu de mettre un seul enregistrement par XML et de faire plusieurs appels. Cette approche permet de faire des opérations en masse et est plus efficace d’un point de vue performance et utilisation des ressources.

Par exemple lorsque vous avez plusieurs données à envoyer, il vaut mieux les mettre dans un seul XML à la manière de l’exemple ci-dessous qui envoie 2 comptes dans le même XML.

Exemple:

<Data> 
  <Account> 
    <Name>Account Test 1</Name> 
    <Address>Address Test 1</Address> 
  </Account> 
  <Account> 
    <Name>Account Test 2</Name> 
    <Address>Address Test 2</Address> 
  </Account>
</Data>

Dans la mesure où les données sont envoyées dans un appel web, pensez à encoder les données avec une fonction du type urlencode(), notamment pour les champs de type date/heure qui doivent contenir la timezone (notée avec un +).

En effet si cela n’est pas fait, la valeur sera enregistrée dans la base sans le signe “+”.

Exemple : “2017-06-12 15:40: 47 02 ” au lieu de “2017-06-12 15:40: 47+02 “.

Exemple d’utilisation d’urlencode() :

$ xmlData = urlencode ("<Data>""<Campaign>""<Name> Campagne-". $ CampaignID. "</Name>""<Campaign_ID>". $ CampaignID. "</Campaign_ID>""<TestDateTime>"2017-06-12 15: 40: 47 + 02"."</TestDateTime>""<OwnerId>".$ OwnerID. "</OwnerId>""<Campaign>""<Data>");

Réponse de réussite de l’appel:

Status Code=200 (OK)
Returned Data [in XML ou JSON]=une liste de données d’enregistrements envoyés dans le HTTP Post Resquest body avec 2 champs additionnels pour chaque enregistrement:
- 1- Succès: pour indiquer si l’opération (insertion/mise à jour/upsert/suppremssion) appliquée dans l’enregistrement correspondant a échoué ou pas,
- 2- Message d’erreur : pour indiquer quelle est l’erreur qui a causé l’échouement de l’opération appliquée sur cet enregistrement.

Exemple de données retournées par l’API :

<Data> 
  <Account> 
    <Name>Account Test 1</Name> 
    <Address>Address Test 1</Address> 
    <Success>FALSE</Success> 
    <ErrorMessage>Some of the Lookup Fields contain invalid values</ErrorMessage> 
  </Account> 
  <Account> 
    <Name>Account Test 2</Name> 
    <Address>Address Test 2</Address> 
    <Success>TRUE</Success> 
    <ErrorMessage /> 
  </Account>
</Data>

Réponse lorsqu’il y a une erreur dans l’appel API:

Status Code=401 (Unauthorized) en cas de fausse authentication token.
Ou
Status Code=400 (BadRequest) : au cas où aucun nom d’objet n’a été spécifié ou aucune action n’a été spécifiée ou s’il y a une erreur dans les données de l’enregistrement de l’xml envoyé dans le HTTP Post Request body ou si un enregistrement ou plus n’ont pas pu être insérés/mis à jour/upsertés/supprimés.

Recommandation d'usage de l'API de Cirrus Shield

Comment pouvons-nous aider ?