Introdução ao Azure WebJobs para sites do Office 365
Com o Office 365, se você estiver executando e utilizando o serviço do Microsoft Office SharePoint Online, deverá repensar a maneira como você executa o que costumava ser trabalhos de timer em suas soluções de farm tradicionais.
No desenvolvimento tradicional do Microsoft Office SharePoint Online, você usa trabalhos de timer para executar tarefas agendadas em farms do Microsoft Office SharePoint Online. Uma técnica comumente usada é desenvolver trabalhos de timer personalizados para executar determinadas tarefas de forma contínua ou iterativa em seu ambiente. Com o Office 365 e o Microsoft Office SharePoint Online, você não se dá ao luxo de implantar suas soluções de farm, que é onde seus trabalhos tradicionais de timer normalmente estão. Em vez disso, você precisa encontrar outra maneira de agendar suas tarefas, o que nos leva ao Azure WebJobs.
Este artigo descreve os conceitos básicos para começar a criar trabalhos personalizados para sites do Office 365 e como você pode criar um Azure Webjob para atuar como um trabalho agendado para sua instalação do Office 365 (ou local) do Microsoft Office SharePoint Online.
Criar o WebJob usando Visual Studio
Para criar um novo WebJob, tudo o que você precisa fazer é criar um novo aplicativo de console e garantir que você adicione os assemblies necessários ao projeto. Neste exemplo, usamos Visual Studio.
Etapa 1: Criar seu aplicativo de console
Comece criando um novo projeto e certifique-se de escolher o modelo Aplicativo de Console. Além disso, certifique-se de escolher .NET Framework 4.5 ou posterior.
Etapa 2: Adicionar os assemblies específicos do Microsoft Office SharePoint Online do NuGet
Se você estiver usando o Visual Studio, a caixa de diálogo do gerenciador de pacotes NuGet pode parecer um pouco diferente das versões anteriores do Visual Studio, mas o conceito é o mesmo.
Vá para Ferramentas>Gerenciador de Pacotes NuGet>Gerenciar Pacotes NuGet para Solução e pesquise por Aplicativo para Microsoft Office SharePoint Online.
Instale o pacote chamado AppForSharePointOnlineWebToolkit.
O kit de ferramentas instala as classes auxiliares necessárias para trabalhar com o modelo de objeto do lado do cliente do Microsoft Office SharePoint Online (CSOM).
Verifique se o pacote NuGet funcionou checando se as duas novas classes a seguir aparecem no projeto do aplicativo de console:
- SharePointContext.cs
- TokenHelper.cs
Etapa 3: Adicionar o código necessário para executar o trabalho em seu site do Office 365
Neste ponto, você criou seu aplicativo de console e adicionou os assemblies necessários que permitirão que você se comunique facilmente com o Microsoft Office SharePoint Online. As próximas etapas são usar essas classes auxiliares para executar comandos em seu ambiente do Microsoft Office SharePoint Online usando o aplicativo de console.
Observação
No exemplo concluído, você usará uma abordagem de conta + senha (como uma conta de serviço). As opções de autenticação serão discutidas mais adiante neste artigo.
Conectar as chamadas ao conjunto de sites do Microsoft Office SharePoint Online
O código a seguir demonstra como conectar a chamada ao seu site agora que você adicionou as classes auxiliares do pacote NuGet.
static void Main(string[] args)
{
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
// Use default authentication mode
context.AuthenticationMode = ClientAuthenticationMode.Default;
// Specify the credentials for the account that will execute the request
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
// TODO: Add your logic here!
}
}
private static SecureString GetSPOSecureStringPassword()
{
try
{
Console.WriteLine(" - > Entered GetSPOSecureStringPassword()");
var secureString = new SecureString();
foreach (char c in ConfigurationManager.AppSettings["SPOPassword"])
{
secureString.AppendChar(c);
}
Console.WriteLine(" - > Constructed the secure password");
return secureString;
}
catch
{
throw;
}
}
private static string GetSPOAccountName()
{
try
{
Console.WriteLine(" - > Entered GetSPOAccountName()");
return ConfigurationManager.AppSettings["SPOAccount"];
}
catch
{
throw;
}
}
Você pode ver no aplicativo de exemplo que dois métodos auxiliares foram adicionados para buscar o nome da conta e a senha da conta do arquivo app.config. Eles são explicados na seção de autenticação posteriormente neste artigo.
Quanto ao método Principal, isso é tudo o que você precisa para conectar itens ao portal. Antes de se aprofundar em como você pode manipular o Microsoft Office SharePoint Online com base em seu código, vamos discutir as opções de autenticação.
Considerar opções de autenticação
Você tem duas opções de autenticação. As seções a seguir descrevem essas abordagens normalmente usadas e como elas diferem.
Opção 1: Usar uma conta de serviço (nome de usuário + senha)
Essa abordagem é bastante simples e permite que você simplesmente insira uma conta e senha para seu locatário do Office 365 e, em seguida, use, por exemplo, o CSOM para executar código em seus sites. Isso é o que foi feito no código de exemplo anterior também.
Criar uma nova conta de serviço no Office 365
Para que isso funcione, você deve criar uma conta específica que atue como uma conta de serviço para esse aplicativo específico ou uma conta de aplicativo de serviço genérico que todos os seus trabalhos e serviços possam usar.
Para fins desta demonstração, criamos uma nova conta chamada SP WebJob.
Dependendo das permissões que o trabalho deve ter, você deve editar as permissões da conta ao configurá-la.
Armazenar credenciais em seu app.config
No arquivo app.config do projeto, você pode especificar as credenciais para que elas sejam facilmente buscadas no executável de código. Esta é a aparência do app.config:
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
</startup>
<appSettings>
<add key="SPOAccount" value="spwebjob@redacted.onmicrosoft.com"/>
<add key="SPOPassword" value="redacted"/>
</appSettings>
</configuration>
Você pode ver as duas configurações no arquivo app.config:
- SPOAccount
- SPOPassword
Se você examinar o primeiro trecho de código, essas configurações serão do arquivo app.config. Lembre-se de que isso significa armazenar o nome da conta e a senha em texto não criptografado em seu app.config. Você precisa tomar uma decisão em seus próprios projetos sobre como e onde armazenar e proteger suas senhas caso escolha essa abordagem.
Executar o trabalho na conta especificada
Depois que o aplicativo é executado, ele é executado usando a conta especificada no construtor SharePointOnlineCredentials().
No exemplo anterior, o WebJob está executando ações em uma lista personalizada em um dos sites hospedados em um conjunto de sites do Microsoft Office SharePoint Online.
Por isso, você pode obter uma boa rastreabilidade das alterações no portal executadas por sua conta de serviço. É por isso que é importante nomear a conta de maneira inteligente; todos saberão que as modificações foram feitas automaticamente pelo seu serviço simplesmente examinando os metadados modificados/criados.
Opção 2: usar OAuth e incluir tokens de autenticação em suas solicitações para evitar especificar a conta/senha
Em uma postagem de blog por Kirk Evans chamada Criando um Suplemento do SharePoint como um Trabalho de Timer, ele explica como você pode utilizar e passar tokens de acesso para evitar configurações de nome de usuário/senha, caso você não queira armazenar as senhas e credenciais em seu aplicativo.
Estender o código com CSOM
Neste ponto, você tem um aplicativo de console funcional que pode autenticar e executar solicitações para seus sites do Office 365. Ainda não foi feito nada sofisticado no código, portanto, aqui está um trecho de exemplo para extrair algumas informações de uma lista chamada Traduções Automáticas. A lógica de código determina se há itens na lista que não foram traduzidos. Em seguida, ele executará uma chamada para um serviço de tradução e traduzirá o texto para o idioma de saída desejado.
static void Main(string[] args)
{
try
{
Console.WriteLine("Initiating Main()");
using (ClientContext context = new ClientContext("https://redacted.sharepoint.com"))
{
Console.WriteLine("New ClientContext('https://redacted.sharepoint.com') opened. ");
context.AuthenticationMode = ClientAuthenticationMode.Default;
context.Credentials = new SharePointOnlineCredentials(GetSPOAccountName(), GetSPOSecureStringPassword());
Console.WriteLine("Authentication Mode and Credentials configured");
List translationlist = context.Web.Lists.GetByTitle("Automatic Translations");
context.Load(translationlist);
context.ExecuteQuery();
Console.WriteLine("TranslationList fetched, loaded and ExecuteQuery'ed");
if (translationlist != null && translationlist.ItemCount > 0)
{
Console.WriteLine("The list exist, let's do some magic");
CamlQuery camlQuery = new CamlQuery();
camlQuery.ViewXml =
@"<View>
<Query>
<Where><Eq><FieldRef Name='IsTranslated' /><Value Type='Boolean'>0</Value></Eq></Where>
</Query>
</View>";
ListItemCollection listItems = translationlist.GetItems(camlQuery);
context.Load(listItems);
context.ExecuteQuery();
Console.WriteLine("Query for listItems executed.");
foreach (ListItem item in listItems)
{
item["Output"] = TranslatorHelper.GetTranslation(item["Title"], item["Target Language"], item["Original Language"]);
item["IsTranslated"] = true;
item.Update();
}
context.ExecuteQuery();
Console.WriteLine("Updated all the list items you found. Carry on...");
}
}
}
catch (Exception ex)
{
Console.WriteLine("ERROR: " + ex.Message);
Console.WriteLine("ERROR: " + ex.Source);
Console.WriteLine("ERROR: " + ex.StackTrace);
Console.WriteLine("ERROR: " + ex.InnerException);
}
}
A classe TranslatorHelper é uma classe auxiliar que chama uma API de tradução personalizada, mas não será discutida em detalhes nesta postagem porque está fora do escopo deste artigo.
Observação
Como visto no código, essa é uma demonstração e definitivamente não é para uso em produção. Revise-o e ajuste-o de acordo com seus padrões de codificação e princípios de segurança. No entanto, todas as adições a console.WriteLine são adicionadas para que você examine a execução dos trabalhos facilmente do portal do Azure. Mais informações sobre registro em log e monitoramento são exibidas posteriormente neste artigo.
Publicar seu WebJob no Azure
Quando você tiver desenvolvido seu WebJob e estiver pronto para implantá-lo em seu ambiente do Azure (em um site do Azure), você terá duas opções principais, conforme descrito nas seções a seguir.
Opção 1: Carregar um arquivo zip com os binários do WebJob no portal do Azure
Usando o portal do Azure onde você mantém toda a sua maravilha no Azure, você pode carregar um arquivo zip que contém a saída do build do Visual Studio. Essa é uma maneira fácil de compilar e enviar seu código para outra pessoa que fará a implantação para você.
Criar o arquivo zip
Basta pegar todos os arquivos de saída do build do Visual Studio (normalmente na pasta bin/Debug ou bin/Release).
Compacte-os para que você obtenha um arquivo zip para seu WebJob.
Localizar um site em que o trabalho deve ser implantado
Agora que você tem seu pacote, a próxima etapa é ir para o seu portal do Azure e entrar.
A partir daí, você deve criar um novo site ou usar um existente. Este site é o host do seu WebJob.
Se você rolar para baixo no painel de configurações do seu site, encontrará um bloco chamado WebJobs no cabeçalho Operações.
Clique na área em que a seta está apontando.
Carregar seu WebJob
Carregue seu WebJob escolhendo o sinal [+ Adicionar].
Escolha um nome e como o trabalho deve ser executado e carregue o arquivo zip real.
Importante
A alternativa Como Executar atualmente só oferece Sob Demanda ou Contínuo, mas em breve haverá suporte para Agendado também, que é o que você realmente deseja. Na seção Publicando diretamente no Azure, você pode agendá-lo de dentro do Visual Studio.
Agora você pode executar seu WebJob do seu portal do Azure.
Opção 2: Publicar diretamente no Azure do Visual Studio
Você pode usar as ferramentas no Visual Studio para publicar rapidamente todas as alterações diretamente no serviço hospedado. Você também pode agendar o trabalho exatamente como deseja que ele seja executado diretamente das caixas de diálogo no Visual Studio.
Publicar o WebJob do Visual Studio
Observação
Essas caixas de diálogo podem ser um pouco diferentes se você estiver executando uma versão anterior do Visual Studio. Além disso, se você estiver fazendo isso pela primeira vez, poderá receber uma caixa de diálogo de entrada para entrar em sua conta do Azure.
Clique com o botão direito do mouse no projeto e escolha Publicar como WebJob do Azure.
Adicionar WebJob do Azure
Isso leva você a uma nova caixa de diálogo em que você pode configurar o trabalho. Como você deseja um trabalho recorrente que deve ser executado em um agendamento (como uma vez por noite), você pode configurar a agenda diretamente dos diálogos.
Verifique se o nome do WebJob é amigável para a Web.
Selecione o modo de execução do WebJob. Se você quiser que isso ocorra em uma hora específica todos os dias, escolha Executar em um Agendamento.
O trabalho deve ser um trabalho recorrente ou um trabalho único? Como você deseja simular um trabalho de timer, ele precisa ser recorrente e se ele será executado todas as noites, sem nenhuma data de término.
Você pode agendar a recorrência até cada minuto, se desejar.
Indique a data de início e hora, bem como o fuso horário.
Escolha OK. Visual Studio envia a seguinte mensagem: Instalando Pacote NuGet de Publicação do Webjobs.
Isso na verdade adiciona um novo arquivo chamado webjob-publish-settings.json ao seu projeto, que contém a configuração para o trabalho.
O arquivo tem esta aparência:
{ "$schema": "http://schemastore.org/schemas/json/webjob-publish-settings.json", "webJobName": "Zimmergren-O365-WebJobSample", "startTime": "2015-01-09T01:00:00+01:00", "endTime": null, "jobRecurrenceFrequency": "Day", "interval": 1, "runMode": "Scheduled" }Observação
Você não precisa desse arquivo no momento porque já projetou o agendamento usando as caixas de diálogo.
Selecionar destino de publicação/implantação
A próxima etapa na caixa de diálogo é indicar onde publicar/implantar seu WebJob. Você pode importar um perfil de publicação ou selecionar sites do Azure para autenticar e selecionar um de seus sites existentes.
No seu portal do Azure, escolha Importar e especifique o arquivo de perfil de publicação que você baixou do seu site do Azure.
Publicar
Com isso feito, tudo o que você precisa fazer é escolher Publicar. A caixa de diálogo Atividade de Publicação na Web exibe o progresso da implantação do WebJob.
Quando terminar, você deverá ver o WebJob em seu portal do Azure.
O status do WebJob agora é exibido como Concluído. Ele indicaria falha/erro se houvesse gerado exceções sem tratamento ou outro comportamento não íntegro.
Tipo ainda diz Sob Demanda, mas esse trabalho é executado uma vez a cada hora agora.
Monitorar o trabalho e revisar logs
Se você concluiu todas as etapas anteriores, agora tem um trabalho que funciona para você como uma tarefa agendada na nuvem, executando ações em seus sites do Office 365.
Se você quiser examinar quando o trabalho foi executado pela última vez, qual foi o resultado de cada execução do trabalho ou o que aconteceu durante a execução do trabalho, você pode escolher o link em Logs quando estiver na visão geral do WebJobs.
Isso fornece uma visão geral de todas as execuções dos trabalhos selecionados, incluindo o status/resultado.
Ao escolher o link realçado, você pode se aprofundar em uma execução específica para examinar os logs do trabalho e garantir que as coisas estejam corretas. Isso provavelmente será mais relevante se o trabalho realmente tiver causado um erro e você precisar investigar o que deu errado ou se o resultado do trabalho estiver incorreto ou não conforme o esperado.
Você também pode ver que as instruções Console.WriteLine que usamos no aplicativo de console para esta demonstração agora aparecem no log de execução do trabalho.
Confira também
- Postagem original no blog sobre Azure WebJobs por Tobias Zimmergren
- Desenvolver e implantar WebJobs usando Visual Studio – Serviço de Aplicativo do Azure
- Vídeo Trabalho de timer remoto simples que interage com o Microsoft Office SharePoint Online por Andrew Connell no Channel9
- Usar o Microsoft Azure WebJobs com o Office 365
- Estrutura do trabalho de temporizador remoto PnP