Application de workflow RESTAPICLIENT

Aperçu
L'application de workflow RESTAPICLIENT vous permet d'appeler des points de terminaison de l'API REST pour échanger des informations avec d'autres applications via des requêtes HTTP. Elle peut également être utilisée pour créer des intégrations avec des applications extensibles (telles que les services Azure et Slack).
RESTAPICLIENT vous permet également d'appeler un point de terminaison de l'API REST à l'aide de charges utiles application/json ou application/x-www-form-urlencoded. RESTAPICLIENT recevra et traitera ensuite la réponse de l'API externe en mappant le contenu de la réponse avec les paramètres OUT définis.
Mode de fonctionnement
L'application RESTAPICLIENT requiert le paramètre APP_URL, qui correspond au point de terminaison de l'API REST.

Le type de contenu du charge utile de demande par défaut (APP_REQUEST_CONTENT_TYPE) est application/json. Le type de contenu application/x-www-form-urlencoded est également supporté.

La méthode de requête HTTP de demande par défaut (APP_METHOD) est GET. D'autres méthodes de requête (POST, PUT, DELETE, etc...) sont également supportées.

En cas d'erreur, lorsque le paramètre OUT APP_RESPONSE_IGNORE_ERROR est défini et que sa valeur est Y, l'erreur est ignorée et les paramètres OUT définis (APP_RESPONSE_STATUS ou APP_RESPONSE_CONTENT) sont mappés. Sinon, une exception sera levée.

Les paramètres de l’application étant sensibles à la casse, ils doivent utiliser la notation acceptée par l’API.

Le délai d'expiration de la demande par défaut est de 3 000 millisecondes; cette valeur par défaut peut être modifiée en définissant la valeur du paramètre RestApiClientRequestTimeout dans le fichier web.config. Le délai d'expiration de la demande peut également être défini dans le paramètre IN APP_TIMEOUT; le délai d'expiration maximum est de 60 000 millisecondes (1 heure).

✏️ Note : Cette valeur de délai d'expiration doit être inférieure à la valeur de délai d'expiration de la demande IIS.

Les en-têtes de requête HTTP peuvent être définis avec les paramètres APP_HEADER_xxx, où xxx est le nom du champ d'en-tête. Pour plus d'informations, voir la section Paramètres d'en-tête.

La charge utile de la demande peut être définie dans les paramètres IN APP_REQUEST_CONTENT_FILE ou APP_REQUEST_CONTENT. Lorsque les deux paramètres sont définis, le paramètre APP_REQUEST_CONTENT_FILE est prioritaire. Pour plus d'informations sur ces paramètres, voir la section Charge utile de demande.

La réponse de l'API REST peut être mappée sur les paramètres OUT APP_RESPONSE_CONTENT_FILE ou APP_RESPONSE_CONTENT. Les deux paramètres peuvent être définis en même temps. Pour plus d'informations sur ces paramètres, voir la section Charge utile de réponse.

Outre les paramètres facultatifs listés ci-dessous, vous pouvez également ajouter des paramètres supplémentaires IN et OUT personnalisés pour envoyer et recevoir des données personnalisées définies par l'utilisateur vers et depuis l'API externe. Pour plus d'informations et des exemples sur ces paramètres IN et OUT personnalisés, voir les sections Charge utile de demande et Charge utile de réponse.

L'application supporte le langage de requête JSONPath (voir https://github.com/json-path/JsonPath), qui permet d'extraire des données spécifiques à partir d'une réponse JSON (similaire aux expressions XPath en XML). Pour plus d'informations sur l'utilisation de cette application avec des exemples, voir la section Charge utile de réponse.

Des logs d'application sont disponibles. Ceux-ci peuvent être spécifiés en définissant la valeur du paramètre RestApiClientLogLevel dans le fichier web.config sur 0 pour désactiver la journalisation, 1 pour les logs simples ou 2 pour les logs de débogage; la valeur par défaut est 0.

