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

20 мин

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

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

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

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

Создание учетной записи Azure Cosmos DB

Примечание.

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

Создание учетной записи базы данных

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

В меню ресурсов на портале Azure или на странице Главная выберите Создать ресурс. Откроется панель Создание ресурса.
В меню Создание ресурса выберите Базы данных, а затем найдите и выберите Azure Cosmos DB. Откроется панель "Какой API лучше всего подходит для рабочей нагрузки".
В параметре Azure Cosmos DB для NoSQL выберите "Создать ", чтобы создать триггер Cosmos DB и входные и выходные привязки. Откроется панель "Создание учетной записи Azure Cosmos DB — Azure Cosmos DB для NoSQL".

На вкладке Основные сведения введите указанные ниже значения для каждого параметра.

Параметр	значение	Описание
Сведения о проекте
Отток подписок	Подписка Concierge	Подписка Azure, которая поддерживает работу с ресурсами в песочнице.
Группа ресурсов	В раскрывающемся списке выберите [имя группы ресурсов песочницы]	Группа ресурсов для песочницы.
Сведения об экземпляре
Имя учетной записи	`globally unique name`	Введите уникальное, но понятное имя для учетной записи Azure Cosmos DB; к указанному имени добавляется `documents.azure.com`. `3 - 50 lowercase characters, numbers, or hyphens (-)`.
Расположение	`region`	Выберите ближайший к вам регион.

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

Затем мы добавим контейнер и добавим базу данных в учетную запись Azure Cosmos DB.

Добавление контейнера

В Azure Cosmos DB контейнер используется для хранения различных создаваемых пользователем сущностей, также называемых элементами. Мы создадим контейнер с именем "Закладки".

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

В меню учетной записи Azure Cosmos DB выберите Обозреватель данных. Появится панель Обозреватель данных для вашей учетной записи Cosmos DB.
Выберите поле Создать контейнер. Откроется панель Создание контейнера. Чтобы увидеть его, может потребоваться прокрутить страницу.

Введите указанные ниже значения для каждого параметра.

Параметр	значение	Описание
Идентификатор базы данных	Выберите "Создать" и введите func-io-learn-db для идентификатора базы данных	Имена баз данных могут содержать от 1 до 255 символов и не могут содержаться `/, \\, #, ?`или конечный пробел. Здесь можно ввести любое значение, но в этом модуле мы будем использовать название func-io-learn-db.
Максимальное число единиц запроса в базе данных в секунду	4000	Установите для пропускной способности по умолчанию значение в 4000 единиц запроса в секунду (ЕЗ/с). Для сокращения задержки позже можно будет увеличить производительность.
Идентификатор контейнера	Закладки	Для идентификаторов контейнеров предусмотрены те же требования к символам, что и для имен баз данных. В этом модуле мы будем использовать контейнер Закладки.
Ключ раздела	/id	Ключ раздела указывает, как документы в коллекциях Azure Cosmos DB распределяются по логическим разделам данных. Мы используем параметр ключа секции в качестве удобства здесь, так как мы не обеспокоены производительностью базы данных в этом модуле. Дополнительные сведения о стратегиях ключей раздела Azure Cosmos DB см. в модулях Azure Cosmos DB Microsoft Learn.

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

Прокрутите до конца панели и нажмите ОК. Создание базы данных и контейнера может занять несколько минут.

По завершении обозреватель данных отображает func-io-learn-db в DATA в API NOSQL.
Выберите func-io-learn-db, чтобы развернуть ее. Обратите внимание, что база данных func-io-learn-db содержит несколько дочерних элементов, включая "Масштаб" и "Закладки".
Разверните контейнер закладок. Обратите внимание, что несколько дочерних элементов уже предварительно заполняют его.

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

Добавление тестовых данных

Предположим, что вам необходимо добавить данные в контейнер Закладки. Используйте Обозреватель данных для хранения URL-адреса и идентификатора для каждого элемента.

Разверните базу данных func-io-learn-db и контейнер Закладки, а затем выберите пункт Элементы. Откроется вкладка Элементы.
В командной строке выберите Создать элемент.
Замените код нового элемента по умолчанию следующим кодом JSON.
```
{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}
```

В командной строке выберите Сохранить.

