Chamar serviços Web a partir dos fluxos de trabalho do SharePoint
Você pode usar o modelo de Suplemento do SharePoint para criar e implantar fluxos de trabalho executados na web de suplemento ou no host da Web. Esses fluxos de trabalho podem interagir com as partes hospedadas remotamente de suplementos hospedados pelo provedor.
Os fluxos de trabalho também podem chamar os serviços Web remotos que contêm dados de negócios importantes de uma das seguintes maneiras:
Ao passar informações de consulta para a parte hospedada remotamente do suplemento. Em seguida, o aplicativo Web remoto chama o serviço Web e passa as informações de volta para o SharePoint.
Consultando o serviço Web usando o proxy Web do SharePoint. O fluxo de trabalho passa os resultados da consulta para a parte hospedada remotamente do suplemento, que então passa as informações para o SharePoint.
As informações recuperadas do serviço Web podem ser armazenadas em listas do SharePoint.
Este artigo descreve três exemplos de código que mostram como chamar os serviços Web a partir de fluxos de trabalho, conforme listado na tabela a seguir. Nos dois primeiros exemplos, as listas e os fluxos de trabalho são implantados na web de suplemento quando o suplemento é instalado. O último exemplo fornece o shell básico de um fluxo de trabalho e instruções sobre como implantá-lo no host da Web e associá-lo a uma lista no host da Web.
Tarefas de fluxo de trabalho e exemplos associados
| Tarefa | Exemplo |
|---|---|
| Chame serviços Web personalizados a partir de um fluxo de trabalho. | Workflow.CallCustomService |
| Chame um serviço Web personalizado a partir de um fluxo de trabalho e atualize o SharePoint usando o proxy Web do SharePoint. | Workflow.CallServiceUpdateSPViaProxy |
| Associe um fluxo de trabalho ao host da Web. | Workflow.AssociateToHostWeb |
Chamar serviços Web personalizados a partir de um fluxo de trabalho
O exemplo Workflow.CallCustomService mostra como criar um fluxo de trabalho que chama um serviço Web personalizado que atualiza os dados da lista do SharePoint. Ele também mostra como projetar um suplemento hospedado pelo provedor para que ele consulte um serviço Web usando o aplicativo Web hospedado remotamente que é implantado com o suplemento. Este exemplo é útil quando você quiser que todas as interações com o serviço Web sejam tratadas pela parte hospedada remotamente do suplemento hospedado pelo provedor.
O exemplo funciona iniciando um fluxo de trabalho a partir de um aplicativo Web remoto. Esse fluxo de trabalho passa as informações de consulta enviadas pelo usuário para o aplicativo Web remoto, que usa essas informações para construir uma consulta para o serviço Web Northwind OData. A consulta retorna os fornecedores de produtos de um determinado país/região. Depois de receber essas informações, o aplicativo Web remoto atualiza uma lista de fornecedores de produtos que o suplemento implantou na web de suplemento.
Observação
A página de exemplo Workflow.CallCustomService contém instruções para implantar esse suplemento. Você também poderá implantar e testar com a depuração F5 no Visual Studio se seguir as instruções da postagem no blog Depurando os fluxos de trabalho do SharePoint 2013 usando o Visual Studio 2013.
A página inicial do suplemento de exemplo Workflow.CallCustomService inclui um menu suspenso a partir do qual você pode selecionar um país/região para o qual deseja criar uma lista de fornecedores de produtos.
O botão Criar na tela chama um método Create no arquivo Controllers\PartSuppliersController.cs que cria uma nova entrada na lista de Fornecedores de peças na web de suplemento. O método Create chama o método Add definido no arquivo Services\PartSuppliersService.cs. A sequência é mostrada nos dois exemplos de código a seguir.
Método 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étodo Add
public int Add(string country)
{
var item = list.AddItem(new ListItemCreationInformation());
item["Country"] = country;
item.Update();
clientContext.ExecuteQuery();
return item.Id;
}
Depois de criar esse novo item de lista, o suplemento apresenta um botão Iniciar fluxo de trabalho que inicia o fluxo de trabalho de aprovação.
A escolha do botão Iniciar fluxo de trabalho aciona o método StartWorkflow definido no arquivo Controllers\PartSuppliersController.cs. Esse método empacota a URL da web de suplemento, a URL do serviço Web (do aplicativo Web hospedado remotamente, não do serviço Web Northwind) e os valores do token de contexto e os passa para o método StartWorkflow. O método PartSuppliersService precisa do token de contexto para interagir com o 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 });
}
O método StartWorkflow cria uma instância de fluxo de trabalho e passa os três valores (appWebUrl, webServiceUrl, contextToken) armazenados na variável do conteúdo para o fluxo de trabalho.
{
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();
}
Depois que o fluxo de trabalho é iniciado, ele faz uma solicitação POST HTTP para o aplicativo Web hospedado remotamente. Essa solicitação informa ao aplicativo Web para atualizar a lista de fornecedores com os fornecedores do país/região que o usuário acabou de adicionar. O arquivo Controllers\DataController.cs contém um método POST que recebe o conteúdo dessa solicitação.
public void Post([FromBody]string country)
{
var supplierNames = GetSupplierNames(country);
UpdateSuppliers(country, supplierNames);
}
O método GetSupplierNames (no arquivo Controllers\DataController.cs) constrói e executa uma consulta LINQ para o serviço Web Northwind OData para todos os fornecedores associados ao país/região selecionado.
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;
}
O método UpdateSuppliers atualiza o campo Fornecedores do item de lista recém-adicionado.
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);
}
}
Se você observar a modo Design do arquivo workflow.xaml no diretório Aprovar Fornecedores do projeto de suplemento, verá (escolhendo a guia Arguments na parte inferior esquerda do modo Design) que o fluxo de trabalho armazena os três valores na variável do conteúdo que é passada para ele como argumentos de fluxo de trabalho.
A atividade HttpSend ocorre antes da aprovação do fluxo de trabalho. Esta atividade envia a consulta POST para o aplicativo Web remoto que dispara a chamada para o serviço Web Northwind e, em seguida, para a atualização do item de lista (com a lista de fornecedores). Esta atividade é configurada para enviar a solicitação ao valor webServiceUrl que foi passado como um argumento de fluxo de trabalho.
A solicitação POST também passa o valor do país/região armazenado no item de lista em que o fluxo de trabalho está operando.
O fluxo de trabalho envia os valores appWebUrl e contextToken para o aplicativo Web por meio dos cabeçalhos de solicitação. Os cabeçalhos também definem os tipos de conteúdo para enviar e aceitar solicitações.
Se o fluxo de trabalho for aprovado, ele altera o valor do campo isApproved do item de lista para true.
Chamar um serviço Web personalizado a partir de um fluxo de trabalho e atualizar o SharePoint usando o proxy Web do SharePoint
O exemplo Workflow.CallServiceUpdateSPViaProxy mostra como criar um suplemento hospedado pelo provedor para consultar um serviço Web e, em seguida, passar essas informações para uma lista do SharePoint por meio do proxy Web do SharePoint.
O exemplo mostra uma tarefa que é útil quando você deseja encapsular todas as interações com um serviço Web para que sejam tratadas diretamente pelo fluxo de trabalho. O uso do proxy Web facilita a atualização da lógica do aplicativo Web remoto sem a necessidade de atualizar a instância de fluxo de trabalho. Se você não estiver usando o proxy e precisar atualizar a lógica no aplicativo Web, deverá remover as instâncias de fluxo de trabalho existentes e reimplantar o suplemento. Por esse motivo, recomendamos esse design quando precisar chamar um serviço Web remoto.
Observação
A página de exemplo Workflow.CallServiceUpdateSPViaProxy contém instruções para implantar esse suplemento. Você também pode implantar e testar o suplemento usando a depuração F5 no Visual Studio se seguir as instruções da postagem no blog Depurando os fluxos de trabalho do SharePoint 2013 usando o Visual Studio 2013.
O exemplo inicia um fluxo de trabalho a partir de um aplicativo Web remoto. Esse fluxo de trabalho passa as informações de consulta enviadas pelo usuário para o serviço Web Northwind OData. A consulta retorna os fornecedores de produtos de um determinado país/região. Depois de receber a resposta do serviço Web, o fluxo de trabalho passa as informações da resposta para o aplicativo Web remoto. Em seguida, o aplicativo Web remoto atualiza uma lista de fornecedores de produtos que o suplemento implantou na web de suplemento.
Ao iniciar o suplemento de exemplo Workflow.CallServiceUpdateSPViaProxy, a página inicial inclui um menu suspenso a partir do qual você pode selecionar um país/região para o qual deseja criar uma lista de fornecedores de produtos.
O botão Criar chama um método no arquivo Controllers\PartSuppliersController.cs que cria uma nova entrada na lista Fornecedores de peças na web de suplemento. O método Create nesse arquivo chama o método Add que é definido no arquivo Services\PartSuppliersService.cs. Ambos são mostrados nos dois exemplos de código a seguir.
Método 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étodo Add
public int Add(string country)
{
var item = list.AddItem(new ListItemCreationInformation());
item["Country"] = country;
item.Update();
clientContext.ExecuteQuery();
return item.Id;
}
Depois de criar esse novo item de lista, o suplemento apresenta um botão Iniciar fluxo de trabalho que inicia o fluxo de trabalho de aprovação.
A escolha do botão Iniciar fluxo de trabalho aciona o método StartWorkflow no arquivo Controllers\PartSuppliersController.cs. Esse método empacota a URL da web de suplemento e a URL do serviço Web (do aplicativo Web hospedado remotamente, não do serviço Web Northwind) e os passa para o método StartWorkflow no arquivo Services\PartSuppliersService.cs. O fluxo de trabalho se comunica com o aplicativo Web remoto por meio do proxy Web e o proxy Web adiciona o token de acesso em um cabeçalho de solicitação. É por isso que o fluxo de trabalho não passa um token de contexto para o método StartWorkflow neste exemplo. O código é mostrado no exemplo a seguir.
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 });
}
O método startWorkflow cria uma instância de fluxo de trabalho e passa os dois valores (appWebUrl e webServiceUrl) armazenados na variável do conteúdo para o fluxo de trabalho.
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();
}
Depois que o fluxo de trabalho é iniciado e antes de ser aprovado, ele faz uma consulta ao serviço Web Northwind para recuperar a lista de fornecedores do país/região que você selecionou. Ele faz isso usando uma atividade HTTPSend que envia uma consulta OData para este ponto de extremidade: "http://services.odata.org/V3/Northwind/Northwind.svc/Suppliers/?$filter=Country eq '" + country.Replace("'", "''") + "'&$select=CompanyName".
A atividade HttpSend deve ser configurada como uma solicitação GET com um cabeçalho Accept que especifica JSON sem metadados: application/json;odata=nometadata.
Se o usuário selecionou Canadá para o novo item de lista de fornecedores, por exemplo, a resposta formatada em JSON será conforme mostrado no exemplo a seguir.
{
value: [
{
CompanyName: "Ma Maison"
},
{
CompanyName: "Forêts d'érables"
}
]
}
Após o início do fluxo de trabalho, ele faz uma solicitação POST HTTP que contém a lista de fornecedores para o aplicativo Web hospedado remotamente por meio do proxy. Ele faz isso por meio de uma atividade HttpSend que consulta a URL do proxy Web: appWebUrl + "/_api/SP.WebProxy.invoke".
Em seguida, o fluxo de trabalho passa a lista de fornecedores que recebeu do serviço Northwind, criando e passando um conteúdo de serviço personalizado. As propriedades da atividade Criar conteúdo de serviço personalizado contêm a lista de fornecedores e a ID do país/região do fornecedor.
A atividade Criar conteúdo WebProxy constrói um conteúdo que passa os conteúdos desse conteúdo para a URL do proxy Web.
As propriedades de atividade de Conteúdo WebProxy especificam a URL da web de suplemento, o tipo e o comprimento do conteúdo da solicitação POST e o tipo de aceitação da solicitação por meio de cabeçalhos de solicitação.
Depois que o fluxo de trabalho tiver construído a carga e a solicitação, ele passa a solicitação para o proxy Web usando uma atividade HttpSend configurada como uma solicitação POST para a URL de proxy da Web. Os cabeçalhos de solicitação especificam OData no formato JSON nos cabeçalhos Content-Type e Accept.
O método Post no arquivo Controllers\DataController.cs aceita o conteúdo da solicitação que o fluxo de trabalho envia por meio do proxy Web. O método Post no exemplo anterior chamou um método para recuperar a lista de fornecedores da Northwind, bem como para atualizar a lista de fornecedores do SharePoint correspondente.
Como o fluxo de trabalho neste exemplo já consultou o serviço Northwind, esta versão do método precisa apenas atualizar a lista do SharePoint. Ele também passa a URL da web de suplemento e o token de acesso (que é passado pelo proxy Web) para o método UpdateSuppliers no arquivo Services\PartSuppliersService.cs, conforme mostrado no exemplo de código a seguir.
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));
}
}
O método UpdateSuppliers no arquivo PartSuppliers.cs atualiza o campo Fornecedores do item de lista recém-criado.
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();
}
Se o fluxo de trabalho for aprovado, ele altera o valor do campo isApproved do item de lista para true.
Associar um fluxo de trabalho ao host da Web
O exemplo Workflow.AssociateToHostWeb mostra como implantar um fluxo de trabalho ao host da Web e associá-lo a uma lista no host da Web usando ferramentas no Visual Studio. As instruções para esse exemplo mostram como criar um fluxo de trabalho no Visual Studio, implantá-lo no host da Web e associá-lo a uma lista no host da Web.
O exemplo contém um fluxo de trabalho simples que pode ser associado a qualquer lista. As instruções para implantar esse fluxo de trabalho mostram como contornar as limitações atuais das ferramentas de fluxo de trabalho do Visual Studio, empacotando o suplemento, abrindo-o e editando um arquivo de configuração e, em seguida, empacotando-o manualmente antes de implantá-lo no host da Web.
Ao abrir esse projeto no Visual Studio, você verá que é um fluxo de trabalho simples e genérico projetado para funcionar com qualquer lista do SharePoint. Além da lista de tarefas do fluxo de trabalho, ele não implanta nenhuma lista com a qual possa ser associado.
Observação
Não é possível executar a tarefa mostrada nesse exemplo usando o Visual Studio 2013. Esse exemplo fornece uma solução alternativa útil. Se as ferramentas do Visual Studio forem atualizadas no futuro, talvez você não precise usar essa solução alternativa.
Implantar um fluxo de trabalho no host da Web
Abra o menu de atalho (clique com o botão direito) do projeto de suplemento Workflow.AssociateToHostWeb no explorador de projetos e escolha Publicar. Você verá uma janela que contém um botão Empacotar o aplicativo.
Ao escolher Empacotar o aplicativo, o Visual Studio cria um arquivo Workflow.AssociateToHostWeb.app no
bin\Debug\app.publish\1.0.0.0diretório da solução. Este arquivo .app é um tipo de arquivo .zip.Extraia o conteúdo do arquivo alterando primeiro a extensão do arquivo para .zip.
No diretório que você extraiu, localize e abra o arquivo XML nomeado WorkflowManifest.xml. O arquivo está vazio.
Adicione o seguinte fragmento XML ao arquivo e salve o arquivo.
<SPIntegratedWorkflow xmlns="http://schemas.microsoft.com/sharepoint/2014/app/integratedworkflow"> <IntegratedApp>true</IntegratedApp> </SPIntegratedWorkflow>Selecione todos os arquivos extraído da pasta e, em seguida, abra o menu de atalho (clique com o botão direito) dos arquivos e selecione Enviar para>Pasta compactada (zipada).
No arquivo zip que você acabou de criar, altere a extensão do arquivo para .app. Agora você deve ter um novo pacote Workflow.AssociateToHostWeb.app que contém o arquivo WorkflowManifest.xml atualizado.
Adicione o suplemento ao seu Catálogo de Aplicativos.
Instale o suplemento no seu site host.
Vá para uma lista em seu site host e selecione a opção de edição de Lista no canto superior esquerdo da página. Você verá as Configurações de fluxo de trabalho no menu suspenso.
Selecione Adicionar um fluxo de trabalho no menu suspenso.
Agora você verá uma opção de seleção semelhante à imagem na figura a seguir. Selecione o suplemento Workflow.AssociateToHostWeb na lista de opções disponíveis.
Agora você implantou o fluxo de trabalho no host da Web e o associou a uma lista no host da Web. Você pode acionar um fluxo de trabalho manualmente ou pode atualizar o fluxo de trabalho no Visual Studio para que seja acionado de outras maneiras.