La longueur de réponse maximale par défaut est de 4194304 caractères (4 Mo); cette valeur par défaut peut être modifiée en définissant la valeur du paramètre RestApiClientMaxResponseLength dans le fichier web.config.

La suppression automatique des fichiers temporaires peut être désactivée en définissant la valeur du paramètre RestApiClientEnableFilesCleanUp sur N dans le fichier web.config; la valeur par défaut est Y.

Paramètre obligatoire
Paramètre
Type
Direction
Description
APP_URL
Text
IN
URL de l'API externe
Paramètres facultatifs
Général
Paramètre
Type
Direction
Description
APP_TIMEOUT
Numeric
IN
Intervalle de temps maximum entre l'envoi de la demande et la réception de la réponse
​
La valeur par défaut est 3 000 millisecondes et le maximum est 60 000 millisecondes. La valeur par défaut peut être modifiée en définissant la valeur du paramètre RestapiClientRequestTimeout dans le fichier web.config.
​
✏️ Note : Cette valeur de délai d'expiration doit être inférieure à la valeur de délai d'expiration de la demande IIS.
APP_METHOD
Text
IN
Méthode d'API
​
La valeur par défaut est GET. POST, PUT, DELETE, HEAD et PATCH sont également supportés.
APP_REQUEST_CONTENT_TYPE
Text
IN
Type de contenu de requête supporté par l'API externe
​
L’application supporte application/json et application/x-www-form-urlencoded); la valeur par défaut est application/json.
APP_RESPONSE_IGNORE_ERROR
Text
IN
Lorsque défini sur Y, l'application ignore l'erreur lorsqu'une exception WebException se produit ou que l'API externe renvoie un statut de réponse supérieur ou égal à 300; la valeur par défaut est N.
Paramètres APP_URL facultatifs
Paramètre
Type
Direction
Description
APP_URL_xxx
Text
IN
Paramètre facultatif d'URL de l'API où xxx est le nom du paramètre d'URL
📌 Exemple
Paramètre
Type
Direction
Valeur
APP_URL
Text
IN
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}
APP_URL_subscriptionId
Text
IN
457a2a46-7a7f-4afa-940d-8779e1425fa8
APP_URL_resourceGroupName
Text
IN
dev-group-advantys
APP_URL_topicName
Text
IN
dev-topic
Les paramètres définis ci-dessus généreront l'URL suivante dans APP_URL :
1
https://management.azure.com/subscriptions/457a2a46-7a7f-4afa-940d-8779e1425fa8/resourceGroups/dev-group-advantys/providers/Microsoft.EventGrid/topics/dev-topic
Copied!
Paramètres d'en-tête
Paramètre
Type
Direction
Description
APP_HEADER_xxx
Text
IN
Paramètres d'en-tête de l'API externe où xxx est le nom du champ d'en-tête
📌 Exemple
Paramètre
Type
Direction
Valeur
APP_HEADER_Authorization
Text
IN
Bearer AbCdEf123456
APP_HEADER_location
Text
IN
canadaeast
Les paramètres définis ci-dessus généreront deux en-têtes dans la charge utile de la demande :
1
Authorization: Bearer AbCdEf123456
2
location: canadaeast
Copied!
Paramètres d'autorisation
L'application supporte également certains paramètres d'en-tête d'autorisation prédéfinis afin d'éviter d'ajouter ces paramètres d'en-tête HTTP avec le nom de paramètre APP_HEADER_xxx.
Paramètre
Type
Direction
Description
APP_AUTH_BASIC_USERNAME
Text
IN
Nom d'utilisateur de base de l'autorisation API
APP_AUTH_BASIC_PASSWORD
Text
IN
Mot de passe de base de l'autorisation API
API authorization Basic password; doit être utilisé avec le paramètre APP_AUTH_BASIC_USERNAME
APP_AUTH_BEARER_TOKEN
Text
IN
Jeton du porteur de l'autorisation API
APP_AUTH_AZ_SAS_TOKEN
Text
IN
Jeton SAS Azure de l'autorisation API
Un seul en-tête d'autorisation peut être défini, sinon une exception est levée.