Обратите внимание, что появится больше свойств, чем добавленные нами две строчки. Все они начинаются с подчеркивания (_rid, _self, _etag, _attachments, _ts). Эти свойства, описанные в следующей таблице, создаются системой для управления элементами, добавляемыми в контейнер.

Свойство	Description
`_rid`	Идентификатор ресурса — это уникальный идентификатор, который также является иерархическим для стека ресурсов в модели ресурсов. Идентификатор используется внутренне для размещения и навигации ресурса элемента.
`_self`	Это уникальный адресуемый URI для ресурса.
`_etag`	Необходимо для управления оптимистичной блокировкой.
`_attachments`	Адресуемый путь к ресурсу вложений.
`_ts`	Метка времени последнего обновления этого ресурса.

Давайте добавим еще несколько элементов в контейнер Закладки. В командной строке выберите Создать элемент. Создайте еще четыре элемента со следующим содержимым. Добавьте элементы, выбрав новый элемент, а затем нажмите кнопку "Сохранить " после копирования и вставки каждого нового элемента. Обратите внимание, что каждый элемент добавляется в список элементов.
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
После ввода данных закладки контейнер должен выглядеть следующим образом.

В вашем контейнере Закладки находится пять элементов. В этом сценарии, если запрос поступает с идентификатором id=docs, он ищет этот идентификатор в контейнере закладок и возвращает URL-адрес https://learn.microsoft.com/azure. Давайте создадим функцию Azure, выполняющую поиск значений в вашем контейнере "Закладки".

Создание функции

Перейдите в приложение-функцию, созданное в предыдущем уроке. В меню ресурсов выберите Главная, и в разделе Последние ресурсы вы увидите свое приложение-функцию (Тип определен как Приложение-функция). Выберите приложение-функцию. Откроется панель Приложение-функция.
На вкладке "Функции" на странице "Обзор" должна быть одна функция HttpTrigger1.
Давайте создадим другую функцию. Выберите " Создать" на вкладке "Функции ". Откроется область создания функций , в которой перечислены шаблоны для поддерживаемых триггеров.
В разделе "Выбор шаблона" выберите триггер HTTP, а затем нажмите кнопку "Далее".
Примите все параметры по умолчанию и нажмите кнопку "Создать ", чтобы создать функцию.

Откроется панель "Обзор" для функции HttpTrigger2.

Проверка функции

Вы можете проверить ход выполнения до сих пор, проверив новую функцию.

На панели команд выберите Получить URL-адрес функции. Откроется диалоговое окно Получение URL-адреса функции.
Выберите значение по умолчанию (ключ функции) в раскрывающемся списке, а затем щелкните значок "Копировать в буфер обмена" и нажмите кнопку "ОК".
Вставьте скопированный URL-адрес функции в адресную строку новой вкладки браузера. Добавьте значение &name=<your name> строки запроса в конец URL-адреса, заменив <your name> на выбранное вами имя, а затем нажмите ВВОД. Функция Azure должна вернуть персонализированный ответ в браузере.

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

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

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

В портал Azure в меню функции HttpTrigger2 в верхней части выберите "Интеграция". Откроется область интеграции для функции.

Вы использовали шаблон, который создал запрос триггера HTTP с выходной привязкой HTTP. Давайте добавим входную привязку Azure Cosmos DB.
В поле "Триггер и входные данные" выберите "Добавить входные данные". Появится панель Создание входных данных.
В раскрывающемся списке "Тип привязки" выберите Azure Cosmos DB.
В разделе Сведения об Azure Cosmos DB под параметром Подключение учетной записи Cosmos DB щелкните ссылку Создать. Откроется диалоговое окно Новое подключение Cosmos DB.

Если появится сообщение с запросом на установку расширения Microsoft.Azure.WebJobs.Extensions.CosmosDB, выберите Установить и дождитесь завершения установки.
По умолчанию Azure распознает созданную ранее учетную запись Azure Cosmos DB. Нажмите ОК для настройки подключения к вашей базе данных. Выполнена настройка нового подключения к учетной записи базы данных. Оно появится в поле Подключение к учетной записи Cosmos DB.

