Поделиться через

Начало работы с веб-заданиями Azure для сайтов Office 365

  • Статья

В Office 365, если у вас работает и используется служба SharePoint Online, необходимо пересмотреть методику выполнения заданий таймера, которая использовалась в традиционных решениях для ферм.

При традиционной разработке в SharePoint задания таймера используются для выполнения запланированных задач в фермах SharePoint. Распространенная методика — разработка собственных заданий таймера для непрерывного или итерационного выполнения задач в среде. В случае Office 365 и SharePoint Online у вас нет возможности развертывать собственные решения для ферм, где обычно хранятся традиционные задания таймера. Вам необходимо другое средство планирования задач. И тут на помощь приходят веб-задания Azure.

В этой статье описываются основные понятия, связанные с началом разработки пользовательских заданий для сайтов Office 365, и создание веб-задания Azure в качестве запланированного задания для установки SharePoint в Office 365 (или локальной версии Office).

Создание веб-задания с помощью Visual Studio

Чтобы создать веб-задание, достаточно создать консольное приложение и убедиться, что к проекту добавлены необходимые сборки. В этом примере мы используем Visual Studio.

Этап 1. Создание консольного приложения

Для начала создайте новый проект и убедитесь, что выбран шаблон Консольное приложение. Кроме того, обязательно выберите .NET Framework 4.5 или более позднюю версию этой платформы.

Диалоговое окно “Создание проекта” с настройками для создания консольного приложения с использованием .NET Framework 4.5

Этап 2. Добавление специальных сборок SharePoint из NuGet

Если вы используете Visual Studio, диалоговое окно диспетчера пакетов NuGet может немного отличаться от более ранних версий Visual Studio, но концепция остается прежней.

  1. Выберите Средства>Диспетчер пакетов NuGet>Управление пакетами NuGet для решения и найдите пункт Приложение для SharePoint.

  2. Установите пакет под названием AppForSharePointOnlineWebToolkit.

  3. Набор средств устанавливает необходимые вспомогательные классы для работы с клиентской объектной моделью SharePoint (CSOM).

Диалоговое окно Диспетчер пакетов NuGet с поисковым запросом App for SharePoint. Приложение для веб-набора средств SharePoint выделено, и кнопка Установить готова к нажатию.


Убедитесь, что пакет NuGet сработал, проверив наличие следующих двух классов в проекте консольного приложения:

  • SharePointContext.cs
  • TokenHelper.cs

В обозревателе решений отображаются последние добавленные классы, контекст SharePoint и вспомогательный объект токена.

Этап 3. Добавление необходимого кода для выполнения задания на сайте Office 365

К этому моменту вы создали консольное приложение и добавили необходимые сборки, которые дадут вам возможность легко взаимодействовать с SharePoint. Далее необходимо использовать эти вспомогательные классы для выполнения команд в среде SharePoint при помощи консольного приложения.

Примечание.

В готовом примере используется подход с учетной записью и паролем (аналогично учетной записи службы). Варианты проверки подлинности рассматриваются далее в этой статье.

Подключение вызовов к семейству веб-сайтов SharePoint Online

Приведенный ниже код иллюстрирует подключение вызова к сайту после добавления вспомогательных классов из пакета 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;
      }
   }

В примере приложения вы можете увидеть, что добавлены два вспомогательных метода для получения имени и пароля учетной записи из файла app.config. Они подробнее рассматриваются в разделе, посвященном проверке подлинности, далее в этой статье.

Что касается метода Main, его достаточно для подключения компонентов к порталу. Прежде чем подробнее изучать управление SharePoint с помощью кода, обсудим варианты проверки подлинности.

Варианты проверки подлинности

Доступны два варианта проверки подлинности. В следующих разделах описываются эти распространенные подходы и отличия между ними.

Вариант 1. Использование учетной записи службы (имени пользователя и пароля)

Этот подход довольно прост и дает возможность просто ввести имя пользователя и пароль для клиента Office 365, а затем использовать, к примеру, CSOM для выполнения кода на сайтах. Так мы поступили и в предыдущем примере кода.

Создание учетной записи службы в Office 365

Чтобы это работало, следует создать специальную учетную запись, которая выступает в качестве учетной записи службы для конкретного приложения или универсальной учетной записи приложений-служб, которую смогут использовать все ваши задания и службы.

Для этой демонстрации мы создали учетную запись под названием SP WebJob.

На информационной панели отображается новая учетная запись SP WebJob.

При настройке учетной записи необходимо изменить ее разрешения в соответствии с потребностями задания.

Хранение учетных данных в файле app.config

В файле app.config своего проекта вы можете указать учетные данные, чтобы их можно было легко получить из исполняемого файла. Файл 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>