APP_AUTH_BEARER_TOKEN équivaut à définir le paramètre d'en-tête APP_HEADER_Authorization. 
Charge utile de demande
Il existe deux manières différentes de préparer la charge utile de demande. La première consiste à accéder à la totalité de la charge de demande (voir Définir la charge utile de la demande entière via un paramètre ci-dessous); la seconde consiste à créer le JSON ou l'URL codée via les paramètres IN (voir les sections Charge utile de demande encodée en URL et la Charge utile de demande JSON ci-dessous.
Définir la charge utile de demande entière via un paramètre
Les paramètres suivants peuvent être utilisés lorsque vous avez accès à l'ensemble de la charge utile de demande ou que le type de contenu de la demande n'est pas application/json ni application/x-www-form-urlencoded. Vous pouvez définir la charge de cette demande dans une donnée de type File ou Text ou directement dans la valeur de texte.
Paramètre
Type
Direction
Description
APP_REQUEST_CONTENT_FILE
File
IN
Demander une charge utile dans un fichier
APP_REQUEST_CONTENT
Text
IN
Charge utile de la demande
APP_REQUEST_CONTENT_FILEa la priorité sur APP_REQUEST_CONTENT.

APP_REQUEST_CONTENT a la priorité sur les paramètres IN utilisés pour créer une charge utile JSON ou encodée en URL.
Charge utile de demande encodée en URL
Les exemples suivants montrent comment créer une charge utile de demande avec application/x-www-form-urlencoded comme type de contenu.
Charge utile de demande en URL standard
Les paramètres suivants sont utilisés pour créer une charge utile de demande  encodée en URL standard :
Paramètre
Type
Direction
Description
param1
Text
IN
value1
param2
Text
IN
value2
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
param1=value1&param2=value2
Copied!
Charge utile de demande JSON encodée dans un nom de clé
Les paramètres suivants permettent de générer une charge JSON encodée dans un nom de clé :
Paramètre
Type
Direction
Description
param1
Text
IN
value1
param2
Text
IN
value2
APP_REQUEST_CONTENT_PAYLOAD_NAME
Text
IN
payload
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
payload: { param1: "value1", "param2": "value2" }
Copied!
Le paramètre APP_REQUEST_CONTENT_PAYLOAD_NAME est seulement supporté avec le type de contenu de demande application/x-www-form-urlencoded.
Charge utile de demande JSON
Les exemples suivants montrent comment créer une charge utile de demande avec application/json comme type de contenu.
Charge utile de demande JSON standard
Les paramètres suivants sont utilisés pour créer une charge utile de demande JSON simple :
Paramètre
Type
Direction
Valeur
person.address.street
Text
IN
160 Guy Street
person.address.zipcode
Text
IN
J4G 1U4
person.age
Text
IN
30
person.name
Text
IN
John
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
{
2
    "person": {
3
        "address": {
4
            "street": "160 Guy Street",
5
            "zipcode": "J4G 1U4"
6
        },
7
        "age": 30,
8
        "name": "John"
9
    }
10
}
Copied!
Si vous souhaitez convertir ce JSON en tableau, vous devez définir la valeur du paramètre APP_REQUEST_CONTENT_IS_ARRAY sur Y.
Paramètre
Type
Direction
Description
APP_REQUEST_CONTENT_IS_ARRAY
Text
IN
Lorsque ce paramètre est défini sur Y, l'application convertit la charge utile de la demande JSON en un tableau; la valeur par défaut est N
​
Uniquement supporté lors de la construction d'une charge utile de demande JSON avec des paramètres IN.
Le paramètre APP_REQUEST_CONTENT_IS_ARRAY défini sur Y générera la charge utile de demande suivante :
1
[{
2
    "person": {
3
        "address": {
4
            "street": "160 Guy Street",
5
            "zipcode": "J4G 1U4"
6
        },
7
        "age": 30,
8
        "name": "John"
9
    }
10
}]
Copied!
Pour savoir comment créer un JSON plus complexe, voir les sections Définition d'un tableau JSON dans une propriété JSON et Définition d'un objet ou d'un tableau JSON dans une propriété JSON avec le paramètre de suffixe __JSON ci-dessous.
Définition d'un tableau JSON dans une propriété JSON
Pour définir un tableau dans une propriété JSON, vous devez définir le chemin de la propriété (par exemple, person.spokenlanguages) suivi du suffixe __X, où X est le numéro d'index du tableau.
Les paramètres suivants permettent de définir un tableau JSON dans une propriété JSON :
Paramètre
Type
Direction
Valeur
person.spokenlanguages__0
Text
IN
french
person.spokenlanguages__1
Text
IN
english
person.spokenlanguages__2
Text
IN
chinese
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
{
2
    "person": {
3
        "spokenlanguages": ["french", "english", "chinese"]
4
    }
5
}
Copied!
Si vous souhaitez définir un tableau JSON d'objets JSON (p.ex. "spokenlanguages": [{"spokenlanguage":"french"}, {"spokenlanguage":"english"}]) dans une propriété JSON, voir la section suivante.
Les paramètres du tableau seront ordonnés en fonction de leur numéro d'index.

