Упражнение. Запись данных с помощью выходных привязок

15 мин

В предыдущем упражнении мы реализовали сценарий поиска закладок в базе данных Azure Cosmos DB. Мы настроили входную привязку для чтения данных из коллекции закладок. Но можно сделать намного больше. Давайте добавим в наш сценарий операцию записи. Рассмотрите следующую блок-схему:

Decision flow diagram illustrating the process of adding a bookmark in Azure Cosmos DB back-end and returning a response.

В этом сценарии мы получаем запросы на добавление закладок в коллекцию. Запросы передают требуемый ключ или идентификатор вместе с URL-адресом закладки. Как видно в блок-схеме, мы отвечаем на ошибку, если ключ уже существует в нашей внутренней части.

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

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

Что может быть хорошим примером этой разгрузки работы в нашем сценарии закладок? Что, если отправить новую закладку в службу создания QR-кода? Эта служба, в свою очередь, создаст QR-код для URL-адреса, сохранит образ в хранилище BLOB-объектов и добавит адрес образа QR-кода в запись в нашей коллекции закладок. Вызов службы для создания QR-изображения занимает много времени. Поэтому вместо того, чтобы ждать результата, мы передаем задачу функции и позволяем ей выполнять эту задачу асинхронно.

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

Важно!

Для этого упражнения требуется знание ресурсов песочницы и ресурсов, созданных в предыдущих уроках, в частности, базы данных Azure Cosmos DB, закладок и входных привязок. Если вы не закончили упражнения в предыдущих уроках, вы не сможете выполнить это упражнение.

Создание функции, активируемой по HTTP

На портале Azure перейдите к созданному приложению-функции, выбрав его имя в пути строки навигации в верхней части страницы функции HttpTrigger2.
На вкладке "Функции " на странице "Обзор " должны быть созданы функции триггера HTTP.
Выберите " Создать" на вкладке "Функции ". Откроется панель "Создать функцию ".
На панели Выберите шаблон выберите Триггер HTTP, а затем — Создать. Откроется панель "Обзор" для функции HttpTrigger3.

Добавление входной привязки Azure Cosmos DB

Давайте добавим еще одну входную привязку Azure Cosmos DB.

В меню функции HttpTrigger3 выберите Интеграция. Появится панель Интеграция.
В поле Входные данные выберите Добавить входные данные. Появится панель Создание входных данных.
Из раскрывающегося списка Тип привязки выберите Azure Cosmos DB.
Параметр подключения учетной записи Cosmos DB должен быть предварительно заполнен подключением, созданным в предыдущем упражнении.

Если подключение не отображается, создайте новое, выполнив приведенные ниже действия.
1. В разделе Сведения об Azure Cosmos DB под параметром Подключение учетной записи Cosmos DB щелкните ссылку Создать.
2. Когда откроется диалоговое окно Создание подключения к Cosmos DB, нажмите кнопку ОК, чтобы создать подключение. Создано новое подключение к учетной записи Cosmos DB.

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

Параметр	значение	Description
Имя параметра документа	`bookmark`	Имя, используемое для идентификации этой привязки в коде.
Имя базы данных	`func-io-learn-db`	База данных, которая будет использоваться. Это значение представляет собой имя базы данных, заданное ранее в этом уроке.
Имя коллекции	`Bookmarks`	Имя коллекции, из которой считываются данные. Этот параметр определен ранее в этом уроке.
Код документа	`{id}`	Добавьте `{id}`, чтобы использовать правильное выражение привязки и принять параметр, передаваемый в строке запроса.
Ключ секции	`{id}`	Опять же, добавьте `{id}`, чтобы использовать правильное выражение привязки и принять параметр, передаваемый в строке запроса.
SQL-запрос (необязательный)	Не указывайте	Мы извлекаем только один элемент за раз на основе идентификатора. Таким образом, фильтрация с использованием параметра документа подходит больше, чем использование SQL-запроса в этом экземпляре. Мы можем написать SQL-запрос для возврата одной записи (`SELECT * from b where b.ID = /id`). Этот запрос возвратит элемент, но он будет возвращен в коллекции элементов. Нашему коду пришлось бы манипулировать коллекцией без необходимости. Для получения нескольких документов используйте SQL-запрос.

Как и в случае входной привязки, созданной в предыдущем упражнении, мы хотим найти закладку с указанным идентификатором, поэтому мы привязали Идентификатор документа, который получает наша функция в строке запроса, к привязке, которая называется выражением привязки. Триггер функции — это HTTP-запрос, использующий строку запроса для указания идентификатора для поиска. Привязка возвращает 0 (не найдено) или 1 (найденные) документы.

