Appel de services web pour les flux de travail SharePoint
Vous pouvez utiliser le modèle de complément SharePoint pour créer et déployer des flux de travail qui s’exécutent sur le site web du complément ou sur le site web hôte. Ces flux de travail peuvent interagir avec les parties hébergées à distance des compléments hébergés par un fournisseur.
Les flux de travail peuvent également appeler des services web distants qui contiennent des données métier importantes de l’une des deux manières suivantes :
En transmettant des informations de requête à la partie hébergée à distance du complément. L’application web distante appelle ensuite le service web et transmet les informations à SharePoint.
En interrogeant le service web à l’aide du proxy web SharePoint. Le flux de travail transmet les résultats de la requête à la partie hébergée à distance du complément, qui transmet ensuite les informations à SharePoint.
Les informations récupérées à partir du service web peuvent être stockées dans des listes SharePoint.
Cet article décrit trois exemples de code qui vous montrent comment appeler des services web à partir de flux de travail, comme indiqué dans le tableau suivant. Dans les deux premiers exemples, les flux de travail et les listes sont déployés sur le site web du complément lors de l’installation du complément. Le dernier exemple fournit l’interpréteur de commandes de base d’un flux de travail et des instructions pour le déployer sur le site web hôte et l’associer à une liste sur le site web hôte.
Tâches de flux de travail et exemples associés
| Tâche | Échantillon |
|---|---|
| Appeler des services web personnalisés à partir d’un flux de travail. | Workflow.CallCustomService |
| Appelez un service web personnalisé à partir d’un flux de travail et mettez à jour SharePoint à l’aide du proxy web SharePoint. | Workflow.CallServiceUpdateSPViaProxy |
| Associez un flux de travail au site web hôte. | Workflow.AssociateToHostWeb |
Appeler ces services web personnalisés à partir d’un flux de travail
L’exemple Workflow.CallCustomService vous montre comment créer un flux de travail qui appelle un service web personnalisé qui met à jour les données de liste SharePoint. Il vous montre également comment concevoir un complément hébergé par un fournisseur afin qu’il interroge un service web à l’aide de l’application web hébergée à distance qui se déploie avec le complément. Cet exemple est utile lorsque vous souhaitez que toutes les interactions avec le service web soient gérées par la partie hébergée à distance de votre complément hébergé par un fournisseur.
L’exemple fonctionne en démarrant un flux de travail à partir d’une application web distante. Ce flux de travail transmet les informations de requête soumises par l’utilisateur à l’application web distante, qui utilise ensuite ces informations pour construire une requête au service web Northwind OData. La requête retourne les fournisseurs de produits pour un pays donné. Une fois ces informations reçues, l’application web distante met à jour une liste de fournisseurs de produits que le complément a déployée sur le site web du complément.
Remarque
La page d’exemple Workflow.CallCustomService contient des instructions pour le déploiement de ce complément. Vous pouvez également déployer et tester avec le débogage F5 dans Visual Studio si vous suivez les instructions du billet de blog Débogage des flux de travail SharePoint 2013 à l’aide de Visual Studio 2013.
La page de démarrage de l’exemple de complément Workflow.CallCustomService inclut un menu déroulant dans lequel vous pouvez sélectionner un pays pour lequel vous souhaitez créer une liste de fournisseurs de produits.
Le bouton Créer à l’écran appelle une méthode Create dans le fichier Controllers\PartSuppliersController.cs qui crée une entrée dans la liste Fournisseurs de composants sur le site web du complément. La méthode Create appelle ensuite la méthode Add définie dans le fichier Services\PartSuppliersService.cs. La séquence est illustrée dans les deux exemples de code suivants.
Méthode Create
public ActionResult Create(string country, string spHostUrl)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);
using (var clientContext = spContext.CreateUserClientContextForSPAppWeb())
{
var service = new PartSuppliersService(clientContext);
var id = service.GetIdByCountry(country);
if (id == null)
{
id = service.Add(country);
TempData["Message"] = "Part Supplier Successfully Created!";
}
else
TempData["ErrorMessage"] = string.Format("Failed to Create The Part Supplier: There's already a Part Supplier who's country is {0}.", country);
return RedirectToAction("Details", new { id = id.Value, SPHostUrl = spHostUrl });
}
}
Méthode Add
public int Add(string country)
{
var item = list.AddItem(new ListItemCreationInformation());
item["Country"] = country;
item.Update();
clientContext.ExecuteQuery();
return item.Id;
}
Après avoir créé cet élément de liste, le complément présente un bouton Démarrer le flux de travail qui démarre le flux de travail d’approbation.
Le choix du bouton Démarrer le flux de travail déclenche la méthode StartWorkflow définie dans le fichier Controllers\PartSuppliersController.cs. Cette méthode empaquète l’URL web du complément, l’URL du service web (pour votre application web hébergée à distance, et non pour le service web Northwind) et les valeurs de jeton de contexte, et les transmet à la méthode StartWorkflow. La méthode PartSuppliersService a besoin du jeton de contexte pour interagir avec SharePoint.
public ActionResult StartWorkflow(int id, Guid workflowSubscriptionId, string spHostUrl)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext) as SharePointAcsContext;
var webServiceUrl = Url.RouteUrl("DefaultApi", new { httproute = "", controller = "Data" }, Request.Url.Scheme);
var payload = new Dictionary<string, object>
{
{ "appWebUrl", spContext.SPAppWebUrl.ToString() },
{ "webServiceUrl", webServiceUrl },
{ "contextToken", spContext.ContextToken }
};
using (var clientContext = spContext.CreateUserClientContextForSPAppWeb())
{
var service = new PartSuppliersService(clientContext);
service.StartWorkflow(workflowSubscriptionId, id, payload);
}
TempData["Message"] = "Workflow Successfully Started!";
return RedirectToAction("Details", new { id = id, SPHostUrl = spHostUrl });
}
La méthode StartWorkflow crée ensuite une instance de flux de travail et transmet les trois valeurs (appWebUrl, webServiceUrl, contextToken) stockées dans la variable de charge utile au flux de travail.
{
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var subscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();
var subscription = subscriptionService.GetSubscription(subscriptionId);
var instanceService = workflowServicesManager.GetWorkflowInstanceService();
instanceService.StartWorkflowOnListItem(subscription, itemId, payload);
clientContext.ExecuteQuery();
}
Une fois le flux de travail démarré, il effectue une requête POST HTTP à l’application web hébergée à distance. Cette demande indique à l’application web de mettre à jour la liste des fournisseurs avec les fournisseurs du pays que l’utilisateur vient d’ajouter. Le fichier Controllers\DataController.cs contient une méthode POST qui reçoit le contenu de cette requête.
public void Post([FromBody]string country)
{
var supplierNames = GetSupplierNames(country);
UpdateSuppliers(country, supplierNames);
}
La méthode GetSupplierNames (dans le fichier Controllers\DataController.cs) construit et exécute une requête LINQ sur le service web Northwind OData pour tous les fournisseurs associés au pays sélectionné.
private string[] GetSupplierNames(string country)
{
Uri uri = new Uri("http://services.odata.org/V3/Northwind/Northwind.svc");
var entities = new NorthwindEntities(uri);
var names = entities.Suppliers
.Where(s => s.Country == country)
.AsEnumerable()
.Select(s => s.CompanyName)
.ToArray();
return names;
}
La méthode UpdateSuppliers met ensuite à jour le champ Fournisseurs de l’élément de liste nouvellement ajouté.
private void UpdateSuppliers(string country, string[] supplierNames)
{
var request = HttpContext.Current.Request;
var authority = request.Url.Authority;
var spAppWebUrl = request.Headers["SPAppWebUrl"];
var contextToken = request.Headers["SPContextToken"];
using (var clientContext = TokenHelper.GetClientContextWithContextToken(
spAppWebUrl, contextToken, authority))
{
var service = new PartSuppliersService(clientContext);
service.UpdateSuppliers(country, supplierNames);
}
}
Si vous examinez le mode Création du fichier workflow.xaml dans le répertoire Approuver les fournisseurs du projet de complément, vous voyez (en choisissant l’onglet Arguments en bas à gauche du mode Création) que le flux de travail stocke les trois valeurs dans la variable de charge utile qui lui est transmise en tant qu’arguments de flux de travail.
L’activité HttpSend se produit avant l’approbation du flux de travail. Cette activité envoie la requête POST à votre application web distante qui déclenche l’appel au service web Northwind, puis à la mise à jour de l’élément de liste (avec la liste des fournisseurs). Cette activité est configurée pour envoyer la demande à la valeur webServiceUrl qui a été transmise en tant qu’argument de flux de travail.
La demande POST transmet également la valeur de pays stockée dans l’élément de liste sur lequel le flux de travail fonctionne.
Le flux de travail envoie les valeurs appWebUrl et contextToken à l’application web via les en-têtes de requête. Les en-têtes définissent également les types de contenu pour l’envoi et l’acceptation des demandes.
Si le flux de travail est approuvé, la valeur du champ isApproved de l’élément de liste devient true.
Appeler un service web personnalisé à partir d’un flux de travail et mettre à jour SharePoint à l’aide du proxy web SharePoint
L’exemple Workflow.CallServiceUpdateSPViaProxy montre comment concevoir un complément hébergé par un fournisseur pour interroger un service web, puis transmettre ces informations à une liste SharePoint via le proxy web SharePoint.
L’exemple montre une tâche utile lorsque vous souhaitez encapsuler toutes les interactions avec un service web afin qu’elles soient gérées directement par le flux de travail. L’utilisation du proxy web facilite la mise à jour de la logique d’application web distante sans avoir à mettre à jour l’instance de flux de travail. Si vous n’utilisez pas le proxy et que vous devez mettre à jour la logique dans votre application web, vous devez supprimer les instances de flux de travail existantes, puis redéployer le complément. C’est pourquoi nous vous recommandons cette conception lorsque vous devez appeler un service web distant.
Remarque
La page d’exemple Workflow.CallServiceUpdateSPViaProxy contient des instructions pour le déploiement de ce complément. Vous pouvez également déployer et tester le complément à l’aide du débogage F5 dans Visual Studio si vous suivez les instructions du billet de blog Débogage de flux de travail SharePoint 2013 à l’aide de Visual Studio 2013.
L’exemple démarre un flux de travail à partir d’une application web distante. Ce flux de travail transmet les informations de requête soumises par l’utilisateur au service web Northwind OData. La requête retourne les fournisseurs de produits pour un pays donné. Une fois qu’il a reçu la réponse du service web, le flux de travail transmet les informations de la réponse à l’application web distante. L’application web distante met ensuite à jour une liste de fournisseurs de produits que le complément a déployée sur le site web du complément.
Lorsque vous démarrez l’exemple de complément Workflow.CallServiceUpdateSPViaProxy, la page de démarrage inclut un menu déroulant à partir duquel vous pouvez sélectionner un pays pour lequel vous souhaitez créer une liste de fournisseurs de produits.
Le bouton Créer appelle une méthode dans le fichier Controllers\PartSuppliersController.cs qui crée une entrée dans la liste Fournisseurs de composants sur le site web du complément. La méthode Create dans ce fichier appelle la méthode Add définie dans le fichier Services\PartSuppliersService.cs. Les deux sont présentés dans les deux exemples de code suivants.
Méthode Create
public ActionResult Create(string country, string spHostUrl)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);
using (var clientContext = spContext.CreateUserClientContextForSPAppWeb())
{
var service = new PartSuppliersService(clientContext);
var id = service.GetIdByCountry(country);
if (id == null)
{
id = service.Add(country);
TempData["Message"] = "Part Supplier Successfully Created!";
}
else
TempData["ErrorMessage"] = string.Format("Failed to Create The Part Supplier: There's already a Part Supplier who's country is {0}.", country);
return RedirectToAction("Details", new { id = id.Value, SPHostUrl = spHostUrl });
}
}
Méthode Add
public int Add(string country)
{
var item = list.AddItem(new ListItemCreationInformation());
item["Country"] = country;
item.Update();
clientContext.ExecuteQuery();
return item.Id;
}
Après avoir créé cet élément de liste, le complément présente un bouton Démarrer le flux de travail qui démarre le flux de travail d’approbation.
Le choix du bouton Démarrer le flux de travail déclenche la méthode StartWorkflow dans le fichier Controllers\PartSuppliersController.cs. Cette méthode empaquète l’URL web du complément et celle du service web (pour votre application web hébergée à distance, et non pour le service web Northwind) et les transmet à la méthode StartWorkflow dans le fichier Services\PartSuppliersService.cs. Le flux de travail communique avec l’application web distante via le proxy web, et le proxy web ajoute le jeton d’accès dans un en-tête de requête. C’est pourquoi le flux de travail ne transmet pas de jeton de contexte à la méthode StartWorkflow dans cet exemple. Le code est illustré dans l’exemple suivant.
public ActionResult StartWorkflow(int id, Guid workflowSubscriptionId, string spHostUrl)
{
var spContext = SharePointContextProvider.Current.GetSharePointContext(HttpContext);
var webServiceUrl = Url.RouteUrl("DefaultApi", new { httproute = "", controller = "Data" }, Request.Url.Scheme);
var payload = new Dictionary<string, object>
{
{ "appWebUrl", spContext.SPAppWebUrl.ToString() },
{ "webServiceUrl", webServiceUrl }
};
using (var clientContext = spContext.CreateUserClientContextForSPAppWeb())
{
var service = new PartSuppliersService(clientContext);
service.StartWorkflow(workflowSubscriptionId, id, payload);
}
TempData["Message"] = "Workflow Successfully Started!";
return RedirectToAction("Details", new { id = id, SPHostUrl = spHostUrl });
}
La méthode StartWorkflow crée une instance de flux de travail et transmet les deux valeurs (appWebUrl et webServiceUrl) stockées dans la variable de charge utile au flux de travail.
public void StartWorkflow(Guid subscriptionId, int itemId, Dictionary<string, object> payload)
{
var workflowServicesManager = new WorkflowServicesManager(clientContext, clientContext.Web);
var subscriptionService = workflowServicesManager.GetWorkflowSubscriptionService();
var subscription = subscriptionService.GetSubscription(subscriptionId);
var instanceService = workflowServicesManager.GetWorkflowInstanceService();
instanceService.StartWorkflowOnListItem(subscription, itemId, payload);
clientContext.ExecuteQuery();
}
Une fois le flux de travail démarré et avant d’être approuvé, il envoie une requête au service web Northwind pour récupérer la liste des fournisseurs pour le pays que vous avez sélectionné. Pour ce faire, il utilise une activité HTTPSend qui envoie une requête OData à ce point de terminaison : "http://services.odata.org/V3/Northwind/Northwind.svc/Suppliers/?$filter=Country eq '" + country.Replace("'", "''") + "'&$select=CompanyName".
L’activité HttpSend doit être configurée en tant que demande GET avec un en-tête Accept qui spécifie JSON sans métadonnées : application/json;odata=nometadata.
Si l’utilisateur a sélectionné Canada pour le nouvel élément de liste de fournisseurs, par exemple, la réponse au format JSON sera indiquée dans l’exemple suivant.
{
value: [
{
CompanyName: "Ma Maison"
},
{
CompanyName: "Forêts d'érables"
}
]
}
Une fois le flux de travail démarré, il effectue une requête POST HTTP qui contient la liste des fournisseurs de l’application web hébergée à distance via le proxy. Pour ce faire, il effectue une activité httpSend qui interroge l’URL du proxy web : appWebUrl + "/_api/SP.WebProxy.invoke".
Le flux de travail transmet ensuite la liste des fournisseurs qu’il a reçue du service Northwind en créant et en transmettant une charge utile de service personnalisée. Les propriétés de l’activité Créer une charge utile de service personnalisée contiennent la liste des fournisseurs et l’ID du pays fournisseur.
L’activité Créer une charge de travail WebProxy construit une charge utile qui transmet le contenu de cette charge utile à l’URL du proxy web.
Les propriétés de l’activité Charge utile WebProxy spécifient l’URL web du complément, la longueur et le type de contenu de la demande POST, ainsi que le type d’acceptation de la demande via les en-têtes de requête.
Une fois que le workflow a construit la charge utile et la requête, il transmet la requête au proxy web à l’aide d’une activité HttpSend configurée en tant que requête POST à l’URL du proxy web. Les en-têtes de requête spécifient des OData au format JSON dans les en-têtes Content-Type et Accept.
La méthode Post à l’intérieur du fichier Controllers\DataController.cs accepte le contenu de la requête que le flux de travail envoie via le proxy web. La méthode Post de l’exemple précédent a appelé une méthode pour récupérer la liste des fournisseurs à partir de Northwind, ainsi qu’une méthode pour mettre à jour la liste des fournisseurs SharePoint correspondante.
Étant donné que le flux de travail de cet exemple a déjà interrogé le service Northwind, cette version de la méthode doit uniquement mettre à jour la liste SharePoint. Il transmet également l’URL web du complément et le jeton d’accès (qui est transmis par le proxy web) à la méthode UpdateSuppliers dans le fichier Services\PartSuppliersService.cs, comme illustré dans l’exemple de code suivant.
public void Post(UpdatePartSupplierModel model)
{
var request = HttpContext.Current.Request;
var authority = request.Url.Authority;
var spAppWebUrl = request.Headers["SPAppWebUrl"];
var accessToken = request.Headers["X-SP-AccessToken"];
using (var clientContext = TokenHelper.GetClientContextWithContextToken(spAppWebUrl, accessToken, authority))
{
var service = new PartSuppliersService(clientContext);
service.UpdateSuppliers(model.Id, model.Suppliers.Select(s => s.CompanyName));
}
}
La méthode UpdateSuppliers dans le fichier PartSuppliers.cs met à jour le champ Fournisseurs de l’élément de liste nouvellement créé.
public void UpdateSuppliers(int id, IEnumerable<string> supplierNames)
{
var item = list.GetItemById(id);
clientContext.Load(item);
clientContext.ExecuteQuery();
string commaSeparatedList = String.Join(",", supplierNames);
item["Suppliers"] = commaSeparatedList;
item.Update();
clientContext.ExecuteQuery();
}
Si le flux de travail est approuvé, la valeur du champ isApproved de l’élément de liste devient true.
Associer un flux de travail au site web hôte
L’exemple Workflow.AssociateToHostWeb vous montre comment déployer un flux de travail sur le site web hôte et l’associer à une liste sur le site web hôte à l’aide d’outils dans Visual Studio. Les instructions de cet exemple vous montrent comment créer un flux de travail dans Visual Studio, le déployer sur le site web hôte et l’associer à une liste sur le site web hôte.
L’exemple contient un flux de travail simple qui peut être associé à n’importe quelle liste. Les instructions de déploiement de ce flux de travail vous montrent comment contourner les limitations actuelles des outils de flux de travail Visual Studio en empaquetant le complément, en l’ouvrant et en modifiant un fichier de configuration, puis en le réempaquetant manuellement avant de le déployer sur le site web hôte.
Lorsque vous ouvrez ce projet dans Visual Studio, vous voyez qu’il s’agit d’un flux de travail simple et générique conçu pour fonctionner avec n’importe quelle liste SharePoint. Outre la liste des tâches du flux de travail, elle ne déploie aucune liste à laquelle elle peut être associée.
Remarque
Vous ne pouvez pas effectuer la tâche indiquée dans cet exemple à l’aide de Visual Studio 2013. Cet exemple fournit une solution de contournement utile. Si les Visual Studio Tools sont mis à jour à l’avenir, vous n’aurez peut-être pas besoin d’utiliser cette solution de contournement.
Déployer un flux de travail sur le site web hôte
Ouvrez le menu contextuel (clic droit) du projet de complément Workflow.AssociateToHostWeb dans l’Explorateur de projets, puis choisissez Publier. Vous verrez une fenêtre qui contient un bouton Empaqueter l’application.
Lorsque vous choisissez Empaqueter l’application, Visual Studio crée un fichier Workflow.AssociateToHostWeb.app dans le
bin\Debug\app.publish\1.0.0.0répertoire de votre solution. Ce fichier .app est un type de fichier .zip.Extrayez le contenu du fichier en remplaçant d’abord l’extension de fichier par .zip.
Dans le répertoire que vous avez extrait, recherchez et ouvrez le fichier XML nommé WorkflowManifest.xml. Le fichier est vide.
Ajoutez le fragment XML suivant au fichier, puis enregistrez le fichier.
<SPIntegratedWorkflow xmlns="http://schemas.microsoft.com/sharepoint/2014/app/integratedworkflow"> <IntegratedApp>true</IntegratedApp> </SPIntegratedWorkflow>Sélectionnez tous les fichiers dans le dossier extrait, puis ouvrez le menu contextuel (par clic droit) pour les fichiers, puis sélectionnez Envoyer à>Dossier compressé.
Dans le fichier zip que vous venez de créer, remplacez l’extension de fichier par .app. Vous devez maintenant disposer d’un nouveau package Workflow.AssociateToHostWeb.app qui contient le fichier WorkflowManifest.xml mis à jour.
Ajoutez le complément à votre catalogue d’applications.
Installez le complément sur votre site hôte.
Accédez à une liste sur votre site hôte et sélectionnez l’option de modification Liste en haut à gauche de la page. Le menu déroulant Paramètres du flux de travail s’affiche.
Sélectionnez Ajouter un flux de travail dans le menu déroulant.
Vous voyez maintenant une option de sélection comme illustrée dans la figure suivante. Sélectionnez le complément Workflow.AssociateToHostWeb dans la liste des options disponibles.
Vous avez maintenant déployé le flux de travail sur le site web hôte et l’avez associé à une liste sur le site web hôte. Vous pouvez déclencher un flux de travail manuellement ou le mettre à jour dans Visual Studio afin qu’il soit déclenché d’autres manières.