Les numéros index n'ont pas de limite (p.ex. person.spokenlanguages__9999).

Une séquence d'index correcte n'est pas obligatoire (p.ex.person.spokenlanguages__90, person.spokenlanguages__30). La valeur du paramètre __30 sera le premier paramètre de tableau et __90 sera le deuxième.

Une exception sera levée si plusieurs propriétés JSON sont spécifiées dans les paramètres IN (p.ex. person.spokenlanguages etperson.spokenlanguages__0).

Le suffixe __X utilise deux caractères de soulignement.

La valeur du paramètre ne peut être qu'une valeur de texte.
Définition d'un objet ou d'un tableau JSON dans une propriété JSON avec le paramètre de suffixe __JSON
Pour définir un objet / un tableau JSON dans une propriété JSON, vous devez définir le chemin de la propriété (p.ex. person.children) suivi du suffixe __JSON avec l'objet ou le tableau JSON comme valeur de paramètre.
Les paramètres suivants permettent de définir un objet ou un tableau JSON dans une propriété JSON:
Paramètre
Type
Direction
Valeur
person.children__JSON
Text
IN
[{"name": "child 1"}, {"name": "child 2"}]
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
{
2
    "person": {
3
        "children": [{
4
            "name": "child 1"
5
        }, {
6
            "name": "child 2"
7
        }]
8
    }
9
}
Copied!
Une exception sera levée si plusieurs propriétés JSON sont spécifiées dans les paramètres IN (p.ex. person.childrenetperson.children__JSON).