Нажмите ОК, чтобы сохранить конфигурацию входной привязки.

Теперь у нас есть входная привязка Azure Cosmos DB. Давайте добавим выходную привязку, чтобы записывать новые данные в коллекцию.

Добавление выходной привязки Azure Cosmos DB

На панели Интеграция функции HttpTrigger3 в поле Выходные данные выберите Добавить выходные данные. Откроется панель Создание выходных данных.
В раскрывающемся списке Тип привязки выберите Azure Cosmos DB.
Параметр подключения учетной записи Cosmos DB должен быть предварительно заполнен с помощью созданного ранее подключения. Если это не так, разверните раскрывающийся список и выберите подключение, определенное для входной привязки HttpTrigger3.

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

Параметр	значение	Description
Имя параметра документа	`newbookmark`	Имя, используемое для идентификации этой привязки в коде. Этот параметр используется для внесения новой записи закладки.
Имя базы данных	`func-io-learn-db`	База данных, которая будет использоваться. Это значение представляет собой имя базы данных, заданное ранее в этом уроке.
Имя коллекции	`Bookmarks`	Имя коллекции, из которой считываются данные. Это значение — имя контейнера, которое мы определили ранее в занятии.
Ключ секции	`/id`	Добавьте ключ раздела, который мы определили ранее при создании контейнера Закладки Azure Cosmos DB. Введенный здесь ключ (указанный в конфигурации входной привязки `<key>`) должен соответствовать ключу в контейнере.

Нажмите ОК, чтобы сохранить конфигурацию выходной привязки.

Теперь у нас есть привязка для чтения из коллекции и привязка для записи в нее.

Добавление выходной привязки хранилища очередей Azure

Хранилище очередей Azure — это служба хранения сообщений, к которой можно получить доступ практически из любой точки мира. Одно сообщение может быть размером до 64 КБ, а очередь может содержать миллионы сообщений до заполнения емкости учетной записи хранения, в которой оно определено. На схеме ниже в общих чертах показано, как в нашем сценарии будет использоваться очередь.

Illustration showing a storage queue with a function pushing and another function popping messages.

Здесь демонстрируется, как функция с именем add-bookmark добавляет сообщения в очередь, а функция gen-qr-code извлекает сообщения из той же очереди и обрабатывает запрос. Так как мы записываем сообщения в очередь из закладки надстроек, мы добавим в решение новую выходную привязку.

Давайте создадим привязку через портал.

В области Интеграция функции в поле Выходные данные выберите Добавить выходные данные. Откроется панель Создание выходных данных.
В раскрывающемся списке Тип привязки выберите Хранилище очередей Azure.

Если появится сообщение, рекомендующее установить расширение Microsoft.Azure.WebJobs.Extensions.Storage, выберите Установить и дождитесь завершения установки.

Затем мы настроим подключение учетной записи хранения, где размещена наша очередь.

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

Для параметра Подключение к учетной записи хранения будет указано имя подключения.

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

Завершите настройку параметров на панели Создание выходных данных, заменив следующие значения новыми:

Параметр	Старое значение	Новое значение	Description
Имя параметра сообщения	outputQueueItem	newmessage	Свойство привязки, используемое в коде.
Имя очереди	outqueue	bookmarks-post-process	Имя очереди, в которой мы размещаем закладки, чтобы другая функция могли их обрабатывать дальше.

Нажмите ОК, чтобы сохранить конфигурацию выходных данных для Хранилища очередей Azure.

Обновление реализации функции

Теперь все привязки настроены. Пришло время использовать их в нашей функции.

Чтобы открыть файл index.js в редакторе кода, выберите функцию HttpTrigger3.
В меню навигации в разделе Разработчик выберите Код и тестирование. Для функции отобразится панель Код и тестирование.

Замените весь код в файле index.js кодом из приведенного ниже фрагмента и нажмите кнопку Сохранить в командной строке.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Давайте разберемся, что делает этот код.

Так как эта функция изменяет наши данные, мы ожидаем HTTP-запрос типа POST и данные закладки в качестве части текста запроса.
Наша входная привязка Azure Cosmos DB пытается получить документ (или закладку) с помощью полученного id. В случае обнаружения записи будет задан объект bookmark. Условие if(bookmark) проверяет, была ли обнаружена запись.
Ее добавление в базу данных является простым делом: задайте параметр привязки context.bindings.newbookmark для новой записи закладки, которую мы создали в виде строки JSON.
Публиковать сообщения в очереди просто: задайте параметр context.bindings.newmessage.