В файле the app.config есть два параметра:

  • SPOAccount
  • SPOPassword

Если вернуться к первому фрагменту кода, можно увидеть, что эти параметры взяты из файла app.config. Помните, что при этом имя и пароль учетной записи хранятся в виде обычного текста в файле app.config. Если вы выберете этот подход, вам необходимо решить, как и где следует хранить и защищать пароли для проекта.

Выполнение задания в указанной учетной записи

После запуска приложение работает с использованием учетной записи, указанной в конструкторе SharePointOnlineCredentials().

В журнале автоматического перевода показаны четыре перевода текста, относящиеся к веб-заданию SP.

В предыдущем примере веб-задание выполняет действия с пользовательским списком на одном из сайтов, размещенных в семействе веб-сайтов SharePoint Online.

По этой причине учетная запись службы предоставляет неплохие возможности отслеживания изменений на портале. Именно поэтому важно выбрать подходящее имя для учетной записи. Все будут знать, что изменения были автоматически внесены службой, просто посмотрев на метаданные об изменении или создании.

Вариант 2. Использование OAuth и включение маркеров проверки подлинности в запросы во избежание указания имени и пароля учетной записи

Кирк Эванс в записи блога Создание надстройки SharePoint в качестве задания таймера объясняет, как использовать и передавать маркеры доступа, чтобы избежать настройки имени пользователя и пароля, если вы не хотите хранить пароли и учетные данные в приложении.

Расширение кода с помощью CSOM

На этом этапе у вас есть консольное приложение, которое может проводить проверку подлинности и выполнять запросы к сайтам Office 365. Пока что в коде нет ничего необычного, поэтому рассмотрим пример получения информации из списка под названием Automatic Translations. Логика кода определяет, есть ли в списке непереведенные пункты. Затем совершается вызов службы перевода, чтобы перевести текст на нужный язык.

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);
   }
}

Класс TranslatorHelper — это вспомогательный класс, который вызывает специальный API перевода, но сейчас мы не будем его подробно рассматривать, поскольку это не относится к тематике данной статьи.

Примечание.

Как видно из кода, это лишь демонстрация, которая однозначно не подходит для использования в рабочей среде. Переработайте и измените код в соответствии со своими стандартами и принципами безопасности. Однако все дополнения к Console.WriteLine необходимы для удобной проверки выполнения заданий на портале Azure. Далее в этой статье мы подробнее рассмотрим ведение журнала и мониторинг.

Публикация веб-задания в Azure

Когда вы разработали веб-задание и готовы развернуть его в среде Azure (на веб-сайте Azure), вам доступны два варианта, описанные в следующих разделах.

Вариант 1. Отправка ZIP-файла с двоичными файлами веб-заданий на портал Azure

Используя портал Azure, где хранятся все ваши ценные ресурсы Azure, вы можете отправить ZIP-файл, содержащий выходные данные сборки Visual Studio. Это удобно для компиляции и доставки кода другому сотруднику, который выполнит развертывание.

Создание ZIP-файла

Просто возьмите все выходные данные из сборки Visual Studio (как правило, они находятся в папке bin/Debug или bin/Release).

В проводнике Windows откроется папка bin/Debug.


Сожмите их, чтобы получить удобный ZIP-файл для веб-задания.

Готовый ZIP-файл откроется в проводнике Windows.

Поиск веб-сайта, на котором следует развернуть задание

  1. Теперь, когда у вас есть пакет, нужно перейти на портал Azure и выполнить вход.

  2. После этого необходимо создать новый веб-сайт или использовать существующий. На этом веб-сайте размещается веб-задание.

  3. При прокрутке вниз в области параметров веб-сайта вы найдете файлwebJobs под заголовком Operations.

    Откроется портал Azure автора со стрелкой, указывающей на веб-задания.

  4. Щелкните область, на которую указывает стрелка.

Отправка веб-задания

  1. Отправьте веб-задание, нажав значок [+ Добавить].

    Откроется портал веб-заданий Azure со стрелкой, указывающей на кнопку “Добавить”.

  2. Выберите имя и способ выполнения задания, а затем отправьте сам ZIP-файл.

    Откроется диалоговое окно

    Важно!

    На данный момент в поле Как выполнить доступны только варианты По запросу и Непрерывно, но вскоре будет добавлен вариант По расписанию, который нам на самом деле нужен. В разделе “Публикация непосредственно в Azure” можно назначить задание из Visual Studio.

  3. Теперь вы можете запустить веб-задание с портала Azure.

    Портал Azure веб-заданий отображается вместе со списком новых заданий. Над заданием появится контекстное меню с параметрами Выполнить и Удалить.

