Учебник. Начало работы с функциями Azure

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

Цели

  • Создание и отладка локальных функций Azure
  • Интеграция с веб и ресурсами хранилища Azure
  • Управление ходом рабочего процесса, в который входит несколько функций Azure

Требования

  • Visual Studio для Mac 7.5 или более поздней версии.
  • Подписка Azure (доступна бесплатно по адресу https://azure.com/free).

Упражнение 1. Создание проекта функций Azure

  1. Запустите Visual Studio для Mac.

  2. Выберите Файл > Новое решение.

  3. В категории Облако > Общие выберите шаблон Функции Azure. Вы будете использовать C# для создания библиотеки классов .NET, в которой размещаются функции Azure. Нажмите кнопку Далее.

    Выбор шаблона функций Azure

  4. Задайте имя проекта AzureFunctionsLab и нажмите Создать.

    именование и создание проекта функций azure

  5. Разверните узлы в окне решения. Шаблон проекта по умолчанию включает ссылки NuGet на различные пакеты AzureWebJobs, а также на пакет Newtonsoft.Json.

    Также существует три файла: — host.json для описания глобальных параметров конфигурации для узла. — local.settings.json для настройки параметров службы. — Шаблон проекта также создает HttpTrigger по умолчанию. В целях этого руководства удалите файл HttpTrigger.cs из проекта.

    Откройте файл local.settings.json. По умолчанию в нем имеется два параметра пустой строки подключения.

    окно решения с файлом local.settings.json

Упражнение 2. Создание учетной записи службы хранилища Azure

  1. Войдите в учетную запись Azure по адресу https://portal.azure.com.

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

    раздел "избранное" на портале Azure с элементом "учетная запись хранения"

  3. Нажмите Добавить, чтобы создать новую учетную запись хранения:

    Кнопка для добавления новой учетной записи хранения

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

    сведения о новой учетной записи хранения

  5. Нажмите кнопку Создать. Создание учетной записи хранения может занять несколько минут. Вы получите уведомление об успешном создании.

    уведомления об успехе развертывания

  6. Нажмите на кнопку Перейти к ресурсу в уведомлении.

  7. Выберите вкладку Ключи доступа.

    настройка ключа доступа

  8. Скопируйте первую строку подключения. Эта строка позже используется для интеграции хранилища Azure с функциями Azure.

    сведения для ключа 1

  9. Вернитесь в Visual Studio для Mac и вставьте полную строку подключения как параметр AzureWebJobsStorage в файле local.settings.json. Теперь можно ссылаться на имя параметра в атрибутах для функций, которым требуется доступ к его ресурсам.

    локальный файл параметров с введенным ключом подключения

Пример 3. Создание и отладка функции Azure

  1. Теперь вы готовы приступить к добавлению кода. При работе с библиотекой классов .NET функции Azure добавляются как статические методы. В окне решения щелкните правой кнопкой мыши узел проекта AzureFunctions и выберите Добавить > Добавить функцию.

    пункт "Добавить функцию"

  2. В диалоговом окне "Новые функции Azure" выберите шаблон универсального веб-перехватчика. Укажите для параметра Имя значение Добавить и нажмите кнопку ОК для создания функции:

    диалоговое окно создания функции azure

  3. В начале нового файла добавьте следующие директивы using:

    using Microsoft.Azure.WebJobs.Extensions.Http;
    using System.Web;
    using Microsoft.WindowsAzure.Storage.Table;
    
  4. Удалите существующий метод Run и добавьте в класс следующий метод в качестве функции Azure:

    [FunctionName("Add")]
    public static int Run(
    [HttpTrigger(AuthorizationLevel.Function, "get", Route = null)]
    HttpRequestMessage req,
    TraceWriter log)
    {
        int x = 1;
        int y = 2;
    
        return x + y;
    }
    
  5. Давайте подробно рассмотрим определение метода.

    Прежде всего вы увидите атрибут FunctionName, который помечает этот метод как функцию Azure. Этот атрибут определяет открытое имя функции. Имя атрибута не должно соответствовать имени фактического метода.

    Новый метод Run с выделенным атрибутом FunctionName

  6. Затем метод помечается как метод public static, который является обязательным. Вы заметите, что возвращается значение int. Если не указано иначе с помощью атрибутов метода, все непустые возвращаемые значения функции Azure возвращаются клиенту в виде текста. По умолчанию они возвращаются как XML, но позднее мы рассмотрим, как изменить формат на JSON.

    Новый метод run с выделенным методом инициализации

  7. Первый параметр помечается атрибутом HttpTrigger, который указывает, что этот метод вызывается HTTP-запросом. Атрибут также указывает уровень авторизации данного метода и поддерживаемые им команды (только GET в данном случае). По желанию вы можете определить параметр Route, который переопределяет путь к методу и предлагает способ автоматического извлечения переменных из пути. Поскольку в данном случае Route имеет значение NULL, будет использоваться путь к этому методу по умолчанию — /api/Add.

    Новый метод run с выделенным параметром

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

    Новый метод run с выделенным TraceWriter

  9. Установите точку останова в строке return этого метода, нажав на поле строки:

    Точка останова в строке return

  10. Скомпилируйте и запустите проект в сеансе отладки, нажав F5 или выбрав Запустить > Начать отладку. Или нажмите на кнопку Запуск. Все варианты выполняют одну задачу. Далее в инструкциях будет упоминаться клавиша F5, но вы можете использовать наиболее удобный метод.

    Компиляция и запуск проекта

  11. При запуске проекта будет автоматически открыто приложение терминала.

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

    Выходные данные функции Azure в терминале

  13. В нижней части сообщения о запуске узел функций Azure выводит URL-адреса API триггеров HTTP. Там должен быть только один адрес. Скопируйте его и вставьте в новой вкладке браузера.

    URL-адрес API функций Azure

  14. Сразу должна сработать точка останова. Веб-запрос был направлен в функцию и теперь готов для отладки. Наведите указатель мыши на переменную x для просмотра ее значения.

    Срабатывание точки останова

  15. Удалите точку останова, используя тот же метод, который вы применяли для ее добавления (щелкните на поле или выберите строку и нажмите клавишу F9).

  16. Чтобы продолжить выполнение, нажмите клавишу F5.

  17. В браузере будут отображаться результаты метода в формате XML. Как и ожидалось, жестко закодированная операция сложения выдает достоверную сумму. Если в Safari вы видите только 3, перейдите в меню Safari > Параметры > Дополнительно, поставьте флажок Показывать меню "Разработка" в строке меню и перезагрузите страницу.

  18. В Visual Studio для Mac нажмите кнопку Остановить, чтобы завершить сеанс отладки. Чтобы применить изменения, перезапустите (остановите и снова запустите) сеанс отладки.

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

  19. В методе Run замените определения x и y следующим кодом. Этот код извлекает значения из строки запроса URL-адреса, чтобы операция сложения выполнялась динамически в зависимости от предоставленных параметров.

    var query = HttpUtility.ParseQueryString(req.RequestUri.Query);
    
    int x = int.Parse(query["x"]);
    
    int y = int.Parse(query["y"]);
    
    return x + y;
    
  20. Запустите приложение.

  21. Вернитесь в окно браузера и добавьте строку /?x=2&y=3 в URL-адрес. Теперь URL-адрес должен выглядеть следующим образом: http://localhost:7071/api/Add?x=2&y=3. Перейдите по новому URL-адресу.

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

  23. Остановите сеанс отладки.

Упражнение 4. Работа с function.json

  1. В предыдущем упражнении говорилось, что в Visual Studio для Mac создается функциональная обязанность для функции Azure, определенной в библиотеке. Дело в том, что функции Azure не используют атрибуты метода в среде выполнения, но используют соглашение для файловой системы во время компиляции для настройки времени и способа предоставления функций Azure. В окне решения щелкните правой кнопкой мыши узел проекта и выберите Отобразить в средстве поиска.

    Пункт меню "Отобразить в средстве поиска"

  2. Перейдите к файловой системе до пункта bin/Debug/netstandard2.0. Найдите папку с именем Add. Эта папка была создана по атрибуту имени функции в коде C#. Разверните папку Add. Там находится один файл function.json. Этот файл используется средой выполнения для размещения и управления функцией Azure. Для других языковых моделей без поддержки среды компиляции (например, скрипт C# или JavaScript) эти папки необходимо создать вручную. Для разработчиков C# они создаются автоматически из метаданных атрибута при сборке. Щелкните правой кнопкой мыши файл function.json и откройте его в Visual Studio.

    function.json в каталоге файлов

  3. Учитывая уже выполненные шаги в этом руководстве, вы имеете общее представление об атрибутах C#. Так что этот файл JSON должен быть вам знаком. Но следует обсудить еще несколько аспектов, о которых мы не говорили ранее. Например, для каждого элемента привязки binding необходимо задать направление direction. Очевидно, что in означает входной параметр, а out — это либо возвращаемое значение (через $return), либо параметр out для метода. В сборке также необходимо указать scriptFile (относительно этого конечного расположения) и метод entryPoint (открытый и статический). В следующих шагах мы добавим пользовательский путь к функции с помощью этой модели, поэтому скопируйте содержимое этого файла в буфер обмена.

    файл function.json открыт в visual studio для mac

  4. В окне решения щелкните правой кнопкой мыши узел проекта AzureFunctionsLab и выберите Добавить > Новая папка. Назовите папку Adder. В соответствии с соглашением по умолчанию имя этой папки будет определять путь к API, например api/Adder.

    пункт "новая папка"

  5. Щелкните правой кнопкой мыши папку Adder и выберите Добавить > Новый файл.

    пункт "новый файл"

  6. Выберите категорию Веб и шаблон Пустой файл JSON. Задайте Имя function и нажмите Создать.

    пункт "пустой файл json"

  7. Вставьте содержимое из другого файла function.json (из шага 3), чтобы заменить содержимое по умолчанию только что созданного файла.

  8. Удалите следующие строки в верхней части файла json:

    "configurationSource":"attributes",
    "generatedBy":"Microsoft.NET.Sdk.Functions-1.0.13",
    
  9. В конце первой привязки (после строки "name": "req" ) добавьте следующие свойства. Не забудьте поставить запятую в предыдущей строке. Это свойство переопределяет маршрут по умолчанию. Теперь он извлечет параметры int из пути и поместит их в параметры метода с именами x и y.

    "direction": "in",
    "route": "Adder/{x:int?}/{y:int?}"
    
  10. Добавьте другую привязку под первой. Эта привязка обрабатывает возвращаемое значение функции. Не забудьте поставить запятую в предыдущей строке:

    {
    "name": "$return",
    "type": "http",
    "direction": "out"
    }
    
  11. Обновите свойство entryPoint в нижней части файла, чтобы использовать метод Add2, как показано ниже. Это показывает, что путь api/Adder... можно сопоставить с соответствующим методом с любым именем (в данном случае — Add2).

    "entryPoint": "<project-name>.<function-class-name>.Add2"
    
  12. Окончательный файл function.json должен выглядеть следующим образом:

    {
    "bindings": [
        {
        "type": "httpTrigger",
        "methods": [
            "get"
        ],
        "authLevel": "function",
        "direction": "in",
        "name": "req",
        "route": "Adder/{x:int?}/{y:int?}"
        },
        {
        "name": "$return",
        "type": "http",
        "direction": "out"
        }
    ],
    "disabled": false,
    "scriptFile": "../bin/AzureFunctionsProject.dll",
    "entryPoint": "AzureFunctionsProject.Add.Add2"
    }
    
  13. Чтобы все это работало, необходимо сделать последний шаг — дать Visual Studio для Mac указание копировать этот файл в тот же относительный путь в выходном каталоге при каждом изменении. Выберите файл, откройте вкладку свойств на правой панели и для пункта Копировать в выходной каталог выберите Копировать более позднюю версию:

    Параметры свойств для JSON-файла

  14. В Add.cs замените метод Run (включая атрибут) следующим методом для выполнения ожидаемой функции. Это очень похоже на метод Run, только он не использует атрибуты и имеет явные параметры для x и y.

    public static int Add2(
        HttpRequestMessage req,
        int x,
        int y,
        TraceWriter log)
    {
        return x + y;
    }
    
  15. Нажмите клавишу F5 для сборки и запуска проекта.

  16. После завершения сборки и запуска платформы вы увидите, что существует второй маршрут для запросов, сопоставляемый с добавленным методом:

    URL-адрес для функций HTTP

  17. Вернитесь в окно браузера и перейдите к http://localhost:7071/api/Adder/3/5 .

  18. На этот раз метод сработает снова, извлекая параметры из пути и рассчитывая сумму.

  19. Вернитесь в Visual Studio для Mac и завершите сеанс отладки.

Упражнение 5. Работа с таблицами хранилища Azure

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

  1. Добавьте следующий класс в Add.cs. Он добавляется в пространство имен, но за пределами существующего класса.

    public class TableRow : TableEntity
    {
        public int X { get; set; }
        public int Y { get; set; }
        public int Sum { get; set; }
    }
    
  2. Добавьте в класс Add следующий код, чтобы ввести еще одну функцию. Этот код уникален, поскольку не содержит HTTP-ответов. Последняя строка возвращает новый объект TableRow, содержащий ключевую информацию, которую будет легко извлечь позже (PartitionKey и RowKey), а также его параметры и сумму. Код в этом методе также использует TraceWriter, чтобы вам было проще понимать, когда функция выполняется.

    [FunctionName("Process")]
    [return: Table("Results")]
    public static TableRow Process(
        [HttpTrigger(AuthorizationLevel.Function, "get",
            Route = "Process/{x:int}/{y:int}")]
        HttpRequestMessage req,
        int x,
        int y,
        TraceWriter log)
    {
        log.Info($"Processing {x} + {y}");
    
        return new TableRow()
        {
            PartitionKey = "sums",
            RowKey = $"{x}_{y}",
            X = x,
            Y = y,
            Sum = x + y
        };
    }
    
  3. Нажмите клавишу F5 для сборки и запуска проекта.

  4. На вкладке браузера перейдите по адресу http://localhost:7071/api/Process/4/6 . В результате в очередь встанет еще одно сообщение, и в конечном итоге в таблицу будет добавлена еще одна строка.

  5. Вернитесь в терминал и следите за входящим запросом для 4 + 6.

    Выходные данные терминала с запросом на сложение

  6. Вернитесь в браузер и обновите запрос, указав тот же URL-адрес. На этот раз вы увидите ошибку после метода Process. Дело в том, что код пытается добавить строку в таблицу хранилища таблиц Azure с помощью комбинации ключа раздела и строки, которая уже существует.

    System.Private.CoreLib: Exception while executing function: Process. Microsoft.Azure.WebJobs.Host: Error while handling parameter $return after function returned:. Microsoft.Azure.WebJobs.Host: The specified entity already exists.
    
  7. Остановите сеанс отладки.

  8. Чтобы устранить ошибку, добавьте следующий параметр в определение метода непосредственно перед параметром TraceWriter. Этот параметр дает платформе функций Azure указание попытаться извлечь TableRow из таблицы Results в PartitionKey, который мы использовали для хранения результатов. Настоящее волшебство происходит тогда, когда вы заметите, что RowKey создается динамически на основе других параметров x и y для этого же метода. Если эта строка уже существует, tableRow получит ее при запуске метода без дополнительных усилий со стороны разработчика. Если строка не существует, она будет иметь значение NULL. Благодаря этой возможности разработчики могут сосредоточиться на важной бизнес-логике, а не на инфраструктуре.

    [Table("Results", "sums", "{x}_{y}")]
    TableRow tableRow,
    
  9. Добавьте следующий код в начало метода. Если tableRow не имеет значение NULL, значит, у нас уже есть результаты для запрашиваемой операции и мы можем получить их незамедлительно. В противном случае функция будет работать, как раньше. Возможно, это не самый надежный способ получить данные, но он иллюстрирует тот факт, что вы можете выполнять невероятно сложные операции на нескольких масштабируемых уровнях с небольшим фрагментом кода.

    if (tableRow != null)
    {
        log.Info($"{x} + {y} already exists");
        return null;
    }
    
  10. Нажмите клавишу F5 для сборки и запуска проекта.

  11. На вкладке браузера измените URL-адрес: http://localhost:7071/api/Process/4/6 . Поскольку для этой записи уже существует строка в таблице, она будет возвращена немедленно и без ошибок. Раз выходных данных HTTP нет, результат можно увидеть в терминале.

    Выходные данные в терминале с уже существующей строкой таблицы

  12. Обновите URL-адрес, указав еще не протестированную комбинацию, например http://localhost:7071/api/Process/5/7 . Обратите внимание на сообщение в терминале, которое указывает, что строка таблицы не найдена (как и ожидалось).

    Выходные данные в терминале с новым процессом

  13. Вернитесь в Visual Studio для Mac и завершите сеанс отладки.

Сводка

В этом руководстве вы узнали, как приступить к созданию функций Azure с помощью Visual Studio для Mac.