Le suffixe __JSON utilise deux caractères de soulignement.
Charge utile de réponse
L'application supporte le mappage des paramètres OUT avec la réponse HTTP :
Paramètre
Type
Direction
Description
APP_RESPONSE_STATUS
Text/Numeric
OUT
Code statut de la réponse
APP_RESPONSE_CONTENT_TYPE
Text
OUT
Type de contenu de la réponse
APP_RESPONSE_CONTENT_FILE
File
OUT
Charge utile de la réponse ou message d'erreur dans un fichier
APP_RESPONSE_CONTENT
Text
OUT
Charge utile de la réponse ou message d'erreur 
APP_RESPONSE_CONTENT_IS_ARRAY
Text
OUT
Renvoie Y si la charge JSON est un tableau
​
Seulement supporté pour les réponses de type de contenu application/json.
Mappage d'une charge utile de réponse JSON avec des paramètres OUT
L'application supporte également des paramètres OUT personnalisés supplémentaires pour mapper la charge utile d'une réponse JSON simple.
📌 Exemple
Charge utile de réponse JSON :
1
{
2
    "person": {
3
        "address": {
4
            "street": "160 Guy Street",
5
            "zipcode": "J4G 1U4"
6
        },
7
        "age": 30,
8
        "name": "John"
9
    }
10
}
Copied!
Les paramètres suivants permettront de mapper la charge utile de la réponse dans différentes données de processus :
Paramètre
Type
Direction
Récupérer la valeur dans une donnée
person.address.street
Text
OUT
DATA_STREET
person.address.zipcode
Text
OUT
DATA_ZIPCODE
person.age
Text
OUT
DATA_AGE
person.name
Text
OUT
DATA_NAME
Pour mapper des JSON complexes, voir la section suivante.
Mappage d'une charge utile de réponse JSON avec des paramètres OUT à l'aide du langage de requête JSONPath
L'application supporte le langage de requête JSONPath (similaire aux expressions XPath en XML). Ce langage vous permet d'extraire des données spécifiques d'un fichier JSON. Pour plus de détails sur la syntaxe JSONPath, voir https://github.com/json-path/JsonPath.
📌 Exemple
Charge utile de réponse JSON :
1
{
2
    "person": {
3
      "name": "Elizabeth",
4
      "children": [
5
        {
6
          "name": "Charles",
7
          "age": 30,
8
          "children": [
9
            {
10
              "name": "Nathalie",
11
              "children": [
12
                {
13
                  "name": "George",
14
                  "age": 8
15
                },
16
                {
17
                  "name": "Charlotte",
18
                  "age": 10
19
                },
20
                {
21
                  "name": "Jefferson",
22
                  "age": 7
23
                }
24
              ]
25
            },
26
            {
27
              "name": "Harry"
28
            }
29
          ]
30
        },
31
        {
32
          "name": "Bob",
33
          "age": 20,
34
          "children": [
35
            {
36
              "name": "John"
37
            },
38
            {
39
              "name": "Mark"
40
            }
41
          ]
42
        }
43
      ]
44
    }
45
}
Copied!
Par exemple, nous voulons ici obtenir les noms des petits-fils de Charles âgés de plus de sept ans, et nous voulons également que ces noms soient séparés par un | (en utilisant le paramètre IN APP_JSONPATH_DELIMITER). Pour obtenir cette information, les paramètres suivants doivent être définis :
Paramètre
Type
Direction
Valeur IN
OUT Value
APP_JSONPATH_DELIMITER
Text
IN
|
-
PARAM1__JSONPATH
Text
INOUT
person.children[?(@.name == 'Charles')].children[*].children[?(@.age > 7)].name
DATA1_VALUE (value will be: George|Charlotte)
Dans le nom du paramètre PARAM1__JSONPATH, le nom de PARAM1 n'est pas pertinent, mais il doit être suivi du suffixe __JSONPATH (deux traits de soulignement sont utilisés dans le suffixe).