Нам нужно выполнить поиск закладки с конкретным идентификатором, поэтому мы привяжем полученный в строке запроса идентификатор к привязке.

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

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

Чтобы показать, почему мы используем эти параметры, выполним поиск закладки с определенным идентификатором. Для этого мы привязали идентификатор документа, который функция получает в строке запроса, к входной привязке. Это называется выражением привязки. Функция активируется HTTP-запросом, который в строке запроса указывает идентификатор для поиска. Так как идентификаторы уникальны в нашей коллекции, привязка возвращает либо 0 (не найдено), либо 1 (найденные) документы.

Чтобы сохранить эту конфигурацию входной привязки, нажмите кнопку "Добавить".

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

Теперь, когда ваша привязка определена, ее можно использовать в функции. Чтобы реализовать созданную привязку, необходимо внести два изменения:

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

Изменение кода реализации JavaScript в функции

В меню Функция вашей функции HttpTrigger2 выберите Код и тестирование. Для функции HttpTrigger2 отобразится панель Код и тестирование.

Замените весь код в файле index.js следующим кодом.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

В командной строке выберите Сохранить. Выберите журналы файловой системы в раскрывающемся списке в верхнем центре области журналов (где по умолчанию отображаются журналы App Insights). Появится панель Журналы с отображением Connected!.

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

Входящий HTTP-запрос запускает функцию, а параметр запроса id передается во входную привязку Azure Cosmos DB.
Если база данных находит документ, соответствующий этому идентификатору, bookmark параметр задается в расположенном документе.

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

Изменение кода реализации JSON в функции

Выберите function.json из раскрывающегося списка в <functionapp> \ HttpTrigger2 \ пути.

Замените весь код в файле function.json следующим кодом. Обязательно замените your-database имя учетной записи Azure Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}",
    }
  ]
}

В командной строке выберите Сохранить.

Изменение кода реализации PowerShell для функции

В меню Функция вашей функции HttpTrigger2 выберите Код и тестирование. Появится панель Код и тестирование для функции HttpTrigger2 с отображением файла run.ps1.

Замените весь код в файле run.ps1 следующим кодом.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

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

В командной строке выберите Сохранить. Выберите журналы файловой системы в раскрывающемся списке в верхнем центре области журналов (где по умолчанию отображаются журналы App Insights). Появится панель Журналы с отображением Connected!.

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

Входящий HTTP-запрос запускает функцию, а параметр запроса id передается во входную привязку Azure Cosmos DB.
Если база данных находит документ, соответствующий этому идентификатору, bookmark параметр задается в расположенном документе.

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

Изменение кода реализации JSON в функции

Выберите function.json из раскрывающегося списка в <functionapp> \ HttpTrigger2 \ пути.

Измените значения для id и partitionKey, чтобы они принимали параметр {id}. Код function. json должен выглядеть следующим образом, где your-database заменяется именем базы данных Cosmos DB.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

В командной строке выберите Сохранить.

Попробуйте

Должна отобразиться панель Код и тестирование для функции HttpTrigger2.
На панели команд выберите Получить URL-адрес функции. Откроется диалоговое окно Получение URL-адреса функции.
В раскрывающемся списке "Ключ" выберите значение по умолчанию в разделе "Ключ функции", а затем щелкните значок "Копировать в буфер обмена" в конце URL-адреса.
Вставьте скопированный ключ функции в адресную строку новой вкладки браузера и добавьте значение &id=docs строки запроса в конец URL-адреса. Полученный URL-адрес должен иметь примерно следующий вид.

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
Чтобы выполнить запрос, нажмите клавишу Ввод. Возвращенный функцией ответ должен быть аналогичен примеру, приведенному ниже.
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
Замените &id=docs на &id=missing, нажмите Enter и просмотрите ответ. Мы определили пять закладок и создали информативное сообщение об ошибке на случай, если запрошенная закладка не существует.

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

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

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

Создание учетной записи Azure Cosmos DB

Создание учетной записи базы данных

Добавление контейнера

Добавление тестовых данных

Создание функции

Проверка функции

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

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

Изменение кода реализации JavaScript в функции

Изменение кода реализации JSON в функции

Изменение кода реализации PowerShell для функции

Изменение кода реализации JSON в функции

Попробуйте

Обратная связь