Примечание.

Единственная задача, которую мы выполнили, — создание привязки очереди. Мы еще никогда не создавали очередь явным образом. Вы наблюдаете все многообразие возможностей привязок! Как видно из следующего уведомления, если очередь не существует, она автоматически создается.

Screenshot showing message that the queue will be auto-created. .

Вот и все. Итак, теперь давайте посмотрим на проделанную работу в действии в следующем разделе.

Чтобы открыть файл run.ps1 в редакторе кода, выберите функцию HttpTrigger3 из строки навигации в верхней части панели.
В меню "Функция" в разделе Разработчик выберите Код и тестирование. Откроется панель Код и тестирование для функции HttpTrigger3 с отображением содержимого по умолчанию run.ps1.

Замените содержимое файла следующим кодом.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

В командной строке выберите Сохранить. Устанавливается соединение, и открывается сеанс для файла журнала.

Давайте разберемся, что делает этот код.

Так как эта функция изменяет наши данные, мы ожидаем HTTP-запрос типа POST и данные закладки в качестве части текста запроса.
Наша входная привязка Azure Cosmos DB пытается извлечь документ или закладку с помощью id в запросе. В случае обнаружения записи будет задан объект bookmark. Условие if ($bookmark) проверяет, была ли обнаружена запись.
Для добавления в базу данных достаточно вызвать Push-OutputBinding с именем выходной привязки Cosmos DB (newbookmark) и значением объекта $newBookmark.
Для отправки сообщения в очередь достаточно вызвать Push-OutputBinding с именем выходной привязки очереди (newmessage) и значением объекта $newBookmark.

Примечание.

Screenshot showing UI tool tip that the queue will be auto-created.

Вот и все. Итак, теперь давайте посмотрим на проделанную работу в действии в следующем разделе.

Попробуйте

Теперь, когда у нас есть несколько выходных привязок, тестирование немного усложняется. В предыдущих уроках мы были содержимым для тестирования, отправив HTTP-запрос со строкой запроса, но мы хотим выполнить http-пост на этот раз. Необходимо также проверить, отправляются ли сообщения в очередь.

В командной строке на панели Код и тестирование для функции HttpTrigger3, активируемой HTTP, выберите пункт Тест/запуск. Появится новая панель с открытой вкладкой ввода, как показано на изображении ниже:
Убедитесь, что в раскрывающемся списке Метод HTTP выбрано значение POST.
Замените содержимое текста запроса следующим объектом JSON:
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```
Выберите Выполнить.
На панели Журналы отображается программный ход выполнения. По завершении убедитесь, что на вкладке Выходные данные в параметре Содержимое HTTP-ответа отображается текст "Закладка уже существует".

Элемент закладки был добавлен при выполнении упражнения Чтение данных с помощью входных привязок. Ответ подтверждает, что JavaScript var bookmark = context.bindings.bookmark работает правильно, и что код PowerShell устанавливает то же подключение.
Давайте разместите вторую закладку в базе данных. Перейдите на вкладку Входные данные.
Замените содержимое текста запроса следующим объектом JSON:
```
{
    "id": "github",
    "url": "https://www.github.com"
}
```
Выберите Выполнить.
Убедитесь, что на вкладке Вывод отображается текст "Закладка добавлена" в содержимом HTTP-ответа, как показано на следующем снимке экрана.

Поздравляем! Ваша функция работает, как задумано. Но что делать с операцией очереди, которую мы добавили в код? Давайте посмотрим, записалось ли что-нибудь в очередь.

Проверка записи сообщения в очередь

Очереди хранилища очередей Azure размещаются в учетной записи хранения. При создании выходной привязки вы настроили учетную запись хранения.

В поле поиска на портале Azure введите учетные записи хранения и в списке результатов выберите Учетные записи хранения. Откроется область Учетные записи хранения.
Выберите учетную запись хранения, которую вы использовали для настройки выходной привязки newmessage.
В меню Учетная запись хранения в поле Хранилище данных выберите Очереди, чтобы отобразить список очередей, размещенных в этой учетной записи хранения. Убедитесь, что в списке есть очередь bookmarks-post-process, как показано на следующем снимке экрана.
Выберите Последующая обработка закладок, чтобы получить список сообщений, находящихся в очереди. Если все сделано правильно, очередь включает сообщение, отправленное при добавлении закладки в базу данных. Это должно выглядеть примерно так.

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

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

Продолжить