La valeur par défaut de APP_JSONPATH_DELIMITER est une virgule (,) lorsque ce paramètre n'est pas défini.
Exemple d'utilisation avec l'API Azure REST pour obtenir un jeton d'accès OAuth 2.0 et créer une rubrique Event Grid
Cet exemple montre comment obtenir un jeton d'accès et l'utiliser pour créer une rubrique Event Grid. Cela peut être fait en créant un processus avec deux actions ayant RESTAPICLIENT comme application. Le workflow ci-dessous illustre cet exemple :
Les sections suivantes décrivent les paramètres à déclarer pour chaque action.
Action GET_TOKEN : Obtention d'un jeton d'accès OAuth 2.0
Les paramètres suivants sont nécessaires pour obtenir un jeton d'accès afin d'utiliser l'API de gestion Azure Resource. Ce jeton sera stocké dans le paramètre OUT access_token et sera utilisé lors de la création d'une rubrique Event Grid dans la section suivante.
Paramètre
Type
Direction
Valeur
APP_URL
Text
IN
https://login.microsoftonline.com/{tenandId}/oauth2/token
APP_URL_tenantId
Text
IN
a6e70c61-fabd-4885-89f7-97121e92db7f
APP_METHOD
Text
IN
POST
APP_REQUEST_CONTENT_TYPE
Text
IN
application/x-www-form-urlencoded
grant_type
Text
IN
client_credentials
client_id
Text
IN
b7e29e2f-6e2b-4375-9684-8151431d4ca6
client_secret
Text
IN
lxy/IwKyTedHUWMeeUtyCtu7/YUy0rNGoY3NNWXXotI=
resource
Text
IN
https://management.core.windows.net/
access_token
Text
OUT
DATA_ACCESS_TOKEN
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
POST https://login.microsoftonline.com/a6e70c61-fabd-4885-89f7-97121e92db7f/oauth2/token HTTP/1.1
2
Host: login.microsoftonline.com
3
Content-Type: application/x-www-form-urlencoded
4
​
5
grant_type=client_credentials&client_id=b7e29e2f-6e2b-4375-9684-8151431d4ca6&client_secret=lxy/IwKyTedHUWMeeUtyCtu7/YUy0rNGoY3NNWXXotI=&resource=https://management.core.windows.net/
Copied!
Voici la réponse de l'API Azure :
1
{  
2
   "token_type":"Bearer",
3
   "expires_in":"3600",
4
   "ext_expires_in":"3600",
5
   "expires_on":"1555951493",
6
   "not_before":"1555947593",
7
   "resource":"https://management.core.windows.net/",
8
   "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d..."
9
}
Copied!
Le paramètre OUT access_token est mappé avec la propriété JSON access_token.
Pour plus d'informations sur l'obtention d'un jeton d'accès pour utiliser l'API de ressource Azure, voir https://docs.microsoft.com/fr-fr/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow.
Action CREATE_TOPIC : création d'une rubrique Event Grid
Les paramètres suivants sont nécessaires pour créer une rubrique Event Grid à l'aide de l'API de gestion des ressources Azure.
Paramètre
Type
Direction
Valeur
APP_URL
Text
IN
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}?api-version={api-version}
APP_URL_subscriptionId
Text
IN
235765d9-5d62-43f4-a730-2ed71a3f8adb
APP_URL_resourceGroupName
Text
IN
dev-group-advantys
APP_URL_topicName
Text
IN
new-topic-example
APP_URL_api-version
Text
IN
2018-09-15-preview
APP_METHOD
Text
IN
PUT
APP_REQUEST_CONTENT_TYPE
Text
IN
application/json
APP_AUTH_BEARER_TOKEN
Text
IN
DATA_ACCESS_TOKEN
location
Text
IN
canadaeast
Les paramètres définis ci-dessus généreront la charge utile de demande suivante :
1
PUT https://management.azure.com/subscriptions/235765d9-5d62-43f4-a730-2ed71a3f8adb/resourceGroups/dev-group-advantys/providers/Microsoft.EventGrid/topics/new-topic-example?api-version=2018-09-15-preview
2
Host: management.azure.com
3
Content-Type: application/json
4
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d...
5
location: canadaeast
Copied!
Voici la réponse de l'API Azure:
1
{  
2
   "properties":{  
3
      "provisioningState":"Creating",
4
      "endpoint":null
5
   },
6
   "location":"canadaeast",
7
   "tags":null,
8
   "id":"/subscriptions/994e2fc0-937d-4110-b355-e7473acef822/resourceGroups/dev-evt-grid/providers/Microsoft.EventGrid/topics/test-from-wfg",
9
   "name":"test-from-wfg",
10
   "type":"Microsoft.EventGrid/topics"
11
}
Copied!
Pour plus d'informations sur la création d'une rubrique Event Grid et sur l'API Azure REST, voir https://docs.microsoft.com/fr-fr/rest/api/eventgrid/topics/createorupdate.
Activation de SSL / TLS
En cas d'erreur Impossible de créer le canal sécurisé SSL / TLS, le chiffrement renforcé doit être activé en exécutant le code suivant dans PowerShell :
1
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord
2
​
3
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord
Copied!
Redémarrez votre serveur IIS après avoir exécuté les commandes.