Вариант 2. Публикация непосредственно в Azure из Visual Studio

С помощью инструментов Visual Studio можно быстро опубликовать любые изменения непосредственно в размещенной службе. Вы также можете запланировать выполнение задания именно так, как вам нужно, непосредственно в диалоговых окнах Visual Studio.

Публикация веб-задания из Visual Studio

Примечание.

Эти диалоговые окна могут немного отличаться, если вы используете более раннюю версию Visual Studio. Кроме того, если вы делаете это впервые, может появиться диалоговое окно входа в учетную запись Azure.

Щелкните проект правой кнопкой мыши и выберите пункт Опубликовать как веб-задание Azure.

Откроется контекстное меню обозревателя решений с выделенным вариантом “Веб-задание Azure”.

Добавление веб-задания Azure

Откроется новое диалоговое окно, где можно настроить задание. Так как вам нужно повторяющееся задание, которое должно выполняться по расписанию (например, по одному разу каждую ночь), вы можете настроить расписание непосредственно в диалоговых окнах.

Откроется диалоговое окно

  1. Убедитесь, что имя веб-задания подходит для использования в Интернете.

  2. Выберите режим выполнения веб-задания. Если вы хотите, чтобы оно выполнялось каждый день в определенное время, выберите вариант Выполнять по расписанию.

  3. Каким должно быть задание: повторяющимся или одноразовым? Поскольку нам нужно имитировать задание таймера, оно должно быть повторяющимся и будет выполняться каждую ночь без даты окончания.

  4. При желании вы можете запланировать повторение с точностью до минуты.

  5. Укажите дату и время начала, а также часовой пояс.

  6. Нажмите кнопку OK. Visual Studio отправляет следующее сообщение: Установка пакета NuGet для публикации веб-заданий.

    Откроется диалоговое окно “Установка пакета NuGet для публикации веб-заданий” с вертушкой и текстом “Установка пакета NuGet для публикации веб-заданий”.

    На самом деле к проекту добавляется новый файл под названием webjob-publish-settings.json, содержащий конфигурацию задания.

    Файл выглядит так:

     {
 "$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"
 }

    Примечание.

    Пока что этот файл нам не нужен, поскольку мы уже составили расписание с помощью диалоговых окон.

Выбор цели публикации или развертывания

Следующий этап диалогового окна — выбор цели публикации или развертывания веб-задания. Вы можете импортировать профиль публикации или выбрать веб-сайты Azure, чтобы пройти проверку подлинности и выбрать один из существующих сайтов.

На портале Azure выберите Импорт и укажите файл профиля публикации, скачанный с веб-сайта Azure.

Откроется диалоговое окно “Публикация веб-сайта” с открытой вкладкой “Подключение”.

Публикация

После этого остается только нажать кнопку Опубликовать. В диалоговом окне Действие веб-публикации будет показан ход выполнения развертывания веб-задания.

Откроется диалоговое окно “Действие веб-публикации”.


После этого веб-задание должно появиться на портале Azure.

В списке веб-заданий на портале Azure появится пункт Zimmergren-O365-WebJobSample с состоянием “Выполнено 2 мин назад”.

Теперь для веб-задания будет отображаться состояние Выполнено. Если бы возникли необработанные исключения или другие неполадки, то отображалось бы состояние Сбой/ошибка.

В поле Тип по-прежнему отображается значение По запросу, но на самом деле задание теперь выполняется каждые четыре часа.

Мониторинг задания и просмотр журналов

Если вы выполнили все предыдущие этапе, теперь у вас есть задание, работающее в качестве запланированной задачи в облаке, выполняя действия на сайтах Office 365.

Если вам нужно проверить, когда задание выполнялось в последний раз, каким был результат каждого выполнения задания или что произошло во время его выполнения, вы можете перейти по ссылке в разделе Журналы из обзора веб-заданий.

Диалоговое окно веб-заданий со стрелкой, указывающей на ссылку “Журналы”.


В нем представлен обзор всех выполнений выбранных заданий, включая состояние /outcome.

Сведения о веб-заданиях, в том числе их последних выполнениях.


Перейдя по выделенной ссылке, вы можете изучить журналы определенного выполнения задания и убедиться, что все в порядке. Скорее всего, это будет более актуально, если задание действительно вызвало ошибку и вам нужно было изучить ее причину либо исход задания был неправильным или не соответствовал ожиданиям.

Вы также можете увидеть, что операторы Console.WriteLine, которые мы использовали в консольном приложении для этой демонстрации, теперь отображаются в журнале выполнения задания.

Подробные сведения о веб-задании со строками в файле журнала.

См. также