Интеграция функций OpenAI, коммуникации и организационных данных в бизнес-приложение
Уровень: промежуточный
В этом руководстве показано, как Azure OpenAI, Службы коммуникации Azure и Microsoft Graph Toolkit можно интегрировать в приложение Line of Business (LOB), чтобы повысить производительность пользователей, повысить удобство работы пользователей и перейти к следующему уровню бизнес-приложений. К ключевым функциям приложения относятся:
- ИИ: позволяет пользователям задавать вопросы на естественном языке и преобразовывать ответы на SQL, которые можно использовать для запроса базы данных, разрешать пользователям определять правила, которые можно использовать для автоматического создания сообщений электронной почты и SMS-сообщений, а также узнать, как естественный язык можно использовать для получения данных из собственных пользовательских источников данных. Azure OpenAI используется для этих функций.
- Обмен данными. Включение звонков по телефону в приложении клиентам и функциям электронной почты и SMS с помощью Служб коммуникации Azure.
- Организационные данные: вытягивание связанных данных организации, которые могут потребоваться пользователям (документы, чаты, сообщения электронной почты, события календаря), так как они работают с клиентами, чтобы избежать переключения контекста. Предоставление доступа к данным организации этого типа снижает потребность пользователя в Outlook, Teams, OneDrive, других пользовательских приложениях, телефоне и т. д., так как необходимые данные и функциональные возможности предоставляются непосредственно в приложении. Microsoft Graph и Microsoft Graph Toolkit используются для этой функции.
Приложение — это простое приложение для управления клиентами, которое позволяет пользователям управлять своими клиентами и связанными данными. Он состоит из интерфейсного интерфейса, созданного с помощью TypeScript, который вызывает внутренние API для получения данных, взаимодействия с функциями ИИ, отправки сообщений электронной почты и SMS и извлечения данных организации. Ниже приведен обзор решения приложения, которое вы узнаете в этом руководстве:
В этом руководстве описан процесс настройки необходимых ресурсов Azure и Microsoft 365. Кроме того, вы узнаете о коде, который используется для реализации функций ИИ, обмена данными и организации. Хотя вам не потребуется копировать и вставлять код, некоторые из упражнений будут изменять код, чтобы попробовать различные сценарии.
Что вы создадите в этом руководстве
Выбор собственного приключения
Вы можете завершить весь учебник, начиная с завершения или завершения конкретных вопросов, интересующих вас. Руководство разбито на следующие разделы:
- Клонируйте упражнение проекта (обязательное упражнение).
- Упражнения ИИ: создайте ресурс Azure OpenAI и используйте его для преобразования естественного языка в SQL, создания сообщений электронной почты или SMS и работы с собственными данными и документами.
- Упражнения по обмену данными. Создайте ресурс Служб коммуникации Azure и используйте его для звонков из приложения и отправки сообщений электронной почты или SMS.
- Упражнение по данным организации. Создание регистрации приложения идентификатора Записи Майкрософт , чтобы Microsoft Graph и Microsoft Graph Toolkit могли использоваться для проверки подлинности и извлечения данных организации в приложение.
Необходимые компоненты
- Узел — узел 20+ и npm 10+ будет использоваться для этого проекта
- Git
- Visual Studio Code (хотя visual Studio Code рекомендуется, любой редактор можно использовать)
- Подписка Azure
- Клиент разработчика Microsoft 365
- Docker Desktop или другая среда выполнения контейнеров, совместимая с OCI (Open Container Initiative), например Podman или nerdctl , способный запускать контейнер.
Технологии Microsoft Cloud, используемые в этом руководстве
- Службы коммуникации Azure
- Служба Azure OpenAI
- Microsoft Entra ID
- Microsoft Graph
- Набор средств Microsoft Graph
Клонирование проекта
Проект кода, используемый в этом руководстве, доступен по адресу https://github.com/microsoft/MicrosoftCloud. Репозиторий проекта включает клиентский и серверный код, необходимый для запуска проекта, что позволяет изучить интегрированные функции, связанные с искусственным интеллектом (ИИ), обменом данными и данными организации. Кроме того, проект служит ресурсом для включения аналогичных функций в собственные приложения.
В этом упражнении вы выполните такие действия:
- Клонируйте репозиторий GitHub.
- Добавьте env-файл в проект и обновите его.
Прежде чем продолжить, убедитесь, что установлены и настроены все необходимые компоненты, как описано в разделе "Предварительные требования " этого руководства.
Клонирование репозитория GitHub и создание .env файла
Выполните следующую команду, чтобы клонировать репозиторий Microsoft Cloud GitHub на компьютер.
Консольgit clone https://github.com/microsoft/MicrosoftCloudОткройте папку MicrosoftCloud/samples/openai-acs-msgraph в Visual Studio Code.
Примечание
Хотя в этом руководстве мы будем использовать Visual Studio Code, для работы с примером проекта можно использовать любой редактор кода.
Обратите внимание на следующие папки и файлы:
- client: клиентский код приложения.
- сервер: код API на стороне сервера.
- docker-compose.yml. Используется для запуска локальной базы данных PostgreSQL.
Переименуйте env.example в корневой каталог проекта в .env.
Откройте ENV-файл и просмотрите включенные ключи:
ENTRAID_CLIENT_ID= TEAM_ID= CHANNEL_ID= OPENAI_API_KEY= OPENAI_ENDPOINT= OPENAI_MODEL=gpt-4o OPENAI_API_VERSION=2024-05-01-preview POSTGRES_USER= POSTGRES_PASSWORD= ACS_CONNECTION_STRING= ACS_PHONE_NUMBER= ACS_EMAIL_ADDRESS= CUSTOMER_EMAIL_ADDRESS= CUSTOMER_PHONE_NUMBER= API_PORT=3000 AZURE_AI_SEARCH_ENDPOINT= AZURE_AI_SEARCH_KEY= AZURE_AI_SEARCH_INDEX=Обновите следующие значения в .env. Эти значения будут использоваться сервером API для подключения к локальной базе данных PostgreSQL.
POSTGRES_USER=web POSTGRES_PASSWORD=web-passwordТеперь, когда у вас есть проект, давайте рассмотрим некоторые функции приложения и узнайте, как они созданы. Нажмите кнопку "Далее ", чтобы продолжить или перейти к определенному упражнению, используя оглавление.
ИИ: создание ресурса Azure OpenAI и развертывание модели
Чтобы приступить к работе с Azure OpenAI в приложениях, необходимо создать службу Azure OpenAI и развернуть модель, которая может использоваться для выполнения задач, таких как преобразование естественного языка в SQL, создание содержимого сообщения электронной почты или SMS и многое другое.
В этом упражнении вы выполните такие действия:
- Создайте ресурс службы Azure OpenAI.
- Развертывание модели.
- Обновите env-файл со значениями из ресурса службы Azure OpenAI.
Создание ресурса службы Azure OpenAI
Посетите портал Azure в браузере и войдите в систему.
Введите openai в строке поиска в верхней части страницы портала и выберите Azure OpenAI из параметров, которые отображаются.
Выберите "Создать " на панели инструментов.
Примечание
Хотя в этом руководстве основное внимание уделяется Azure OpenAI, если у вас есть ключ API OpenAI и вы хотите его использовать, вы можете пропустить этот раздел и перейти непосредственно к разделу "Обновить env-файл проекта " ниже. Назначьте ключ
OPENAI_API_KEYAPI OpenAI в env-файле (вы можете игнорировать любые другие.envинструкции, связанные с OpenAI).Модели Azure OpenAI доступны в определенных регионах. Ознакомьтесь с документом о доступности модели Azure OpenAI , чтобы узнать, какие регионы поддерживают модель gpt-4o, используемую в этом руководстве.
Выполните следующие задачи:
- Выберите свою подписку Azure.
- Выберите группу ресурсов, используемую (при необходимости создайте новую).
- Выберите регион, в котором поддерживается модель gpt-4o на основе документа, который вы рассмотрели ранее.
- Введите имя ресурса. Это значение должно быть уникальным.
- Выберите ценовую категорию "Стандартный" S0 .
Нажмите кнопку "Далее", пока не получите экран проверки и отправки . Нажмите кнопку "Создать".
После создания ресурса Azure OpenAI перейдите к нему и выберите " Управление ресурсами " —">Ключи" и "Конечная точка ".
Найдите значения KEY 1 и Endpoint . Вы будете использовать оба значения в следующем разделе, чтобы скопировать их в локальный файл.
Выберите развертыванияуправления ресурсами -->Model.
Нажмите кнопку "Управление развертываниями" , чтобы перейти в Azure OpenAI Studio.
Выберите "Развернуть модель ->Развернуть базовую модель" на панели инструментов.
Выберите gpt-4o из списка моделей и нажмите кнопку "Подтвердить".
Примечание
Azure OpenAI поддерживает несколько различных типов моделей. Каждая модель может использоваться для обработки различных сценариев.
Откроется следующее диалоговое окно. Рассмотрим предоставленные значения по умолчанию.
Измените значение маркеров в минуту (тысячи) на 100K. Это позволит вам сделать больше запросов к модели и избежать попадания ограничения скорости при выполнении следующих действий.
Выберите "Развернуть".
После развертывания модели выберите "Игровые площадки " -->Chat.
В раскрывающемся списке развертывания должна отображаться модель gpt-4o .
Прочтите предоставленный системный текст сообщения . Это сообщает модели, как действовать как пользователь взаимодействует с ним.
Найдите текстовое поле в области чата и введите сводку по созданию ИИ и способ ее использования. Нажмите клавишу ВВОД , чтобы отправить сообщение модели и создать ответ.
Экспериментируйте с другими запросами и ответами. Например, введите краткую историю о столице Франции и обратите внимание на ответ, созданный.
Обновление файла проекта .env
Вернитесь в Visual Studio Code и откройте
.envфайл в корне проекта.Скопируйте значение KEY 1 из ресурса Azure OpenAI и назначьте его
OPENAI_API_KEYв env-файле , расположенном в корне папки openai-acs-msgraph :OPENAI_API_KEY=<KEY_1_VALUE>Скопируйте значение *Endpoint и назначьте его
OPENAI_ENDPOINTв env-файле ./Удалите символ из конца значения, если он присутствует.OPENAI_ENDPOINT=<ENDPOINT_VALUE>Примечание
Вы увидите, что значения для
OPENAI_MODELиOPENAI_API_VERSIONуже заданы в env-файле . Для значения модели задано значение gpt-4o , соответствующее имени развертывания модели, созданному ранее в этом упражнении. Версия API имеет поддерживаемое значение, определенное в справочной документации по Azure OpenAI.Сохраните ENV-файл .
Запуск служб приложений
Пришло время запустить службы приложений, включая базу данных, сервер API и веб-сервер.
В следующих шагах вы создадите три окна терминала в Visual Studio Code.
Щелкните правой кнопкой мыши env-файл в списке файлов Visual Studio Code и выберите "Открыть в интегрированном терминале". Перед продолжением убедитесь, что терминал находится в корне проекта — openai-acs-msgraph .
Выберите один из следующих параметров, чтобы запустить базу данных PostgreSQL:
Если установлен и запущен Docker Desktop , запустите
docker-compose upв окне терминала и нажмите клавишу ВВОД.Если у вас есть Podman с установленным и запущенным podman-compose , запустите
podman-compose upв окне терминала и нажмите клавишу ВВОД.Чтобы запустить контейнер PostgreSQL непосредственно с помощью Docker Desktop, Podman, nerdctl или другой установленной среды выполнения контейнера, выполните следующую команду в окне терминала:
Mac, Linux или подсистема Windows для Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgresWindows с PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
После запуска контейнера базы данных нажмите + значок на панели инструментов терминала Visual Studio Code, чтобы создать второе окно терминала.
cdв папку server/typescript и выполните следующие команды, чтобы установить зависимости и запустить сервер API.npm installnpm start
+ Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
cdв папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.npm installnpm start
Откроется браузер, в который вы http://localhost:4200перейдете.
ИИ: естественный язык для SQL
Цитата "Просто потому, что вы не можете означать, что вы должны" является полезным руководством при разработке возможностей ИИ. Например, естественный язык Azure OpenAI для SQL позволяет пользователям создавать запросы к базе данных на обычном английском языке, что может быть мощным инструментом для повышения производительности. Однако мощный не всегда означает подходящий или безопасный. В этом упражнении показано, как использовать эту функцию ИИ, а также обсудить важные аспекты, которые следует учитывать перед принятием решения о его реализации.
Ниже приведен пример запроса естественного языка, который можно использовать для получения данных из базы данных:
Get the the total revenue for all companies in London.
При правильном запросе Azure OpenAI преобразует этот запрос в SQL, который можно использовать для возврата результатов из базы данных. В результате нетехническая поддержка пользователей, включая бизнес-аналитиков, маркетинговиков и руководителей, может проще получить ценные сведения из баз данных, не борясь с сложным синтаксисом SQL или опираясь на ограниченные наборы данных и фильтры. Этот упрощенный подход может повысить производительность, устраняя потребность пользователей в поиске помощи от технических экспертов.
Это упражнение предоставляет отправную точку, которая поможет вам понять, как работает естественный язык для SQL, ознакомиться с некоторыми важными рекомендациями, понять, как вы думаете о преимуществах и минусах, и показать вам код для начала работы.
В этом упражнении вы выполните следующие действия.
- Используйте запросы GPT для преобразования естественного языка в SQL.
- Экспериментируйте с различными запросами GPT.
- Используйте созданный SQL для запроса базы данных PostgreSQL, запущенной ранее.
- Результаты запроса возвращаются из PostgreSQL и отображаются в браузере.
Начнем с экспериментов с различными запросами GPT, которые можно использовать для преобразования естественного языка в SQL.
Использование естественного языка для компонента SQL
В предыдущем упражнении вы запустили базу данных, API и приложение. Вы также обновили
.envфайл. Если вы не выполнили эти действия, следуйте инструкциям в конце упражнения, прежде чем продолжить.Вернитесь в браузер (http://localhost:4200) и найдите раздел настраиваемого запроса страницы под datagrid. Обратите внимание, что образец значения запроса уже включен: получение общего дохода для всех заказов. Группировать по компании и включать город.
Нажмите кнопку "Выполнить запрос ". Это приведет к передаче запроса естественного языка пользователя в Azure OpenAI, который преобразует его в SQL. Затем SQL-запрос будет использоваться для запроса базы данных и возврата любых потенциальных результатов.
Выполните следующий пользовательский запрос:
Get the total revenue for Adventure Works Cycles. Include the contact information as well.Просмотрите окно терминала, на котором запущен сервер API в Visual Studio Code, и обратите внимание, что он отображает SQL-запрос, возвращенный из Azure OpenAI. Данные JSON используются интерфейсами API на стороне сервера для запроса базы данных PostgreSQL. Все строковые значения, включенные в запрос, добавляются в качестве значений параметров, чтобы предотвратить атаки на внедрение SQL:
JSON{ "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", "paramValues": ["Adventure Works Cycles"] }Вернитесь в браузер и выберите "Сбросить данные ", чтобы просмотреть все клиенты снова в datagrid.
Изучение естественного языка в КОДе SQL
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Примечание
Цель этого упражнения заключается в том, чтобы показать, что возможно с помощью естественного языка в функциональных возможностях SQL и продемонстрировать, как приступить к работе с ним. Как упоминалось ранее, важно обсудить, подходит ли этот тип искусственного интеллекта для вашей организации, прежде чем продолжить любую реализацию. Кроме того, необходимо планировать надлежащие правила запроса и меры безопасности базы данных , чтобы предотвратить несанкционированный доступ и защитить конфиденциальные данные.
Теперь, когда вы видели естественный язык для функции SQL в действии, давайте рассмотрим, как она реализована.
Откройте файл сервера или apiRoutes.ts и найдите
generateSqlмаршрут. Этот маршрут API вызывается клиентским приложением, работающим в браузере, и используется для создания SQL из запроса естественного языка. После получения SQL-запроса он используется для запроса базы данных и возврата результатов.TypeScriptrouter.post('/generateSql', async (req, res) => { const userPrompt = req.body.prompt; if (!userPrompt) { return res.status(400).json({ error: 'Missing parameter "prompt".' }); } try { // Call Azure OpenAI to convert the user prompt into a SQL query const sqlCommandObject = await getSQLFromNLP(userPrompt); let result: any[] = []; // Execute the SQL query if (sqlCommandObject && !sqlCommandObject.error) { result = await queryDb(sqlCommandObject) as any[]; } else { result = [ { query_error : sqlCommandObject.error } ]; } res.json(result); } catch (e) { console.error(e); res.status(500).json({ error: 'Error generating or running SQL query.' }); } });Обратите внимание на следующие функции маршрута
generateSql:- Он извлекает значение пользовательского запроса из
req.body.promptи назначает его переменной с именемuserPrompt. Это значение будет использоваться в запросе GPT. - Она вызывает функцию
getSQLFromNLP()для преобразования естественного языка в SQL. - Он передает созданный SQL функции с именем
queryDb, которая выполняет SQL-запрос и возвращает результаты из базы данных.
- Он извлекает значение пользовательского запроса из
Откройте файл сервера или openAI.ts в редакторе и найдите функцию
getSQLFromNLP(). Эта функция вызывается маршрутомgeneratesqlи используется для преобразования естественного языка в SQL.TypeScriptasync function getSQLFromNLP(userPrompt: string): Promise<QueryData> { // Get the high-level database schema summary to be used in the prompt. // The db.schema file could be generated by a background process or the // schema could be dynamically retrieved. const dbSchema = await fs.promises.readFile('db.schema', 'utf8'); const systemPrompt = ` Assistant is a natural language to SQL bot that returns a JSON object with the SQL query and the parameter values in it. The SQL will query a PostgreSQL database. PostgreSQL tables with their columns: ${dbSchema} Rules: - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks. - Return a JSON object with the following structure: { "sql": "", "paramValues": [] } Examples: User: "Display all company reviews. Group by company." Assistant: { "sql": "SELECT * FROM reviews", "paramValues": [] } User: "Display all reviews for companies located in cities that start with 'L'." Assistant: { "sql": "SELECT r.* FROM reviews r INNER JOIN customers c ON r.customer_id = c.id WHERE c.city LIKE 'L%'", "paramValues": [] } User: "Display revenue for companies located in London. Include the company name and city." Assistant: { "sql": "SELECT c.company, c.city, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.city = $1 GROUP BY c.company, c.city", "paramValues": ["London"] } User: "Get the total revenue for Adventure Works Cycles. Include the contact information as well." Assistant: { "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", "paramValues": ["Adventure Works Cycles"] } `; let queryData: QueryData = { sql: '', paramValues: [], error: '' }; let results = ''; try { results = await callOpenAI(systemPrompt, userPrompt); if (results) { console.log('results', results); const parsedResults = JSON.parse(results); queryData = { ...queryData, ...parsedResults }; if (isProhibitedQuery(queryData.sql)) { queryData.sql = ''; queryData.error = 'Prohibited query.'; } } } catch (error) { console.log(error); if (isProhibitedQuery(results)) { queryData.sql = ''; queryData.error = 'Prohibited query.'; } else { queryData.error = results; } } return queryData; }- Параметр
userPromptпередается в функцию. ЗначениемuserPromptявляется запрос естественного языка, введенный пользователем в браузере. - Определяет
systemPromptтип помощника по искусственному интеллекту, который следует использовать, и правила, которые следует соблюдать. Это помогает Azure OpenAI понимать структуру базы данных, какие правила следует применять, а также как возвращать созданный SQL-запрос и параметры. - Вызывается
callOpenAI()функция иsystemPromptuserPromptпередаются в нее значения. - Результаты проверяются, чтобы гарантировать, что в созданный SQL-запрос не включены запрещенные значения. При обнаружении запрещенных значений SQL-запрос имеет пустую строку.
- Параметр
Более подробно рассмотрим системный запрос:
TypeScriptconst systemPrompt = ` Assistant is a natural language to SQL bot that returns a JSON object with the SQL query and the parameter values in it. The SQL will query a PostgreSQL database. PostgreSQL tables with their columns: ${dbSchema} Rules: - Convert any strings to a PostgreSQL parameterized query value to avoid SQL injection attacks. - Return a JSON object with the following structure: { "sql": "", "paramValues": [] } Examples: User: "Display all company reviews. Group by company." Assistant: { "sql": "SELECT * FROM reviews", "paramValues": [] } User: "Display all reviews for companies located in cities that start with 'L'." Assistant: { "sql": "SELECT r.* FROM reviews r INNER JOIN customers c ON r.customer_id = c.id WHERE c.city LIKE 'L%'", "paramValues": [] } User: "Display revenue for companies located in London. Include the company name and city." Assistant: { "sql": "SELECT c.company, c.city, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.city = $1 GROUP BY c.company, c.city", "paramValues": ["London"] } User: "Get the total revenue for Adventure Works Cycles. Include the contact information as well." Assistant: { "sql": "SELECT c.company, c.city, c.email, SUM(o.total) AS revenue FROM customers c INNER JOIN orders o ON c.id = o.customer_id WHERE c.company = $1 GROUP BY c.company, c.city, c.email", "paramValues": ["Adventure Works Cycles"] } `;Определяется тип используемого помощника по искусственному интеллекту. В этом случае "естественный язык для бота SQL".
Определены имена таблиц и столбцы в базе данных. Высокоуровневая схема, включенная в запрос, находится в файле server/db.schema и выглядит следующим образом.
- customers (id, company, city, email) - orders (id, customer_id, date, total) - order_items (id, order_id, product_id, quantity, price) - reviews (id, customer_id, review, date, comment)Совет
Возможно, вы можете создать представления только для чтения, содержащие только пользователей данных, разрешены запрашивать с помощью естественного языка в SQL.
Правило определяется для преобразования строковых значений в параметризованное значение запроса, чтобы избежать атак внедрения SQL.
Правило определяется, чтобы всегда возвращать объект JSON с sql-запросом и значениями параметров в нем.
Приведены примеры запросов пользователей и ожидаемых значений sql-запроса и параметров. Это называется "несколькими выстрелами" обучение. Хотя LLM обучены на больших объемах данных, их можно адаптировать к новым задачам только в нескольких примерах. Альтернативный подход — это "нулевой снимок", в котором нет примера, и модель, как ожидается, создаст правильные значения SQL-запроса и параметров.
Функция
getSQLFromNLP()отправляет системе и пользователю запросы в функцию с именемcallOpenAI(), которая также находится в файле сервера или openAI.ts . ФункцияcallOpenAI()определяет, должна ли служба Azure OpenAI или служба OpenAI вызываться путем проверки переменных среды. Если ключ, конечная точка и модель доступны в переменных среды, вызывается Azure OpenAI, в противном случае вызывается OpenAI.TypeScriptfunction callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) { const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL; if (isAzureOpenAI) { if (useBYOD) { return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature); } return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature); } return getOpenAICompletion(systemPrompt, userPrompt, temperature); }Примечание
Хотя мы сосредоточимся на Azure OpenAI в этом руководстве, если вы предоставляете
OPENAI_API_KEYтолько значение в env-файле , приложение будет использовать OpenAI вместо этого. Если вы решили использовать OpenAI вместо Azure OpenAI, вы можете увидеть разные результаты в некоторых случаях.Найдите функцию
getAzureOpenAICompletion().TypeScriptasync function getAzureOpenAICompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> { const completion = await createAzureOpenAICompletion(systemPrompt, userPrompt, temperature); let content = completion.choices[0]?.message?.content?.trim() ?? ''; console.log('Azure OpenAI Output: \n', content); if (content && content.includes('{') && content.includes('}')) { content = extractJson(content); } return content; }Эта функция выполняет следующие действия:
Параметры:
-
systemPrompt,userPromptиtemperatureявляются основными параметрами.-
systemPrompt: сообщает модели Azure OpenAI о своей роли и правилах, которые необходимо выполнить. -
userPrompt: содержит предоставленные пользователем сведения, такие как входные данные естественного языка или правила для создания выходных данных. -
temperature: диктует уровень творчества ответа модели. Более высокое значение приводит к более творческим выходным данным.
-
-
Создание завершения:
- Вызовы
createAzureOpenAICompletion()функции сsystemPrompt,userPromptаtemperatureтакже для создания завершения. - Он извлекает содержимое из первого выбора в завершении, обрезая любое дополнительное пробелы.
- Если содержимое содержит такие структуры JSON (указано наличием
{и}), извлекает содержимое JSON.
- Вызовы
Ведение журнала и возвращаемое значение:
- Функция записывает выходные данные Azure OpenAI в консоль.
- Он возвращает обработанное содержимое в виде строки.
Найдите функцию
createAzureOpenAICompletion().TypeScriptasync function createAzureOpenAICompletion(systemPrompt: string, userPrompt: string, temperature: number, dataSources?: any[]): Promise<any> { const baseEnvVars = ['OPENAI_API_KEY', 'OPENAI_ENDPOINT', 'OPENAI_MODEL']; const byodEnvVars = ['AZURE_AI_SEARCH_ENDPOINT', 'AZURE_AI_SEARCH_KEY', 'AZURE_AI_SEARCH_INDEX']; const requiredEnvVars = dataSources ? [...baseEnvVars, ...byodEnvVars] : baseEnvVars; checkRequiredEnvVars(requiredEnvVars); const config = { apiKey: OPENAI_API_KEY, endpoint: OPENAI_ENDPOINT, apiVersion: OPENAI_API_VERSION, deployment: OPENAI_MODEL }; const aoai = new AzureOpenAI(config); const completion = await aoai.chat.completions.create({ model: OPENAI_MODEL, // gpt-4o, gpt-3.5-turbo, etc. Pulled from .env file max_tokens: 1024, temperature, response_format: { type: "json_object", }, messages: [ { role: 'system', content: systemPrompt }, { role: 'user', content: userPrompt } ], // @ts-expect-error data_sources is a custom property used with the "Azure Add Your Data" feature data_sources: dataSources }); return completion; } function checkRequiredEnvVars(requiredEnvVars: string[]) { for (const envVar of requiredEnvVars) { if (!process.env[envVar]) { throw new Error(`Missing ${envVar} in environment variables.`); } } }Эта функция выполняет следующие действия:
Параметры:
-
systemPrompt,userPromptиtemperatureявляются основными параметрами, рассмотренными ранее. - Необязательный
dataSourcesпараметр поддерживает функцию "Azure Bring Your Own Data", которая будет описана далее в этом руководстве.
-
Проверка переменных среды:
- Функция проверяет наличие важных переменных среды, вызывая ошибку, если отсутствуют какие-либо.
Объект конфигурации:
-
configОбъект создается с помощью значений.envиз файла (OPENAI_API_KEY,OPENAI_ENDPOINT, ,OPENAI_API_VERSIONOPENAI_MODEL). Эти значения используются для создания URL-адреса для вызова Azure OpenAI.
-
Экземпляр AzureOpenAI:
- Создается экземпляр
AzureOpenAIс помощью объектаconfig. СимволAzureOpenAIявляется частьюopenaiпакета, который должен быть импортирован в верхней части файла.
- Создается экземпляр
Создание завершения:
- Функция
chat.completions.create()вызывается со следующими свойствами:-
model: указывает модель GPT (например, gpt-4o, gpt-3.5-turbo), как определено в файле.env. -
max_tokens: определяет максимальное количество маркеров для завершения. -
temperature: задает температуру выборки. Более высокие значения (например, 0,9) дают больше творческих ответов, а более низкие значения (например, 0) создают более детерминированные ответы. -
response_format: определяет формат ответа. Здесь задано значение для возврата объекта JSON. Дополнительные сведения о режиме JSON см. в справочной документации по Azure OpenAI. -
messages: содержит сообщения для создания завершения чата. В этом примере содержатся два сообщения: один из системы (определение поведения и правил) и один из пользователей (содержащий текст запроса).
-
- Функция
Возвращаемое значение:
- Функция возвращает объект завершения, созданный Azure OpenAI.
Закомментируйте следующие строки в
getSQLFromNLP()функции:TypeScript// if (isProhibitedQuery(queryData.sql)) { // queryData.sql = ''; // }Сохраните openAI.ts. Сервер API автоматически перестроит код TypeScript и перезагрузит сервер.
Вернитесь в браузер и введите все имена таблиц из базы данных в входные данные пользовательского запроса . Выберите "Выполнить запрос". Отображаются ли имена таблиц?
Вернитесь к
getSQLFromNLP()функции на сервере или openAI.ts и добавьте следующее правило вRules:раздел системного запроса, а затем сохраните файл.- Do not allow the SELECT query to return table names, function names, or procedure names.Вернитесь в браузер и выполните следующие задачи:
- Введите все имена таблиц из базы данных в входные данные пользовательского запроса . Выберите "Выполнить запрос". Отображаются ли имена таблиц?
- Введите все имена функций из базы данных. В входные данные настраиваемого запроса и снова нажмите кнопку "Выполнить запрос ". Отображаются ли имена функций?
ВОПРОС. Будет ли модель всегда соответствовать правилам, заданным в запросе?
ОТВЕТ: Нет! Важно отметить, что модели OpenAI могут возвращать непредвиденные результаты иногда, которые могут не соответствовать определенным правилам. Важно планировать это в коде.
Вернитесь на сервер или openAI.ts и найдите функцию
isProhibitedQuery(). Это пример кода после последующей обработки, который может выполняться после возврата результатов в Azure OpenAI. Обратите внимание, что свойство присваиваетсяsqlпустой строке, если запрещенные ключевые слова возвращаются в созданном SQL-запросе. Это гарантирует, что если непредвиденные результаты возвращаются из Azure OpenAI, sql-запрос не будет выполняться в базе данных.TypeScriptfunction isProhibitedQuery(query: string): boolean { if (!query) return false; const prohibitedKeywords = [ 'insert', 'update', 'delete', 'drop', 'truncate', 'alter', 'create', 'replace', 'information_schema', 'pg_catalog', 'pg_tables', 'pg_proc', 'pg_namespace', 'pg_class', 'table_schema', 'table_name', 'column_name', 'column_default', 'is_nullable', 'data_type', 'udt_name', 'character_maximum_length', 'numeric_precision', 'numeric_scale', 'datetime_precision', 'interval_type', 'collation_name', 'grant', 'revoke', 'rollback', 'commit', 'savepoint', 'vacuum', 'analyze' ]; const queryLower = query.toLowerCase(); return prohibitedKeywords.some(keyword => queryLower.includes(keyword)); }Примечание
Важно отметить, что это только демонстрационный код. При выборе преобразования естественного языка в SQL могут быть другие запрещенные ключевые слова, необходимые для покрытия конкретных вариантов использования. Это функция, которую необходимо запланировать и использовать с осторожностью, чтобы гарантировать, что возвращаются только допустимые запросы SQL и выполняются в базе данных. Помимо запрещенных ключевых слов, также необходимо учитывать безопасность.
Вернитесь к серверу или openAI.ts и раскомментируйте следующий код в
getSQLFromNLP()функции. Сохраните файл.TypeScriptif (isProhibitedQuery(queryData.sql)) { queryData.sql = ''; }Удалите следующее правило из
systemPromptфайла и сохраните его.- Do not allow the SELECT query to return table names, function names, or procedure names.Вернитесь в браузер, введите все имена таблиц из базы данных в входные данные пользовательского запроса и нажмите кнопку "Выполнить запрос ".
Отображаются ли результаты таблицы? Даже без правила
isProhibitedQuery()код после обработки запрещает выполнение этого типа запроса в базе данных.Как уже говорилось ранее, интеграция естественного языка с SQL в бизнес-приложениях может быть довольно полезной для пользователей, но она имеет собственный набор рекомендаций.
Преимущества:
Удобство работы с пользователем. Эта функция может сделать взаимодействие с базами данных более доступными для пользователей без технического опыта, уменьшая потребность в знаниях SQL и потенциально ускоряя операции.
Повышение производительности: бизнес-аналитики, специалисты по маркетингу, руководители и другие нетехническая пользователи могут получать ценные сведения из баз данных без необходимости полагаться на технических экспертов, тем самым повышая эффективность.
Широкое приложение. С помощью расширенных языковых моделей приложения могут быть разработаны для обеспечения широкого спектра пользователей и вариантов использования.
Соображения:
Безопасность: одной из самых больших проблем является безопасность. Если пользователи могут взаимодействовать с базами данных с помощью естественного языка, необходимо обеспечить надежные меры безопасности, чтобы предотвратить несанкционированный доступ или вредоносные запросы. Вы можете реализовать режим только для чтения, чтобы запретить пользователям изменять данные.
Конфиденциальность данных. Некоторые данные могут быть конфиденциальными и не должны быть легко доступными, поэтому вам потребуется обеспечить надлежащие гарантии и разрешения пользователей.
Точность. В то время как обработка естественного языка значительно улучшилась, это не идеально. Неправильное представление запросов пользователей может привести к неточным результатам или непредвиденному поведению. Вам потребуется спланировать, как будут обрабатываться непредвиденные результаты.
Эффективность. Нет никаких гарантий, что SQL, возвращенный из запроса естественного языка, будет эффективным. В некоторых случаях дополнительные вызовы к Azure OpenAI могут потребоваться, если правила после обработки обнаруживают проблемы с запросами SQL.
Обучение и адаптация пользователей: пользователям необходимо обучено правильно сформулировать свои запросы. Хотя это проще, чем обучение SQL, может быть и кривая обучения.
Перед переходом к следующему упражнению следует рассмотреть несколько окончательных пунктов:
- Помните, что "Просто потому, что вы не можете означать, что вы должны" применяется здесь. Используйте крайне осторожность и тщательное планирование перед интеграцией естественного языка с SQL в приложение. Важно понимать потенциальные риски и планировать их.
- Прежде чем использовать эту технологию, обсудите потенциальные сценарии с командой, администраторами баз данных, командой безопасности, заинтересованными лицами и другими соответствующими сторонами, чтобы убедиться, что она подходит для вашей организации. Важно обсудить, соответствует ли естественному языку SQL безопасность, конфиденциальность и другие требования вашей организации.
- Безопасность должна быть основной проблемой и встроена в процесс планирования, разработки и развертывания.
- Хотя естественный язык для SQL может быть очень мощным, тщательное планирование должно перейти в него, чтобы обеспечить наличие необходимых правил и включена функция после обработки. Запланируйте дополнительное время для реализации и тестирования таких функций и для учета сценариев, в которых возвращаются непредвиденные результаты.
- С помощью Azure OpenAI клиенты получают возможности безопасности Microsoft Azure, выполняя те же модели, что и OpenAI. Azure OpenAI предлагает частные сети, региональную доступность и фильтрацию содержимого ИИ. Дополнительные сведения о данных, конфиденциальности и безопасности для Службы Azure OpenAI.
Теперь вы узнали, как использовать Azure OpenAI для преобразования естественного языка в SQL и узнали о преимуществах и недостатках реализации этого типа функций. В следующем упражнении вы узнаете, как создавать сообщения электронной почты и SMS с помощью Azure OpenAI.
ИИ: создание завершений
Помимо естественного языка в компоненте SQL, вы также можете использовать Службу OpenAI Azure для создания сообщений электронной почты и SMS для повышения производительности пользователей и упрощения рабочих процессов связи. Используя возможности создания языка Azure OpenAI, пользователи могут определять определенные правила, такие как "Заказ отложен 5 дней", и система автоматически создаст контекстно соответствующие сообщения электронной почты и SMS на основе этих правил.
Эта возможность служит в качестве начального запуска для пользователей, предоставляя им задумчивый шаблон сообщения, который можно легко настроить перед отправкой. Результатом является значительное сокращение времени и усилий, необходимых для создания сообщений, что позволяет пользователям сосредоточиться на других важных задачах. Кроме того, технология создания языка Azure OpenAI может быть интегрирована в рабочие процессы автоматизации, что позволяет системе автономно создавать и отправлять сообщения в ответ на предопределенные триггеры. Этот уровень автоматизации не только ускоряет процессы обмена данными, но и обеспечивает согласованность и точность обмена сообщениями в различных сценариях.
В этом упражнении вы выполните следующие действия.
- Экспериментируйте с различными запросами.
- Используйте запросы на создание завершений для сообщений электронной почты и SMS.
- Изучите код, обеспечивающий завершение ИИ.
- Узнайте о важности проектирования запросов и включения правил в запросы.
Давайте приступим к работе, экспериментируя с различными правилами, которые можно использовать для создания сообщений электронной почты и SMS.
Использование функции завершения ИИ
В предыдущем упражнении вы запустили базу данных, API и приложение. Вы также обновили
.envфайл. Если вы не выполнили эти действия, следуйте инструкциям в конце упражнения, прежде чем продолжить.Вернитесь к браузеру (http://localhost:4200) и выберите "Связаться с клиентом " в любой строке в datagrid, за которой следует email/SMS Customer , чтобы перейти на экран генератора сообщений .
Это использует Azure OpenAI для преобразования правил сообщений, которые определяются в сообщения электронной почты или SMS. Выполните следующие задачи:
Введите правило, например заказ, отложено 5 дней в входные данные и нажмите кнопку "Создать сообщения электронной почты или SMS ".
Вы увидите тему и текст, созданные для сообщения электронной почты, и короткое сообщение, созданное для SMS.
Примечание
Так как Службы коммуникации Azure еще не включено, вы не сможете отправлять сообщения электронной почты или SMS.
Закройте диалоговое окно электронной почты или SMS в браузере. Теперь, когда вы видели эту функцию в действии, давайте рассмотрим, как она реализована.
Изучение кода завершения ИИ
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Откройте файл сервера или apiRoutes.ts и найдите
completeEmailSmsMessagesмаршрут. Этот API вызывается интерфейсной частью приложения при выборе кнопки "Создать сообщения электронной почты или SMS ". Он извлекает значения имени пользователя, компании и контакта из текста и передает ихcompleteEmailSMSMessages()функции в файле сервера или openAI.ts . Затем результаты возвращаются клиенту.TypeScriptrouter.post('/completeEmailSmsMessages', async (req, res) => { const { prompt, company, contactName } = req.body; if (!prompt || !company || !contactName) { return res.status(400).json({ status: false, error: 'The prompt, company, and contactName parameters must be provided.' }); } let result; try { // Call OpenAI to get the email and SMS message completions result = await completeEmailSMSMessages(prompt, company, contactName); } catch (e: unknown) { console.error('Error parsing JSON:', e); } res.json(result); });Откройте файл сервера или openAI.ts и найдите функцию
completeEmailSMSMessages().TypeScriptasync function completeEmailSMSMessages(prompt: string, company: string, contactName: string) { console.log('Inputs:', prompt, company, contactName); const systemPrompt = ` Assistant is a bot designed to help users create email and SMS messages from data and return a JSON object with the email and SMS message information in it. Rules: - Generate a subject line for the email message. - Use the User Rules to generate the messages. - All messages should have a friendly tone and never use inappropriate language. - SMS messages should be in plain text format and NO MORE than 160 characters. - Start the message with "Hi <Contact Name>,\n\n". Contact Name can be found in the user prompt. - Add carriage returns to the email message to make it easier to read. - End with a signature line that says "Sincerely,\nCustomer Service". - Return a valid JSON object with the emailSubject, emailBody, and SMS message values in it: { "emailSubject": "", "emailBody": "", "sms": "" } - The sms property value should be in plain text format and NO MORE than 160 characters. `; const userPrompt = ` User Rules: ${prompt} Contact Name: ${contactName} `; let content: EmailSmsResponse = { status: true, email: '', sms: '', error: '' }; let results = ''; try { results = await callOpenAI(systemPrompt, userPrompt, 0.5); if (results) { const parsedResults = JSON.parse(results); content = { ...content, ...parsedResults, status: true }; } } catch (e) { console.log(e); content.status = false; content.error = results; } return content; }Эта функция имеет следующие функции:
-
systemPromptиспользуется для определения того, что помощник по искусственному интеллекту, способный создавать сообщения электронной почты и SMS, требуется. Также включает вsystemPromptсебя:- Правила для помощника, чтобы управлять тоном сообщений, начальным и конечным форматом, максимальной длиной SMS-сообщений и т. д.
- Сведения о данных, которые должны быть включены в ответ, — объект JSON в данном случае.
-
userPromptиспользуется для определения правил и имени контакта, которые пользователь хотел бы включить в качестве сообщений электронной почты и SMS. Введенное . - Функция вызывает
callOpenAI()функцию, которую вы изучили ранее, чтобы создать завершения электронной почты и SMS.
-
Вернитесь в браузер, обновите страницу и выберите "Связаться с клиентом " в любой строке, за которой следует сообщение электронной почты или SMS,чтобы снова перейти на экран генератора сообщений .
Введите следующие правила в входные данные генератора сообщений:
- Заказ впереди расписания.
- Расскажите клиенту никогда не заказывать от нас снова, мы не хотим, чтобы их бизнес.
Выберите "Создать сообщения электронной почты/SMS" и запишите это сообщение. Правило
All messages should have a friendly tone and never use inappropriate language.в системном запросе переопределяет отрицательное правило в запросе пользователя.Вернитесь к серверу или openAI.ts* в редакторе и удалите
All messages should have a friendly tone and never use inappropriate language.правило из запроса вcompleteEmailSMSMessages()функции. Сохраните файл.Вернитесь к генератору сообщений электронной почты или SMS в браузере и снова выполните те же правила:
- Заказ впереди расписания.
- Расскажите клиенту никогда не заказывать от нас снова, мы не хотим, чтобы их бизнес.
Выберите "Создать сообщения электронной почты/SMS" и обратите внимание на возвращенное сообщение.
Что происходит в этих сценариях? При использовании Azure OpenAI фильтрация содержимого может применяться, чтобы обеспечить всегдае использование соответствующего языка. Если вы используете OpenAI, правило, определенное в системном запросе, используется для обеспечения соответствия возвращенного сообщения.
Примечание
Это иллюстрирует важность инженерных запросов с правильными сведениями и правилами, чтобы обеспечить правильные результаты возврата. Дополнительные сведения об этом процессе см. в статье "Введение в документацию по проектированию запросов ".
Отмените внесенные изменения
systemPromptcompleteEmailSMSMessages(), сохраните файл и повторно запустите его еще раз, но используйтеOrder is ahead of schedule.правило (не включайте отрицательное правило). На этот раз вы увидите сообщения электронной почты и SMS, возвращенные должным образом.Перед переходом к следующему упражнению следует рассмотреть несколько окончательных пунктов:
- Важно иметь человека в цикле для просмотра созданных сообщений. В этом примере завершения Azure OpenAI возвращают предлагаемые сообщения электронной почты и SMS, но пользователь может переопределить их перед отправкой. Если вы планируете автоматизировать сообщения электронной почты, имея некоторый тип процесса проверки человека, чтобы убедиться, что утвержденные сообщения отправляются важно. Просматривайте ИИ как copilot, а не автопилот.
- Завершения будут выполняться только так же хорошо, как и правила, которые вы добавляете в запрос. Время на тестирование запросов и возвращаемых завершений. Рассмотрите возможность использования потока запросов для создания комплексного решения, упрощающего прототипирование, экспериментирование, итерацию и развертывание приложений ИИ. Пригласите других заинтересованных лиц проекта, чтобы также просмотреть завершения.
- Возможно, потребуется включить код после обработки, чтобы обеспечить правильную обработку непредвиденных результатов.
- Используйте системные запросы, чтобы определить правила и сведения, которые должен следовать помощнику по ИИ. Используйте запросы пользователя, чтобы определить правила и сведения, которые пользователь хотел бы включить в завершения.
ИИ: Azure OpenAI в данных
Интеграция Azure OpenAI Natural Language Processing (NLP) и возможностей завершения обеспечивает значительный потенциал для повышения производительности пользователей. Используя соответствующие запросы и правила, помощник по искусственному интеллекту может эффективно создавать различные формы связи, такие как сообщения электронной почты, SMS-сообщения и многое другое. Эта функция приводит к повышению эффективности пользователей и оптимизации рабочих процессов.
Хотя эта функция достаточно мощна самостоятельно, могут возникнуть случаи, когда пользователям необходимо создавать завершения на основе пользовательских данных вашей компании. Например, у вас может быть коллекция руководств по продукту, которые могут быть сложными для пользователей, которые могут перемещаться, когда они помогают клиентам с проблемами установки. Кроме того, вы можете поддерживать полный набор часто задаваемых вопросов (часто задаваемых вопросов), связанных с преимуществами здравоохранения, которые могут оказаться сложными для пользователей, чтобы прочитать и получить ответы, необходимые им. В таких случаях и многих других служба Azure OpenAI позволяет использовать собственные данные для создания завершений, обеспечивая более точный и контекстно точный ответ на вопросы пользователей.
Ниже приведен краткий обзор работы функции "перенос собственных данных" из документации по Azure OpenAI.
Примечание
Одной из ключевых функций Azure OpenAI в данных является возможность получения и использования данных таким образом, чтобы повысить выходные данные модели. Azure OpenAI на ваших данных вместе с поиском ИИ Azure определяет, какие данные следует извлекать из указанного источника данных на основе входных данных пользователя и предоставленного журнала бесед. Затем эти данные дополняются и повторно передаются в качестве запроса к модели OpenAI, при этом извлекаемые сведения добавляются к исходному запросу. Хотя полученные данные добавляются в запрос, результирующий вход по-прежнему обрабатывается моделью, как и любой другой запрос. После получения данных и отправки запроса в модель модель модель использует эту информацию для предоставления завершения.
В этом упражнении вы выполните следующие действия.
- Создайте пользовательский источник данных с помощью портала Azure AI Foundry.
- Разверните модель внедрения с помощью портала Azure AI Foundry.
- Отправка пользовательских документов.
- Запустите сеанс чата на игровой площадке чата, чтобы поэкспериментировать с созданием завершений на основе собственных данных.
- Изучите код, использующий поиск ИИ Azure и Azure OpenAI для создания завершений на основе собственных данных.
Давайте начнем с развертывания модели внедрения и добавления пользовательского источника данных в Azure AI Foundry.
Добавление пользовательского источника данных в Azure AI Foundry
Перейдите в Azure OpenAI Studio и войдите с учетными данными, имеющими доступ к ресурсу Azure OpenAI.
Выберите развертывания в меню навигации.
Выберите "Выбрать модель развертывания " ->-Deploy base model (Развернуть базовую модель ) на панели инструментов.
Выберите модель внедрения текста ada-002 из списка моделей и нажмите кнопку "Подтвердить".
Выберите следующие параметры.
- Имя развертывания: text-embedding-ada-002
- Версия модели: по умолчанию
- Тип развертывания: Стандартный
- Задайте для маркеров значение "Ограничение скорости минуты" (тысячи) значение 120K
- Фильтр содержимого: DefaultV2
- Включить динамическую цитату: включено
Нажмите кнопку "Развернуть ".
После создания модели выберите "Главная" в меню навигации, чтобы перейти на экран приветствия.
Найдите плитку "Принести собственные данные " на экране приветствия и нажмите кнопку "Попробовать сейчас".
Выберите "Добавить данные ", а затем добавьте источник данных.
В раскрывающемся списке "Выбор источника данных " выберите " Отправить файлы".
В раскрывающемся списке "Выбор ресурса хранилища BLOB-объектов Azure " выберите "Создать новый ресурс хранилища BLOB-объектов Azure".
Выберите подписку Azure в раскрывающемся списке "Подписка ".
В раскрывающемся списке "Выбор ресурса хранилища BLOB-объектов Azure " выберите "Создать новый ресурс хранилища BLOB-объектов Azure".
Это приведет к портал Azure, где можно выполнить следующие задачи:
- Введите уникальное имя учетной записи хранения, например byodstorage[Ваше фамилия].
- Выберите регион, близкий к вашему расположению.
- Выберите "Рецензирование ", а затем "Создать".
После создания ресурса хранилища BLOB-объектов вернитесь в диалоговое окно Azure AI Foundry и выберите созданный ресурс хранилища BLOB-объектов из раскрывающегося списка "Выбор ресурса хранилища BLOB-объектов Azure ". Если вы не видите его в списке, щелкните значок обновления рядом с раскрывающимся списком.
Для доступа к учетной записи хранения необходимо включить общий доступ к ресурсам между источниками (CORS). Выберите включить CORS в диалоговом окне Azure AI Foundry.
В раскрывающемся списке " Выбор ресурса поиска ИИ Azure " выберите "Создать новый ресурс поиска ИИ Azure".
При этом вы вернеесь к портал Azure, где можно выполнить следующие задачи:
- Введите уникальное имя ресурса поиска ИИ, например byodsearch-[ваше фамилия].
- Выберите регион, близкий к вашему расположению.
- В разделе "Ценовая категория " выберите "Изменить ценовую категорию " и выберите "Базовый" и "Выбрать". Уровень "Бесплатный" не поддерживается, поэтому вы очистите ресурс поиска ИИ в конце этого руководства.
- Выберите "Рецензирование ", а затем "Создать".
После создания ресурса поиска ИИ перейдите на страницу обзора ресурсов и скопируйте значение URL-адреса в локальный файл.
Выберите параметры -->Ключи в меню навигации.
На странице управления доступом к API выберите "Оба ", чтобы включить доступ к службе с помощью управляемого удостоверения или с помощью ключа. При появлении запроса нажмите кнопку "Да ".
Примечание
Хотя мы будем использовать ключ API в этом упражнении, так как добавление назначений ролей может занять до 10 минут, с небольшими дополнительными усилиями вы можете включить управляемое удостоверение, назначаемое системой, для доступа к службе более безопасно.
Выберите ключи в меню навигации слева и скопируйте значение ключа первичного администратора в локальный файл. Позже в упражнении потребуются значения URL-адреса и ключа.
Выберите "Параметры->Семантический рангер" в меню навигации и убедитесь, что выбран параметр "Бесплатный".
Примечание
Чтобы проверить, доступен ли семантический рангировщик в определенном регионе, просмотрите страницу "Доступные по регионам" на веб-сайте Azure, чтобы узнать, указан ли ваш регион.
Вернитесь в диалоговое окно "Добавление данных"
и выберите созданный ресурс поиска в раскрывающемся списке Выбор ресурса поиска ИИ Azure . Если вы не видите его в списке, щелкните значок обновления рядом с раскрывающимся списком.Введите значение byod-search-index для значения имени индекса .
Установите флажок "Добавить векторный поиск" в этот ресурс поиска .
В раскрывающемся списке "Выбор модели внедрения " выберите созданную ранее модель преобразования текста ada-002 .
В диалоговом окне "Отправка файлов " нажмите кнопку "Обзор файла".
Перейдите в папку документов клиента проекта (расположенную в корне проекта) и выберите следующие файлы:
- Часы A102 Установка Instructions.docx
- FAQs.docxкомпании
Примечание
В настоящее время эта функция поддерживает следующие форматы файлов для создания локального индекса: .txt, MD, .html, .pdf, .docx и .pptx.
Выберите " Отправить файлы". Файлы будут отправлены в контейнер fileupload-byod-search-index в ресурсе хранилища BLOB-объектов, созданном ранее.
Нажмите кнопку "Рядом", чтобы перейти к диалоговому оккуму управления данными .
В раскрывающемся списке "Тип поиска" выберите "Гибридная+ семантика".
Примечание
Этот параметр обеспечивает поддержку поиска ключевых слов и векторов. После возврата результатов дополнительный процесс ранжирования применяется к результирующем набору с помощью моделей глубокого обучения, что повышает релевантность поиска для пользователя. Дополнительные сведения о семантической поиске см. в документации по семантической поиску в Azure AI .
Убедитесь, что для параметра "Выбор размера " задано значение 1024.
Нажмите кнопку "Далее".
Для типа проверки подлинности ресурсов Azure выберите ключ API. Дополнительные сведения о выборе подходящего типа проверки подлинности в документации по проверке подлинности поиска ИИ Azure.
Нажмите кнопку "Далее".
Просмотрите сведения и нажмите кнопку "Сохранить и закрыть".
После отправки пользовательских данных данные будут индексированы и доступны для использования на игровой площадке чата. Этот процесс может занять несколько минут. По завершении перейдите к следующему разделу.
Использование пользовательского источника данных на площадке чата
Найдите раздел сеанса чата страницы в Azure OpenAI Studio и введите следующий запрос пользователя:
textWhat safety rules are required to install a clock?После отправки запроса пользователя вы увидите результат, аналогичный следующему:
Разверните раздел "1 ссылки " в ответе чата и обратите внимание, что файл "Часы A102 Установка Instructions.docx " указан и вы можете выбрать его для просмотра документа.
Введите следующее сообщение пользователя:
textWhat should I do to mount the clock on the wall?Вы увидите результат, аналогичный следующему:
Теперь давайте поэкспериментируем с документом часто задаваемых вопросы о компании. Введите следующий текст в поле запроса пользователя :
textWhat is the company's policy on vacation time?Вы должны увидеть, что для этого запроса не найдена информация.
Введите следующий текст в поле запроса пользователя :
textHow should I handle refund requests?Вы увидите результат, аналогичный следующему:
Разверните раздел 1 ссылок в ответе чата и обратите внимание на то, что файл корпоративного FAQs.docx указан и вы можете выбрать его для просмотра документа.
Выберите "Просмотреть код " на панели инструментов игровой площадки чата.
Обратите внимание, что вы можете переключаться между разными языками, просматривать конечную точку и получать доступ к ключу конечной точки. Закройте диалоговое окно "Пример кода ".
Включите переключатель "Показать необработанный JSON" над сообщениями чата. Обратите внимание, что сеанс чата начинается со следующего сообщения:
JSON{ "role": "system", "content": "You are an AI assistant that helps people find information." }Теперь, когда вы создали пользовательский источник данных и поэкспериментировали с ним на игровой площадке чата, давайте посмотрим, как его можно использовать в приложении проекта.
Использование собственной функции данных в приложении
Вернитесь в проект в VS Code и откройте env-файл . Обновите следующие значения с помощью конечной точки, ключа и индекса служб ИИ. Ранее в этом упражнении вы скопировали конечную точку и ключ в локальный файл.
AZURE_AI_SEARCH_ENDPOINT=<AI_SERVICES_ENDPOINT_VALUE> AZURE_AI_SEARCH_KEY=<AI_SERVICES_KEY_VALUE> AZURE_AI_SEARCH_INDEX=byod-search-indexВ предыдущем упражнении вы запустили базу данных, API и приложение. Вы также обновили
.envфайл. Если вы не выполнили эти действия, следуйте инструкциям в конце предыдущего упражнения, прежде чем продолжить.После загрузки приложения в браузере щелкните значок справки чата в правом верхнем углу приложения.
В диалоговом окне чата должен появиться следующий текст:
textHow should I handle a company refund request?Нажмите кнопку "Получить справку ". Вы увидите результаты, возвращенные компанией FAQs.docx документ, отправленный ранее в Azure OpenAI Studio. Если вы хотите прочитать документ, его можно найти в папке документов клиента в корне проекта.
Измените текст на следующий и нажмите кнопку "Получить справку ":
textWhat safety rules are required to install a clock?Результаты, возвращенные в документе "Установка Часов A102" Instructions.docx , отправленном ранее в Azure OpenAI Studio. Этот документ также доступен в папке документов клиента в корне проекта.
Изучение кода
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Вернитесь к исходному коду проекта в Visual Studio Code.
Откройте файл сервера или apiRoutes.ts и найдите
completeBYODмаршрут. Этот API вызывается, когда в диалоговом окне справки чата выбрана кнопка "Получить справку ". Он извлекает запрос пользователя из текста запроса и передает егоcompleteBYOD()функции в файле сервера или openAI.ts . Затем результаты возвращаются клиенту.TypeScriptrouter.post('/completeBYOD', async (req, res) => { const { prompt } = req.body; if (!prompt) { return res.status(400).json({ status: false, error: 'The prompt parameter must be provided.' }); } let result; try { // Call OpenAI to get custom "bring your own data" completion result = await completeBYOD(prompt); } catch (e: unknown) { console.error('Error parsing JSON:', e); } res.json(result); });Откройте файл сервера или openAI.ts и найдите функцию
completeBYOD().TypeScriptasync function completeBYOD(userPrompt: string): Promise<string> { const systemPrompt = 'You are an AI assistant that helps people find information in documents.'; return await callOpenAI(systemPrompt, userPrompt, 0, true); }Эта функция имеет следующие функции:
- Параметр
userPromptсодержит сведения, введенные пользователем в диалоговое окно справки чата. -
systemPromptПеременная определяет, что помощник по искусственному интеллекту, предназначенный для поиска информации, будет использоваться. -
callOpenAI()используется для вызова API OpenAI Azure и возврата результатов. Он передаетsystemPromptзначения иuserPromptзначения, а также следующие параметры:-
temperature- Объем творчества, включаемого в ответ. В этом случае пользователю нужны согласованные (менее творческие) ответы, поэтому значение равно 0. -
useBYOD— логическое значение, указывающее, следует ли использовать поиск ИИ вместе с Azure OpenAI. В этом случае он установленtrueтаким образом, чтобы функция поиска ИИ использовалась.
-
- Параметр
Функция
callOpenAI()принимает параметр, используемыйuseBYODдля определения вызываемой функции OpenAI. В этом случае он задаетuseBYODзначениеtrueдляgetAzureOpenAIBYODCompletion()вызова функции.TypeScriptfunction callOpenAI(systemPrompt: string, userPrompt: string, temperature = 0, useBYOD = false) { const isAzureOpenAI = OPENAI_API_KEY && OPENAI_ENDPOINT && OPENAI_MODEL; if (isAzureOpenAI) { if (useBYOD) { return getAzureOpenAIBYODCompletion(systemPrompt, userPrompt, temperature); } return getAzureOpenAICompletion(systemPrompt, userPrompt, temperature); } return getOpenAICompletion(systemPrompt, userPrompt, temperature); }Найдите функцию
getAzureOpenAIBYODCompletion()на сервере или openAI.ts. Это довольно похоже наgetAzureOpenAICompletion()функцию, которую вы изучили ранее, но отображается как отдельная функция, чтобы выделить несколько ключевых различий, уникальных для сценария Azure OpenAI для данных, доступного в Azure OpenAI.TypeScriptasync function getAzureOpenAIBYODCompletion(systemPrompt: string, userPrompt: string, temperature: number): Promise<string> { const dataSources = [ { type: 'azure_search', parameters: { authentication: { type: 'api_key', key: AZURE_AI_SEARCH_KEY }, endpoint: AZURE_AI_SEARCH_ENDPOINT, index_name: AZURE_AI_SEARCH_INDEX } } ]; const completion = await createAzureOpenAICompletion(systemPrompt, userPrompt, temperature, dataSources) as AzureOpenAIYourDataResponse; console.log('Azure OpenAI Add Your Own Data Output: \n', completion.choices[0]?.message); for (let citation of completion.choices[0]?.message?.context?.citations ?? []) { console.log('Citation Path:', citation.filepath); } return completion.choices[0]?.message?.content?.trim() ?? ''; }Обратите внимание на следующие функции в
getAzureOpenAIBYODCompletion()функции:- Создается
dataSourcesсвойство, содержащее ресурсkeyendpointпоиска ИИ, иindex_nameзначения, добавленные в.envфайл ранее в этом упражнении. - Функция
createAzureOpenAICompletion()вызывается с помощью ,systemPromptuserPromptиtemperatureзначенийdataSources. Эта функция используется для вызова API OpenAI Azure и возврата результатов. - После возврата ответа ссылки на документ записываются в консоль. Затем содержимое сообщения завершения возвращается вызывающей объекту.
- Создается
Перед переходом к следующему упражнению следует рассмотреть несколько окончательных пунктов:
- В примере приложения используется один индекс в поиске ИИ Azure. С помощью Azure OpenAI можно использовать несколько индексов и источников данных. Свойство
dataSourcesвgetAzureOpenAIBYODCompletion()функции можно обновить, чтобы включить несколько источников данных по мере необходимости. - Безопасность должна тщательно оцениваться с помощью этого типа сценария. Пользователи не смогут задавать вопросы и получать результаты из документов, к которым они не могут получить доступ.
- В примере приложения используется один индекс в поиске ИИ Azure. С помощью Azure OpenAI можно использовать несколько индексов и источников данных. Свойство
Теперь, когда вы узнали о Azure OpenAI, запросах, завершениях и способах использования собственных данных, давайте рассмотрим следующее упражнение, чтобы узнать, как можно использовать возможности взаимодействия для улучшения приложения. Если вы хотите узнать больше о Azure OpenAI, просмотрите обучающее содержимое службы Azure OpenAI . Дополнительные сведения об использовании собственных данных с Azure OpenAI можно найти в документации по Azure OpenAI .
Обмен данными. Создание ресурса Службы коммуникации Azure
Эффективное взаимодействие важно для успешных пользовательских бизнес-приложений. С помощью Службы коммуникации Azure (ACS) вы можете добавлять такие функции, как телефонные звонки, динамический чат, аудио- и видеозвонки, а также сообщения электронной почты и SMS-сообщения в приложения. Ранее вы узнали, как Azure OpenAI может создавать завершения для сообщений электронной почты и SMS. Теперь вы узнаете, как отправлять сообщения. Вместе ACS и OpenAI могут улучшить приложения, упрощая взаимодействие, повышая взаимодействие и повышая производительность бизнеса.
В этом упражнении вы выполните следующие действия.
- Создайте ресурс Службы коммуникации Azure (ACS).
- Добавьте бесплатный номер телефона с возможностями звонков и SMS.
- Подключите домен электронной почты.
- Обновите env-файл проекта со значениями из ресурса ACS.
Создание ресурса Службы коммуникации Azure
Посетите портал Azure в браузере и войдите в систему, если вы еще не сделали этого.
Введите службы коммуникации в строке поиска в верхней части страницы и выберите службы коммуникации из параметров, которые отображаются.
Выберите "Создать " на панели инструментов.
Выполните следующие задачи:
- Выберите свою подписку Azure.
- Выберите группу ресурсов для использования (создайте новую, если она не существует).
- Введите имя ресурса ACS. Это значение должно быть уникальным.
- Выберите расположение данных.
Выберите "Рецензирование" и "Создать " и " Создать".
Вы успешно создали новый ресурс Службы коммуникации Azure! Затем вы включите возможности телефонных звонков и SMS. Вы также подключите домен электронной почты к ресурсу.
Включение возможностей звонков и SMS
Добавьте номер телефона и убедитесь, что номер телефона включен. Этот номер телефона будет использоваться для вызова телефона из приложения.
Выберите телефонию и SMS -->Телефонные номера в меню "Ресурс".
Нажмите + Получите на панели инструментов (или нажмите кнопку "Получить номер ") и введите следующие сведения:
-
Страна или регион:
United States -
Тип номера:
Toll-free
Примечание
Для создания бесплатного номера требуется кредитная карта в подписке Azure. Если у вас нет карточки в файле, вы можете пропустить добавление номера телефона и перейти к следующему разделу упражнения, которое подключает домен электронной почты. Вы по-прежнему можете использовать приложение, но не сможете вызвать номер телефона.
- Номер: выберите "Добавить в корзину" для одного из указанных номеров телефонов.
-
Страна или регион:
Нажмите кнопку "Далее", просмотрите сведения о номере телефона и нажмите кнопку "Купить".
Примечание
Проверка SMS для бесплатных номеров теперь является обязательной в США и Канаде. Чтобы включить sms-обмен сообщениями, необходимо отправить проверку после покупки номера телефона. Хотя в этом руководстве не будет выполняться этот процесс, вы можете выбрать телефонию и SMS -->Нормативные документы из меню ресурсов и добавить необходимую документацию по проверке.
После создания номера телефона выберите его, чтобы открыть панель "Компоненты ". Убедитесь, что заданы следующие значения (они должны быть заданы по умолчанию):
- В разделе "Вызовы " выберите
Make calls. - В разделе SMS выберите
Send and receive SMS. - Нажмите кнопку "Сохранить".
- В разделе "Вызовы " выберите
Скопируйте значение номера телефона в файл для последующего использования. Номер телефона должен соответствовать этому общему шаблону:
+12345678900
Подключение домена электронной почты
Выполните следующие задачи, чтобы создать подключенный домен электронной почты для ресурса ACS, чтобы отправить сообщение электронной почты. Это будет использоваться для отправки сообщения электронной почты из приложения.
- В меню "Ресурс" выберите "Электронная почта -->Домены ".
- Выберите "Подключить домен" на панели инструментов.
- Выберите свою подписку и группу ресурсов.
- В раскрывающемся списке "Служба электронной почты" выберите
Add an email service. - Присвойте службе электронной почты имя, например
acs-demo-email-service. - Выберите "Рецензирование" и "Создать" и "Создать".
- После завершения развертывания выберите
Go to resourceи выберите1-click add, чтобы добавить бесплатный поддомен Azure. - После добавления поддомена (для развертывания потребуется несколько минут), выберите его.
- Когда вы находитесь на экране AzureManagedDomain , выберите службы электронной почты -->MailFrom addresss из меню "Ресурс".
- Скопируйте значение MailFrom в файл. Вы будете использовать его позже при обновлении env-файла .
- Вернитесь к ресурсу Служб коммуникации Azure и выберите "Электронная почта->Домены" в меню ресурсов.
- Выберите
Add domainи введитеMailFromзначение на предыдущем шаге (убедитесь, что выбрана правильная подписка, группа ресурсов и служба электронной почты). Выберите кнопкуConnect.
.env Обновление файла
Теперь, когда ваш номер телефона ACS (с включенным вызовом и SMS) и домен электронной почты готовы, обновите следующие ключи/значения в env-файле проекта:
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING> ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER> ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS> CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO> CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>ACS_CONNECTION_STRINGconnection string: значение из раздела "Ключи" ресурса ACS.ACS_PHONE_NUMBER: назначьте бесплатный номер значениюACS_PHONE_NUMBER.ACS_EMAIL_ADDRESS: назначьте адрес электронной почты MailTo.CUSTOMER_EMAIL_ADDRESS: назначьте адрес электронной почты, который вы хотите отправить из приложения (так как данные клиента в базе данных приложения являются только примерами данных). Вы можете использовать личный адрес электронной почты.CUSTOMER_PHONE_NUMBER: Вам потребуется указать номер телефона на основе США (по состоянию на сегодняшний день) из-за дополнительной проверки, необходимой в других странах или регионах для отправки SMS-сообщений. Если у вас нет номера на основе США, его можно оставить пустым.
Запуск и перезапуск серверов приложений и API
Выполните одно из следующих действий на основе упражнений, которые вы выполнили до этой точки:
Если вы запустили базу данных, сервер API и веб-сервер в предыдущем упражнении, необходимо остановить сервер API и веб-сервер и перезапустить их, чтобы получить изменения в env-файле . Базу данных можно оставить запущенной.
Найдите окна терминала с сервером API и веб-сервером и нажмите клавиши CTRL+C , чтобы остановить их. Запустите их снова, введя
npm startв каждом окне терминала и нажав клавишу ВВОД. Перейдите к следующему упражнению.Если вы еще не запустили базу данных, сервер API и веб-сервер, выполните следующие действия.
В следующих шагах вы создадите три окна терминала в Visual Studio Code.
Щелкните правой кнопкой мыши env-файл в списке файлов Visual Studio Code и выберите "Открыть в интегрированном терминале". Перед продолжением убедитесь, что терминал находится в корне проекта — openai-acs-msgraph .
Выберите один из следующих параметров, чтобы запустить базу данных PostgreSQL:
Если установлен и запущен Docker Desktop , запустите
docker-compose upв окне терминала и нажмите клавишу ВВОД.Если у вас есть Podman с установленным и запущенным podman-compose , запустите
podman-compose upв окне терминала и нажмите клавишу ВВОД.Чтобы запустить контейнер PostgreSQL непосредственно с помощью Docker Desktop, Podman, nerdctl или другой установленной среды выполнения контейнера, выполните следующую команду в окне терминала:
Mac, Linux или подсистема Windows для Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgresWindows с PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
После запуска контейнера базы данных нажмите + значок на панели инструментов терминала Visual Studio Code, чтобы создать второе окно терминала.
cdв папку server/typescript и выполните следующие команды, чтобы установить зависимости и запустить сервер API.npm installnpm start
+ Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
cdв папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.npm installnpm start
Откроется браузер, в который вы http://localhost:4200перейдете.
Обмен данными: звонок по телефону
Интеграция возможностей звонков Службы коммуникации Azure в пользовательское бизнес-приложение предлагает несколько ключевых преимуществ для бизнеса и их пользователей:
- Обеспечивает бесшовное и реальное время взаимодействие между сотрудниками, клиентами и партнерами непосредственно из бизнес-приложения, устраняя необходимость переключения между несколькими платформами или устройствами.
- Улучшает взаимодействие с пользователем и повышает общую эффективность работы.
- Упрощает быстрое решение проблем, так как пользователи могут быстро подключаться к соответствующим командам поддержки или экспертам по темам быстро и легко.
В этом упражнении вы выполните следующие действия.
- Изучите функцию звонков по телефону в приложении.
- Ознакомьтесь с кодом, чтобы узнать, как создается функция звонков по телефону.
Использование функции звонков по телефону
В предыдущем упражнении вы создали ресурс Служб коммуникации Azure (ACS) и запустили базу данных, веб-сервер и сервер API. Вы также обновили следующие значения в env-файле .
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING> ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER> ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS> CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO> CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>Прежде чем продолжить, убедитесь, что вы выполнили предыдущее упражнение .
Вернитесь в браузер (http://localhost:4200), найдите datagrid и выберите "Связаться с клиентом ", а затем вызов клиента в первой строке.
Компонент телефонного звонка будет добавлен в заголовок. Введите номер телефона, который вы хотите позвонить (убедитесь, что он начинается с + и включает код страны) и выберите "Звонок". Вам будет предложено разрешить доступ к микрофону.
Выберите "Зависнуть" , чтобы завершить вызов. Нажмите кнопку "Закрыть", чтобы закрыть компонент телефонного звонка.
Изучение кода звонков по телефону
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Откройте файл customers-list.component.ts . Полный путь к файлу — client/src/app/customers-list/customers-list.component.ts.
Обратите внимание, что
openCallDialog()отправляетCustomerCallсообщение и номер телефона клиента с помощью шины событий.TypeScriptopenCallDialog(data: Phone) { this.eventBus.emit({ name: Events.CustomerCall, value: data }); }Примечание
Код шины событий можно найти в файле eventbus.service.ts , если вы заинтересованы в его изучении. Полный путь к файлу — client/src/app/core/eventbus.service.ts.
Функция компонента заголовка
ngOnInit()подписывается наCustomerCallсобытие, отправленное шиной событий, и отображает компонент телефонного звонка. Этот код можно найти в header.component.ts.TypeScriptngOnInit() { this.subscription.add( this.eventBus.on(Events.CustomerCall, (data: Phone) => { this.callVisible = true; // Show phone call component this.callData = data; // Set phone number to call }) ); }Откройте phone-call.component.ts. На некоторое время, чтобы разоблачить код. Полный путь к файлу — client/src/app/phone-call/phone-call.component.ts. Обратите внимание на следующие ключевые функции:
- Извлекает маркер доступа Службы коммуникации Azure путем вызова
acsService.getAcsToken()функции вngOnInit(); - Добавляет на страницу "телефонный абонент". Вы можете увидеть абонент, щелкнув входной номер телефона в заголовке.
- Запускает и завершает вызов, используя
startCall()функции соответственноendCall().
- Извлекает маркер доступа Службы коммуникации Azure путем вызова
Прежде чем изучить код, который делает телефонный звонок, давайте рассмотрим, как извлекается маркер доступа ACS и как создаются объекты звонков по телефону. Найдите функцию
ngOnInit()в phone-call.component.ts.TypeScriptasync ngOnInit() { if (ACS_CONNECTION_STRING) { this.subscription.add( this.acsService.getAcsToken().subscribe(async (user: AcsUser) => { const callClient = new CallClient(); const tokenCredential = new AzureCommunicationTokenCredential(user.token); this.callAgent = await callClient.createCallAgent(tokenCredential); }) ); } }Эта функция выполняет следующие действия:
- Извлекает идентификатор пользователя ACS и маркер доступа, вызывая функцию
acsService.getAcsToken(). - После получения маркера доступа код выполняет следующие действия:
- Создает новый экземпляр
CallClientиAzureCommunicationTokenCredentialиспользование маркера доступа. - Создает новый экземпляр
CallAgentс помощьюCallClientобъектов иAzureCommunicationTokenCredentialобъектов. Позже вы увидите, чтоCallAgentиспользуется для запуска и завершения вызова.
- Создает новый экземпляр
- Извлекает идентификатор пользователя ACS и маркер доступа, вызывая функцию
Откройте acs.services.ts и найдите функцию
getAcsToken(). Полный путь к файлу — client/src/app/core/acs.service.ts. Функция выполняет HTTP-запрос GET к маршруту, предоставляемому/acstokenсервером API.TypeScriptgetAcsToken(): Observable<AcsUser> { return this.http.get<AcsUser>(this.apiUrl + 'acstoken') .pipe( catchError(this.handleError) ); }Функция сервера API с именем
createACSToken()извлекает идентификатор пользователя и маркер доступа и возвращает его клиенту. Его можно найти в файле server/typescript/acs.ts .TypeScriptimport { CommunicationIdentityClient } from '@azure/communication-identity'; const connectionString = process.env.ACS_CONNECTION_STRING as string; async function createACSToken() { if (!connectionString) return { userId: '', token: '' }; const tokenClient = new CommunicationIdentityClient(connectionString); const { user, token } = await tokenClient.createUserAndToken(["voip"]); return { userId: user.communicationUserId, token }; }Эта функция выполняет следующие действия:
- Проверяет, доступно ли значение ACS
connectionString. В противном случае возвращает объект с пустымuserIdиtoken. - Создает новый экземпляр
CommunicationIdentityClientи передаетconnectionStringв него значение. - Создает пользователя и маркер, используя
tokenClient.createUserAndToken()область voip. - Возвращает объект,
userIdсодержащий значения иtokenзначения.
- Проверяет, доступно ли значение ACS
Теперь, когда вы узнали, как извлекается идентификатор пользователя и маркер, вернитесь к
phone-call.component.tsфункции и найдите ееstartCall().Эта функция вызывается при выборе звонка в компоненте телефонного звонка. Он использует объект, упомянутый
CallAgentранее, для запуска вызова. ФункцияcallAgent.startCall()принимает объект, представляющий номер для вызова и номер телефона ACS, используемый для вызова.TypeScriptstartCall() { this.call = this.callAgent?.startCall( [{ phoneNumber: this.customerPhoneNumber }], { alternateCallerId: { phoneNumber: this.fromNumber } }); console.log('Calling: ', this.customerPhoneNumber); console.log('Call id: ', this.call?.id); this.inCall = true; // Adding event handlers to monitor call state this.call?.on('stateChanged', () => { console.log('Call state changed: ', this.call?.state); if (this.call?.state === 'Disconnected') { console.log('Call ended. Reason: ', this.call.callEndReason); this.inCall = false; } }); }Функция
endCall()вызывается при выборе функции "Зависание" в компоненте телефонного звонка.TypeScriptendCall() { if (this.call) { this.call.hangUp({ forEveryone: true }); this.call = undefined; this.inCall = false; } else { this.hangup.emit(); } }Если вызов выполняется,
call.hangUp()функция вызывается для завершения вызова. Если вызов не выполняется,hangupсобытие создается родительскому компоненту заголовка, чтобы скрыть компонент телефонного звонка.Прежде чем перейти к следующему упражнению, давайте рассмотрим основные понятия, описанные в этом упражнении:
- Идентификатор пользователя ACS и маркер доступа извлекаются с сервера API с помощью
acsService.createUserAndToken()функции. - Маркер используется для создания
CallClientиCallAgentобъекта. - Объект
CallAgentиспользуется для запуска и завершения вызова путем вызоваcallAgent.startCall()иcallAgent.hangUp()функций соответственно.
- Идентификатор пользователя ACS и маркер доступа извлекаются с сервера API с помощью
Теперь, когда вы узнали, как можно интегрировать телефонные звонки в приложение, давайте переключим наше внимание на использование Службы коммуникации Azure для отправки сообщений электронной почты и SMS.
Коммуникация: отправка сообщений электронной почты и SMS
Помимо телефонных звонков, Службы коммуникации Azure также могут отправлять сообщения электронной почты и SMS. Это может быть полезно, если вы хотите отправить сообщение клиенту или другому пользователю непосредственно из приложения.
В этом упражнении вы выполните следующие действия.
- Узнайте, как отправлять сообщения электронной почты и SMS из приложения.
- Ознакомьтесь с кодом, чтобы узнать, как реализована функция электронной почты и SMS.
Использование функций электронной почты и SMS
В предыдущем упражнении вы создали ресурс Служб коммуникации Azure (ACS) и запустили базу данных, веб-сервер и сервер API. Вы также обновили следующие значения в env-файле .
ACS_CONNECTION_STRING=<ACS_CONNECTION_STRING> ACS_PHONE_NUMBER=<ACS_PHONE_NUMBER> ACS_EMAIL_ADDRESS=<ACS_EMAIL_ADDRESS> CUSTOMER_EMAIL_ADDRESS=<EMAIL_ADDRESS_TO_SEND_EMAIL_TO> CUSTOMER_PHONE_NUMBER=<UNITED_STATES_BASED_NUMBER_TO_SEND_SMS_TO>Прежде чем продолжить, убедитесь, что вы выполнили упражнение.
Вернитесь в браузер (http://localhost:4200) и выберите "Связаться с клиентом ", а затем "Электронная почта/SMS" в первой строке.
Перейдите на вкладку "Электронная почта/SMS" и выполните следующие задачи:
- Введите тему и текст электронной почты и нажмите кнопку "Отправить электронную почту ".
- Введите SMS-сообщение и нажмите кнопку "Отправить SMS ".
Примечание
Проверка SMS для бесплатных номеров теперь является обязательной в США и Канаде. Чтобы включить sms-обмен сообщениями, необходимо отправить проверку после покупки номера телефона. Хотя в этом руководстве не будет выполняться этот процесс, вы можете выбрать телефонию и SMS -->Нормативные документы из ресурса Служб коммуникации Azure на портале Azure и добавить необходимую документацию по проверке.
Убедитесь, что вы получили сообщения электронной почты и SMS. Функция SMS будет работать только в том случае, если вы отправили нормативные документы, упомянутые в предыдущем примечание. Как напоминание, сообщение электронной почты будет отправлено в значение, определенное для
CUSTOMER_EMAIL_ADDRESSCUSTOMER_PHONE_NUMBER, и SMS-сообщение будет отправлено в значение, определенное в env-файле . Если вы не смогли указать номер телефона на основе США, используемый для SMS-сообщений, можно пропустить этот шаг.Примечание
Если вы не видите сообщение электронной почты в папке "Входящие" для адреса, определенного
CUSTOMER_EMAIL_ADDRESSв env-файле , проверьте папку нежелательной почты.
Изучение кода электронной почты
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Откройте файл customers-list.component.ts . Полный путь к файлу — client/src/app/customers-list/customers-list.component.ts.
При выборе клиента контакта , за которым следует email/SMS Customer в datagrid,
customer-listкомпонент отображает диалоговое окно. Это обрабатывается функциейopenEmailSmsDialog()в файле customer-list.component.ts .TypeScriptopenEmailSmsDialog(data: any) { if (data.phone && data.email) { // Create the data for the dialog let dialogData: EmailSmsDialogData = { prompt: '', title: `Contact ${data.company}`, company: data.company, customerName: data.first_name + ' ' + data.last_name, customerEmailAddress: data.email, customerPhoneNumber: data.phone } // Open the dialog const dialogRef = this.dialog.open(EmailSmsDialogComponent, { data: dialogData }); // Subscribe to the dialog afterClosed observable to get the dialog result this.subscription.add( dialogRef.afterClosed().subscribe((response: EmailSmsDialogData) => { console.log('SMS dialog result:', response); if (response) { dialogData = response; } }) ); } else { alert('No phone number available.'); } }Функция
openEmailSmsDialog()выполняет следующие задачи:- Проверяет, содержит
dataлиphoneобъект (который представляет строку из datagrid) иemailсвойство. Если это так, он создаетdialogDataобъект, содержащий сведения для передачи в диалоговое окно. - Открывает диалоговое
EmailSmsDialogComponentокно и передаетdialogDataобъект в него. - Подписывается на
afterClosed()событие диалогового окна. Это событие запускается при закрытии диалогового окна. Объектresponseсодержит сведения, введенные в диалоговое окно.
- Проверяет, содержит
Откройте файл email-sms-dialog.component.ts . Полный путь к файлу — client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
Найдите функцию
sendEmail():TypeScriptsendEmail() { if (this.featureFlags.acsEmailEnabled) { // Using CUSTOMER_EMAIL_ADDRESS instead of this.data.email for testing purposes this.subscription.add( this.acsService.sendEmail(this.emailSubject, this.emailBody, this.getFirstName(this.data.customerName), CUSTOMER_EMAIL_ADDRESS /* this.data.email */) .subscribe(res => { console.log('Email sent:', res); if (res.status) { this.emailSent = true; } }) ); } else { this.emailSent = true; // Used when ACS email isn't enabled } }Функция
sendEmail()выполняет следующие задачи:- Проверяет, установлен
acsEmailEnabledлиtrueфлаг компонента. Этот флаг проверяет, имеет лиACS_EMAIL_ADDRESSпеременная среды присвоенное значение. - Если
acsEmailEnabledзадано значение true,acsService.sendEmail()функция вызывается и передается тема электронной почты, текст, имя клиента и адрес электронной почты клиента. Так как база данных содержит примеры данных,CUSTOMER_EMAIL_ADDRESSпеременная среды используется вместоthis.data.email. В реальном приложенииthis.data.emailбудет использоваться значение. - Подписывается на
sendEmail()функцию вacsServiceслужбе. Эта функция возвращает наблюдаемый RxJS, содержащий ответ от клиентской службы. - Если сообщение было отправлено успешно,
emailSentдля свойства заданоtrueзначение .
- Проверяет, установлен
Для улучшения инкапсуляции кода и повторного использования клиентские службы, такие как acs.service.ts , используются во всем приложении. Это позволяет объединить все функциональные возможности ACS в одно место.
Откройте acs.service.ts и найдите функцию
sendEmail(). Полный путь к файлу — client/src/app/core/acs.service.ts.TypeScriptsendEmail(subject: string, message: string, customerName: string, customerEmailAddress: string) : Observable<EmailSmsResponse> { return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendEmail', { subject, message, customerName, customerEmailAddress }) .pipe( catchError(this.handleError) ); }Функция
sendEmail()выполняетAcsServiceследующие задачи:-
http.post()Вызывает функцию и передает тему электронной почты, сообщение, имя клиента и адрес электронной почты клиента. Функцияhttp.post()возвращает наблюдаемый RxJS, содержащий ответ из вызова API. - Обрабатывает все ошибки, возвращаемые
http.post()функцией с помощью оператора RxJScatchError.
-
Теперь давайте рассмотрим, как приложение взаимодействует с функцией электронной почты ACS. Откройте файл acs.ts и найдите функцию
sendEmail(). Полный путь к файлу — server/typescript/acs.ts.Функция
sendEmail()выполняет следующие задачи:Создает новый
EmailClientобъект и передает в него строка подключения ACS (это значение извлекается из переменнойACS_CONNECTION_STRINGсреды).TypeScriptconst emailClient = new EmailClient(connectionString);Создает новый
EmailMessageобъект и передает сведения отправителя, субъекта, сообщения и получателя.TypeScriptconst msgObject: EmailMessage = { senderAddress: process.env.ACS_EMAIL_ADDRESS as string, content: { subject: subject, plainText: message, }, recipients: { to: [ { address: customerEmailAddress, displayName: customerName, }, ], }, };Отправляет сообщение электронной почты с помощью
emailClient.beginSend()функции и возвращает ответ. Хотя функция отправляется только одному получателю в этом примере,beginSend()эта функция также может использоваться для отправки нескольким получателям.TypeScriptconst poller = await emailClient.beginSend(msgObject);Ожидает, пока
pollerобъект будет сигнализировать о завершении и отправляет ответ вызывающему объекту.
Изучение SMS-кода
Вернитесь к файлу email-sms-dialog.component.ts , который вы открыли ранее. Полный путь к файлу — client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
Найдите функцию
sendSms():TypeScriptsendSms() { if (this.featureFlags.acsPhoneEnabled) { // Using CUSTOMER_PHONE_NUMBER instead of this.data.customerPhoneNumber for testing purposes this.subscription.add( this.acsService.sendSms(this.smsMessage, CUSTOMER_PHONE_NUMBER /* this.data.customerPhoneNumber */) .subscribe(res => { if (res.status) { this.smsSent = true; } }) ); } else { this.smsSent = true; } }Функция
sendSMS()выполняет следующие задачи:- Проверяет, установлен
acsPhoneEnabledлиtrueфлаг компонента. Этот флаг проверяет, имеет лиACS_PHONE_NUMBERпеременная среды присвоенное значение. - Если
acsPhoneEnabledзадано значение true, функция вызывается,acsService.SendSms()а sms-сообщение и номер телефона клиента передаются. Так как база данных содержит примеры данных,CUSTOMER_PHONE_NUMBERпеременная среды используется вместоthis.data.customerPhoneNumber. В реальном приложенииthis.data.customerPhoneNumberбудет использоваться значение. - Подписывается на
sendSms()функцию вacsServiceслужбе. Эта функция возвращает наблюдаемый RxJS, содержащий ответ от клиентской службы. - Если SMS-сообщение было отправлено успешно, оно задает
smsSentдля свойстваtrueзначение .
- Проверяет, установлен
Откройте acs.service.ts и найдите функцию
sendSms(). Полный путь к файлу — client/src/app/core/acs.service.ts.TypeScriptsendSms(message: string, customerPhoneNumber: string) : Observable<EmailSmsResponse> { return this.http.post<EmailSmsResponse>(this.apiUrl + 'sendSms', { message, customerPhoneNumber }) .pipe( catchError(this.handleError) ); }Функция
sendSms()выполняет следующие задачи:-
http.post()Вызывает функцию и передает ему номер телефона и сообщения. Функцияhttp.post()возвращает наблюдаемый RxJS, содержащий ответ из вызова API. - Обрабатывает все ошибки, возвращаемые
http.post()функцией с помощью оператора RxJScatchError.
-
Наконец, давайте рассмотрим, как приложение взаимодействует с функцией SMS ACS. Откройте файл acs.ts . Полный путь к файлу — server/typescript/acs.ts и найдите функцию
sendSms().Функция
sendSms()выполняет следующие задачи:Создает новый
SmsClientобъект и передает в него строка подключения ACS (это значение извлекается из переменнойACS_CONNECTION_STRINGсреды).TypeScriptconst smsClient = new SmsClient(connectionString);smsClient.send()Вызывает функцию и передает номер телефона ACS (), номер телефона клиента (fromto) и SMS-сообщение:TypeScriptconst sendResults = await smsClient.send({ from: process.env.ACS_PHONE_NUMBER as string, to: [customerPhoneNumber], message: message }); return sendResults;Возвращает ответ вызывающего абонента.
Дополнительные сведения о функциях электронной почты ACS и SMS см. в следующих статьях:
Прежде чем перейти к следующему упражнению, давайте рассмотрим основные понятия, описанные в этом упражнении:
- Файл acs.service.ts инкапсулирует функции электронной почты ACS и SMS, используемые клиентским приложением. Он обрабатывает вызовы API к серверу и возвращает ответ вызывающему объекту.
- API на стороне сервера использует ACS
EmailClientиSmsClientобъекты для отправки сообщений электронной почты и SMS.
Теперь, когда вы узнали, как можно отправлять сообщения электронной почты и SMS, давайте переключим наше внимание на интеграцию данных организации в приложение.
Организационные данные: создание регистрации приложения идентификатора Записи Майкрософт
Повышение производительности пользователей путем интеграции данных организации (сообщений электронной почты, файлов, чатов и событий календаря) непосредственно в пользовательские приложения. Используя API Microsoft Graph и идентификатор Microsoft Entra, вы можете легко получать и отображать соответствующие данные в приложениях, уменьшая потребность пользователей в переключении контекста. Указывает, ссылается ли сообщение электронной почты, отправленное клиенту, просмотр сообщения Teams или доступ к файлу, пользователи могут быстро найти нужную информацию, не выходя из приложения, оптимизируя процесс принятия решений.
В этом упражнении вы выполните следующие действия.
- Создайте регистрацию приложения идентификатора Microsoft Entra, чтобы Microsoft Graph смог получить доступ к данным организации и перенести его в приложение.
- Поиск
teamиchannelидентификаторы из Microsoft Teams, необходимые для отправки сообщений чата в определенный канал. - Обновите env-файл проекта со значениями из регистрации приложения идентификатора Microsoft Entra.
Создание регистрации приложений идентификатора записи Майкрософт
Перейдите на портал Azure и выберите идентификатор Microsoft Entra.
Выберите "Управлениерегистрацией -->App", а затем + Новая регистрация.
Введите сведения о новой форме регистрации приложения, как показано ниже, и нажмите кнопку "Зарегистрировать".
- Имя: microsoft-graph-app
- Поддерживаемые типы учетных записей: учетные записи в любом каталоге организации (любой клиент идентификатора Microsoft Entra — Multitenant)
- URI перенаправления:
- Выберите одностраничные приложения (SPA) и введите
http://localhost:4200в поле URI перенаправления .
- Выберите одностраничные приложения (SPA) и введите
- Выберите "Регистрация", чтобы создать регистрацию приложения.
Выберите "Обзор" в меню ресурсов и скопируйте
Application (client) IDзначение в буфер обмена.
Обновление env-файла проекта
Откройте env-файл в редакторе и присвойте ему
Application (client) IDзначениеENTRAID_CLIENT_ID.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE>Если вы хотите включить возможность отправки сообщения из приложения в канал Teams, войдите в Microsoft Teams с помощью учетной записи клиента разработки Microsoft 365 (это упоминается в предварительном запросе для руководства).
После входа разверните команду и найдите канал, в который нужно отправить сообщения из приложения. Например, можно выбрать команду компании и канал "Общие " (или любой другой командой или каналом, который вы хотите использовать).
В заголовке команды щелкните три точки (...) и выберите "Получить ссылку на команду".
В появившемся окне ссылки идентификатор команды — это строка букв и чисел после
team/. Например, в ссылке "https://teams.microsoft.com/l/team/19%3ae9b9.../"идентификатор команды равен 19%3ae9b9... до следующего/символа.Скопируйте идентификатор команды и назначьте его
TEAM_IDв env-файле .В заголовке канала щелкните три точки (...) и выберите "Получить ссылку на канал".
В всплывающем окне отображается ссылка, идентификатор канала — это строка букв и чисел после
channel/. Например, в ссылке "https://teams.microsoft.com/l/channel/19%3aQK02.../"идентификатор канала равен 19%3aQK02... до следующего/символа.Скопируйте идентификатор канала и назначьте его
CHANNEL_IDв env-файле .Сохраните env-файл перед продолжением.
Запуск и перезапуск серверов приложений и API
Выполните одно из следующих действий на основе упражнений, которые вы выполнили до этой точки:
Если вы запустили базу данных, сервер API и веб-сервер в предыдущем упражнении, необходимо остановить сервер API и веб-сервер и перезапустить их, чтобы получить изменения в env-файле . Базу данных можно оставить запущенной.
Найдите окна терминала с сервером API и веб-сервером и нажмите клавиши CTRL+C , чтобы остановить их. Запустите их снова, введя
npm startв каждом окне терминала и нажав клавишу ВВОД. Перейдите к следующему упражнению.Если вы еще не запустили базу данных, сервер API и веб-сервер, выполните следующие действия.
В следующих шагах вы создадите три окна терминала в Visual Studio Code.
Щелкните правой кнопкой мыши env-файл в списке файлов Visual Studio Code и выберите "Открыть в интегрированном терминале". Перед продолжением убедитесь, что терминал находится в корне проекта — openai-acs-msgraph .
Выберите один из следующих параметров, чтобы запустить базу данных PostgreSQL:
Если установлен и запущен Docker Desktop , запустите
docker-compose upв окне терминала и нажмите клавишу ВВОД.Если у вас есть Podman с установленным и запущенным podman-compose , запустите
podman-compose upв окне терминала и нажмите клавишу ВВОД.Чтобы запустить контейнер PostgreSQL непосредственно с помощью Docker Desktop, Podman, nerdctl или другой установленной среды выполнения контейнера, выполните следующую команду в окне терминала:
Mac, Linux или подсистема Windows для Linux (WSL):
[docker | podman | nerdctl] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v $(pwd)/data:/var/lib/postgresql/data -p 5432:5432 postgresWindows с PowerShell:
[docker | podman] run --name postgresDb -e POSTGRES_USER=web -e POSTGRES_PASSWORD=web-password -e POSTGRES_DB=CustomersDB -v ${PWD}/data:/var/lib/postgresql/data -p 5432:5432 postgres
После запуска контейнера базы данных нажмите + значок на панели инструментов терминала Visual Studio Code, чтобы создать второе окно терминала.
cdв папку server/typescript и выполните следующие команды, чтобы установить зависимости и запустить сервер API.npm installnpm start
+ Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
cdв папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.npm installnpm start
Откроется браузер, в который вы http://localhost:4200перейдете.
Организационные данные: вход пользователя и получение маркера доступа
Пользователям необходимо пройти проверку подлинности с помощью идентификатора Microsoft Entra, чтобы Microsoft Graph получить доступ к данным организации. В этом упражнении вы узнаете, как компонент Microsoft Graph Toolkit mgt-login можно использовать для проверки подлинности пользователей и получения маркера доступа. Затем маркер доступа можно использовать для вызова Microsoft Graph.
Примечание
Если вы не знакомы с Microsoft Graph, вы можете узнать больше об этом в схеме обучения Microsoft Graph.
В этом упражнении вы выполните следующие действия.
- Узнайте, как связать приложение Идентификатора Microsoft Entra с Microsoft Graph Toolkit для проверки подлинности пользователей и получения данных организации.
- Узнайте о важности областей.
- Узнайте, как компонент mgt-login Microsoft Graph Toolkit можно использовать для проверки подлинности пользователей и получения маркера доступа.
Использование функции входа
В предыдущем упражнении вы создали регистрацию приложения в идентификаторе Microsoft Entra и запустили сервер приложений и сервер API. Вы также обновили следующие значения в
.envфайле (TEAM_IDиCHANNEL_IDявляются необязательными):ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>Прежде чем продолжить, убедитесь, что вы выполнили предыдущее упражнение .
Вернитесь в браузер (http://localhost:4200), выберите вход в заголовок и войдите с помощью учетной записи пользователя администратора из клиента разработчика Microsoft 365.
Совет
Войдите с помощью учетной записи администратора клиента разработчика Microsoft 365. Вы можете просмотреть других пользователей в клиенте разработчика, перейдя в Центр администрирования Microsoft 365.
Если вы впервые вошли в приложение, вам будет предложено предоставить согласие на разрешения, запрошенные приложением. Дополнительные сведения об этих разрешениях (также называемых "областями") см. в следующем разделе при изучении кода. Нажмите кнопку "Принять ", чтобы продолжить.
После входа в систему вы увидите имя пользователя, отображаемого в заголовке.
Изучение кода входа
Теперь, когда вы вошли, давайте рассмотрим код, используемый для входа пользователя и получения маркера доступа и профиля пользователя. Вы узнаете о веб-компоненте mgt-login , который входит в состав Microsoft Graph Toolkit.
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Откройте клиент илиpackage.json и обратите внимание, что
@microsoft/mgtв зависимости включены и@microsoft/mgt-componentsпакеты. Пакет@microsoft/mgtсодержит функции поставщика MSAL (библиотека проверки подлинности Майкрософт) и веб-компоненты, такие как mgt-login и другие, которые можно использовать для входа пользователей и получения и отображения данных организации.Откройте клиент или src/main.ts и обратите внимание на следующие импорты из
@microsoft/mgt-componentsпакета. Импортированные символы используются для регистрации компонентов Microsoft Graph Toolkit, используемых в приложении.TypeScriptimport { registerMgtLoginComponent, registerMgtSearchResultsComponent, registerMgtPersonComponent, } from '@microsoft/mgt-components';Прокрутите внизу файла и запишите следующий код:
TypeScriptregisterMgtLoginComponent(); registerMgtSearchResultsComponent(); registerMgtPersonComponent();Этот код регистрирует
mgt-loginиmgt-search-resultsвеб-компоненты иmgt-personвключает их для использования в приложении.Чтобы использовать компонент mgt-login для входа пользователей, необходимо ссылаться на и использовать идентификатор клиента приложения Microsoft Entra ID (хранящегося в env-файле как
ENTRAID_CLIENT_ID).Откройте graph.service.ts и найдите функцию
init(). Полный путь к файлу — client/src/app/core/graph.service.ts. Вы увидите следующий импорт и код:TypeScriptimport { Msal2Provider, Providers, ProviderState } from '@microsoft/mgt'; init() { if (!this.featureFlags.microsoft365Enabled) return; if (!Providers.globalProvider) { console.log('Initializing Microsoft Graph global provider...'); Providers.globalProvider = new Msal2Provider({ clientId: ENTRAID_CLIENT_ID, scopes: ['User.Read', 'Presence.Read', 'Chat.ReadWrite', 'Calendars.Read', 'ChannelMessage.Read.All', 'ChannelMessage.Send', 'Files.Read.All', 'Mail.Read'] }); } else { console.log('Global provider already initialized'); } }Этот код создает новый
Msal2Providerобъект, передав идентификатор клиента Microsoft Entra ID из регистрации приложения, аscopesтакже идентификатор, для которого приложение запрашивает доступ. Ониscopesиспользуются для запроса доступа к ресурсам Microsoft Graph, к которым будет обращаться приложение.Msal2ProviderПосле создания объекта он назначаетсяProviders.globalProviderобъекту, который используется компонентами Microsoft Graph Toolkit для получения данных из Microsoft Graph.Откройте header.component.html в редакторе и найдите компонент mgt-login . Полный путь к файлу — client/src/app/header/header.component.html.
HTML@if (this.featureFlags.microsoft365Enabled) { <mgt-login class="mgt-dark" (loginCompleted)="loginCompleted()"></mgt-login> }Компонент mgt-login включает вход пользователя и предоставляет доступ к маркеру, используемому с Microsoft Graph. После успешного входа
loginCompletedсобытие активируется, которое вызывает функциюloginCompleted(). Хотя mgt-login используется в компоненте Angular в этом примере, он совместим с любым веб-приложением.Отображение компонента mgt-login зависит от заданного
featureFlags.microsoft365Enabledtrueзначения. Этот пользовательский флаг проверяет наличие переменнойENTRAID_CLIENT_IDсреды, чтобы убедиться, что приложение правильно настроено и может пройти проверку подлинности в идентификаторе Microsoft Entra. Флаг добавляется для размещения случаев, когда пользователи предпочитают выполнять только упражнения ИИ или коммуникации в рамках руководства, а не после всей последовательности упражнений.Откройте header.component.ts и найдите функцию
loginCompleted. Эта функция вызывается, когдаloginCompletedсобытие создается и обрабатывает извлечение вошедшего в систему профиля пользователя с помощьюProviders.globalProvider.TypeScriptasync loginCompleted() { const me = await Providers.globalProvider.graph.client.api('me').get(); this.userLoggedIn.emit(me); }В этом примере вызов выполняется в API Microsoft Graph
meдля получения профиля пользователя (meпредставляет текущего вошедшего пользователя). Операторthis.userLoggedIn.emit(me)кода выдает событие из компонента для передачи данных профиля родительскому компоненту. Родительский компонент — это app.component.ts файл в данном случае, который является корневым компонентом для приложения.Дополнительные сведения о компоненте mgt-login см. в документации по Microsoft Graph Toolkit .
Теперь, когда вы вошли в приложение, давайте рассмотрим, как можно получить данные организации.
Организационные данные: получение файлов, чатов и отправки сообщений в Teams
В современной цифровой среде пользователи работают с широким набором данных организации, включая сообщения электронной почты, чаты, файлы, события календаря и многое другое. Это может привести к частым сменам контекста — переключению между задачами или приложениями, что может нарушить фокус и снизить производительность. Например, пользователю, работающему над проектом, может потребоваться переключиться с текущего приложения в Outlook, чтобы найти важные сведения в сообщении электронной почты или переключиться на OneDrive для бизнеса, чтобы найти связанный файл. Это действие назад и вперед нарушает фокус и тратит время, которое может быть лучше потрачено на задачу на руку.
Чтобы повысить эффективность, вы можете интегрировать организационные данные непосредственно в приложения, которые пользователи используют ежедневно. Путем привлечения данных организации к приложениям пользователи могут получать доступ к информации и управлять ими более просто, минимизируя сдвиги контекста и повышая производительность. Кроме того, эта интеграция предоставляет ценные аналитические сведения и контекст, что позволяет пользователям принимать обоснованные решения и эффективно работать.
В этом упражнении вы выполните следующие действия.
- Узнайте, как веб-компонент mgt-search-results в Microsoft Graph Toolkit можно использовать для поиска файлов.
- Узнайте, как вызвать Microsoft Graph непосредственно для получения файлов из OneDrive для бизнеса и сообщений чата из Microsoft Teams.
- Узнайте, как отправлять сообщения чата в каналы Microsoft Teams с помощью Microsoft Graph.
Использование функции данных организации
В предыдущем упражнении вы создали регистрацию приложения в идентификаторе Microsoft Entra и запустили сервер приложений и сервер API. Вы также обновили следующие значения в
.envфайле.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>Прежде чем продолжить, убедитесь, что вы выполнили предыдущее упражнение .
Вернитесь в браузер (http://localhost:4200). Если вы еще не вошли, выберите вход в заголовок и войдите с помощью пользователя из клиента разработчика Microsoft 365.
Примечание
Помимо проверки подлинности пользователя, веб-компонент mgt-login также получает маркер доступа, который может использоваться Microsoft Graph для доступа к файлам, чатам, сообщениям электронной почты, событиям календаря и другим данным организации. Маркер доступа содержит области (разрешения), такие как
Chat.ReadWrite,Files.Read.Allи другие, которые вы видели ранее:TypeScriptProviders.globalProvider = new Msal2Provider({ clientId: ENTRAID_CLIENT_ID, // retrieved from .env file scopes: ['User.Read', 'Presence.Read', 'Chat.ReadWrite', 'Calendars.Read', 'ChannelMessage.Read.All', 'ChannelMessage.Send', 'Files.Read.All', 'Mail.Read'] });Выберите "Просмотреть связанное содержимое " для строки Adatum Corporation в datagrid. Это приведет к получению данных организации, таких как файлы, чаты, сообщения электронной почты и события календаря с помощью Microsoft Graph. После загрузки данных он будет отображаться под datagrid в интерфейсе табуляции. Важно отметить, что на данный момент вы не видите никаких данных, так как вы еще не добавили какие-либо файлы, чаты, сообщения электронной почты или события календаря для пользователя в клиенте разработчика Microsoft 365. Давайте исправим это на следующем шаге.
На этом этапе у клиента Microsoft 365 могут не быть связанные данные организации для корпорации Adatum . Чтобы добавить некоторые примеры данных, выполните по крайней мере одно из следующих действий:
Добавьте файлы, посещая https://onedrive.com и выполнив вход с помощью учетных данных клиента разработчика Microsoft 365.
- Выберите "Мои файлы " в области навигации слева.
- Выберите +Добавить новую , а затем отправьте папку из меню.
- Выберите папку документов openai-acs-msgraph/customer из клонированного проекта.
Добавьте сообщения чата и события календаря, посещая https://teams.microsoft.com и выполнив вход с помощью учетных данных клиента Разработчика Microsoft 365.
Выберите Teams в области навигации слева.
Выберите команду и канал.
Нажмите кнопку "Пуск записи".
Введите новый заказ для Adatum Corporation для темы и любого дополнительного текста, который вы хотите добавить в текст сообщения. Нажмите кнопку "Опубликовать ".
Вы можете добавить дополнительные сообщения чата, которые упоминают другие компании, используемые в приложении, такие как Adventure Works Cycles, Contoso Pharmaceuticals и Tailwind Traders.
Выберите "Календарь " в области навигации слева.
Выберите "Создать собрание".
Введите "Встреча с Adatum Corporation о расписании проекта" для названия и текста.
Нажмите кнопку "Сохранить".
Добавьте сообщения электронной почты, посещая https://outlook.com и выполнив вход с помощью учетных данных клиента Разработчика Microsoft 365.
Выберите "Создать почту".
Введите личный адрес электронной почты в поле "To ".
Введите новый заказ, размещенный для Adatum Corporation для темы и все, что вы хотите для тела.
Нажмите кнопку "Отправить".
Вернитесь в приложение в браузере и обновите страницу. Снова выберите "Просмотреть связанное содержимое" для строки "Корпорация Adatum". Теперь на вкладках должны отображаться данные в зависимости от того, какие задачи вы выполнили на предыдущем шаге.
Давайте рассмотрим код, который включает функцию данных организации в приложении. Чтобы получить данные, клиентская часть приложения использует маркер доступа, полученный компонентом mgt-login , который вы рассмотрели ранее для вызова API Microsoft Graph.
Изучение кода поиска файлов
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
Начнем с того, как данные файла извлекаются из OneDrive для бизнеса. Откройте files.component.html и просмотрите код. Полный путь к файлу — client/src/app/files/files.component.html.
Найдите компонент mgt-search-results и обратите внимание на следующие атрибуты:
HTML<mgt-search-results class="search-results" entity-types="driveItem" [queryString]="searchText" (dataChange)="dataChange($any($event))" />Компонент mgt-search-results является частью Набора средств Microsoft Graph, и, как подразумевает имя, оно используется для отображения результатов поиска из Microsoft Graph. Компонент использует следующие функции в этом примере:
Атрибут
classиспользуется для указания того, чтоsearch-resultsкласс CSS должен применяться к компоненту.Атрибут
entity-typesиспользуется для указания типа данных для поиска. В этом случае значение используетсяdriveItemдля поиска файлов в OneDrive для бизнеса.Атрибут
queryStringиспользуется для указания термина поиска. В этом случае значение привязано кsearchTextсвойству, передаваемому компоненту файлов , когда пользователь выбирает представление связанного содержимого для строки в datagrid. Квадратные скобки вокругqueryStringуказывают, что свойство привязано к значениюsearchText.Событие
dataChangeзапускается при изменении результатов поиска. В этом случае в компоненте файловdataChange()функция клиента, а данные события передаются функции. Круглые скобкиdataChangeуказывают на то, что событие привязано кdataChange()функции.Так как не указан пользовательский шаблон, встроенный
mgt-search-resultsшаблон по умолчанию используется для отображения результатов поиска.
Альтернативой использованию компонентов, таких как mgt-search-results, является вызов API Microsoft Graph непосредственно с помощью кода. Чтобы узнать, как это работает, откройте файл graph.service.ts и найдите функцию
searchFiles(). Полный путь к файлу — client/src/app/core/graph.service.ts.Вы заметите, что
queryпараметр передается функции. Это поисковый термин, передаваемый по мере выбора пользователем представления связанного содержимого для строки в datagrid. Если поисковый запрос не передается, возвращается пустой массив.TypeScriptasync searchFiles(query: string) { const files: DriveItem[] = []; if (!query) return files; ... }Затем создается фильтр, определяющий тип выполняемого поиска. В этом случае код ищет файлы в OneDrive для бизнеса поэтому
driveItemиспользуется так же, как вы видели ранее с компонентомmgt-search-results. Это то же самое, что передачаdriveItementity-typesв компонент mgt-search-results , который вы видели ранее. Затем параметрqueryдобавляется вqueryStringфильтр вместе сContentType:Document.TypeScriptconst filter = { "requests": [ { "entityTypes": [ "driveItem" ], "query": { "queryString": `${query} AND ContentType:Document` } } ] };Затем вызов выполняется в
/search/queryAPI Microsoft Graph с помощьюProviders.globalProvider.graph.client.api()функции. Объектfilterпередаетсяpost()функции, которая отправляет данные в API.TypeScriptconst searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);Затем результаты поиска итерируются для поиска
hits. Каждыйhitсодержит сведения о найденном документе. Свойство с именемresourceсодержит метаданные документа и добавляется вfilesмассив.TypeScriptif (searchResults.value.length !== 0) { for (const hitContainer of searchResults.value[0].hitsContainers) { if (hitContainer.hits) { for (const hit of hitContainer.hits) { files.push(hit.resource); } } } }Затем
filesмассив возвращается вызывающей объекту.TypeScriptreturn files;
Просматривая этот код, вы можете увидеть, что веб-компонент mgt-search-results , который вы изучили ранее, выполняет большую работу и значительно сокращает объем кода, который необходимо написать! Однако могут возникнуть сценарии, в которых требуется вызвать Microsoft Graph напрямую, чтобы получить больше контроля над данными, отправленными в API, или способом обработки результатов.
Откройте файл files.component.ts и найдите функцию
search(). Полный путь к файлу — client/src/app/files/files.component.ts.Хотя текст этой функции закомментирован из-за используемого компонента mgt-search-results , функция может использоваться для вызова Microsoft Graph при выборе пользователем представления связанного содержимого для строки в datagrid. Функция
search()вызываетсяsearchFiles()в graph.service.ts и передаетqueryпараметр в него (имя компании в этом примере). Затем результаты поиска назначаютсяdataсвойству компонента.TypeScriptoverride async search(query: string) { this.data = await this.graphService.searchFiles(query); }Затем компонент файлов может использовать
dataсвойство для отображения результатов поиска. Это можно обрабатывать с помощью пользовательских привязок HTML или с помощью другого элемента управления Microsoft Graph Toolkit с именемmgt-file-list. Ниже приведен пример привязкиdataсвойства к одному из свойств компонента с именемfilesи обработкойitemClickсобытия по мере взаимодействия пользователя с файлом.HTML<mgt-file-list (itemClick)="itemClick($any($event))" [files]="data"></mgt-file-list>Независимо от того, следует ли использовать компонент mgt-search-results , показанный ранее или написать пользовательский код для вызова Microsoft Graph, будет зависеть от конкретного сценария. В этом примере компонент mgt-search-results используется для упрощения кода и уменьшения объема необходимой работы.
Изучение кода поиска сообщений чата Teams
Вернитесь к graph.service.ts и найдите функцию
searchChatMessages(). Вы увидите, что это похоже наsearchFiles()функцию, которую вы посмотрели ранее.- Он публикует данные в API Microsoft Graph
/search/queryи преобразует результаты в массив объектов, имеющих сведения оteamId,channelIdиmessageIdкоторые соответствуют термину поиска. - Чтобы получить сообщения канала Teams, в API и
/teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId}teamIdAPI выполняетсяchannelIdвторой вызов, который передается.messageIdВозвращает полные сведения о сообщении. - Выполняются дополнительные задачи фильтрации, а полученные сообщения возвращаются вызывающей
searchChatMessages()программе.
- Он публикует данные в API Microsoft Graph
Откройте файл chats.component.ts и найдите функцию
search(). Полный путь к файлу — client/src/app/chats/chats.component.ts. Функцияsearch()вызываетсяsearchChatMessages()в graph.service.ts и передаетqueryпараметр в него.TypeScriptoverride async search(query: string) { this.data = await this.graphService.searchChatMessages(query); }Результаты поиска назначаются
dataсвойству компонента и привязке данных используются для итерации по массиву результатов и отрисовки данных. В этом примере для отображения результатов поиска используется компонент карточки Angular Material .HTML@if (this.data.length) { <div> @for (chatMessage of this.data;track chatMessage.id) { <mat-card> <mat-card-header> <mat-card-title [innerHTML]="chatMessage.summary"></mat-card-title> <!-- <mat-card-subtitle [innerHTML]="chatMessage.body"></mat-card-subtitle> --> </mat-card-header> <mat-card-actions> <a mat-stroked-button color="basic" [href]="chatMessage.webUrl" target="_blank">View Message</a> </mat-card-actions> </mat-card> } </div> }
Отправка сообщения в канал Microsoft Teams
Помимо поиска сообщений чата Microsoft Teams, приложение также позволяет пользователю отправлять сообщения в канал Microsoft Teams. Это можно сделать, вызвав конечную точку
/teams/${teamId}/channels/${channelId}/messagesMicrosoft Graph.
В следующем коде вы увидите, что создается URL-адрес, включающий
teamIdзначения иchannelIdзначения. Значения переменной среды используются для идентификатора команды и идентификатора канала в этом примере, но эти значения могут быть динамически получены, а также с помощью Microsoft Graph. Константаbodyсодержит сообщение для отправки. Затем выполняется запрос POST, и результаты возвращаются вызывающей объекту.TypeScriptasync sendTeamsChat(message: string): Promise<TeamsDialogData> { if (!message) new Error('No message to send.'); if (!TEAM_ID || !CHANNEL_ID) new Error('Team ID or Channel ID not set in environment variables. Please set TEAM_ID and CHANNEL_ID in the .env file.'); const url = `https://graph.microsoft.com/v1.0/teams/${TEAM_ID}/channels/${CHANNEL_ID}/messages`; const body = { "body": { "contentType": "html", "content": message } }; const response = await Providers.globalProvider.graph.client.api(url).post(body); return { id: response.id, teamId: response.channelIdentity.teamId, channelId: response.channelIdentity.channelId, message: response.body.content, webUrl: response.webUrl, title: 'Send Teams Chat' }; }Использование этого типа функций в Microsoft Graph обеспечивает отличный способ повышения качества продукта пользователей, позволяя пользователям взаимодействовать с Microsoft Teams непосредственно из приложения, которое они уже используют.
Организационные данные: получение сообщений электронной почты и событий календаря
В предыдущем упражнении вы узнали, как получить файлы из OneDrive для бизнеса и чатов из Microsoft Teams с помощью Microsoft Graph и компонента mgt-search-results из Microsoft Graph Toolkit. Вы также узнали, как отправлять сообщения в каналы Microsoft Teams. В этом упражнении вы узнаете, как получить сообщения электронной почты и события календаря из Microsoft Graph и интегрировать их в приложение.
В этом упражнении вы выполните следующие действия.
- Узнайте, как веб-компонент mgt-search-results в Microsoft Graph Toolkit можно использовать для поиска сообщений электронной почты и событий календаря.
- Узнайте, как настроить компонент mgt-search-results для отображения результатов поиска в пользовательском режиме.
- Узнайте, как вызывать Microsoft Graph напрямую для получения сообщений электронной почты и событий календаря.
Изучение кода поиска сообщений электронной почты
Совет
Если вы используете Visual Studio Code, вы можете открывать файлы напрямую, выбрав:
- Windows/Linux: CTRL +P
- Mac: Cmd + P
Затем введите имя файла, который нужно открыть.
В предыдущем упражнении вы создали регистрацию приложения в идентификаторе Microsoft Entra и запустили сервер приложений и сервер API. Вы также обновили следующие значения в
.envфайле.ENTRAID_CLIENT_ID=<APPLICATION_CLIENT_ID_VALUE> TEAM_ID=<TEAMS_TEAM_ID> CHANNEL_ID=<TEAMS_CHANNEL_ID>Прежде чем продолжить, убедитесь, что вы выполнили предыдущее упражнение .
Откройте emails.component.html и просмотрите код. Полный путь к файлу — client/src/app/emails/emails.component.html.
Найдите компонент mgt-search-results :
HTML<mgt-search-results class="search-results" entity-types="message" [queryString]="searchText" (dataChange)="dataChange($any($event))"> <template data-type="result-message"></template> </mgt-search-results>Этот пример компонента mgt-search-results настраивается так же, как и тот, который вы посмотрели ранее. Единственное различие заключается в том, что
entity-typesатрибут заданmessageдля поиска сообщений электронной почты и предоставляется пустой шаблон.- Атрибут
classиспользуется для указания того, чтоsearch-resultsкласс CSS должен применяться к компоненту. - Атрибут
entity-typesиспользуется для указания типа данных для поиска. В этом случае используется значениеmessage. - Атрибут
queryStringиспользуется для указания термина поиска. - Событие
dataChangeзапускается при изменении результатов поиска. Функция компонентаdataChange()электронной почты вызывается, результаты передаются в него, а свойство с именемdataобновляется в компоненте. - Для компонента определен пустой шаблон. Этот тип шаблона обычно используется для определения способа отрисовки результатов поиска. Однако в этом сценарии мы говорим компоненту не отображать данные сообщения. Вместо этого мы отрисуем данные самостоятельно с помощью стандартной привязки данных (Angular используется в этом случае, но вы можете использовать любую библиотеку или платформу, которую вы хотите).
- Атрибут
Ознакомьтесь с компонентом mgt-search-results в emails.component.html , чтобы найти привязки данных, используемые для отрисовки сообщений электронной почты. В этом примере выполняется итерацию по
dataсвойству и записывается тема электронной почты, предварительный просмотр текста и ссылка для просмотра полного сообщения электронной почты.HTML@if (this.data.length) { <div> @for (email of this.data;track $index) { <mat-card> <mat-card-header> <mat-card-title>{{email.resource.subject}}</mat-card-title> <mat-card-subtitle [innerHTML]="email.resource.bodyPreview"></mat-card-subtitle> </mat-card-header> <mat-card-actions> <a mat-stroked-button color="basic" [href]="email.resource.webLink" target="_blank">View Email Message</a> </mat-card-actions> </mat-card> } </div> }
Помимо использования компонента mgt-search-results для получения сообщений, Microsoft Graph предоставляет несколько API, которые также можно использовать для поиска по электронной почте.
/search/queryAPI, который вы видели ранее, может быть использован, но более простойmessagesвариант — ЭТО API.Чтобы узнать, как вызвать этот API, вернитесь к graph.service.ts и найдите функцию
searchEmailMessages(). Он создает URL-адрес, который можно использовать для вызоваmessagesконечной точки Microsoft Graph и присваиваетqueryзначение параметру$search. Затем код выполняет запрос GET и возвращает результаты вызывающей объекту. Оператор$searchавтоматически ищетqueryзначение в полях темы, текста и отправителя.TypeScriptasync searchEmailMessages(query:string) { if (!query) return []; // The $search operator will search the subject, body, and sender fields automatically const url = `https://graph.microsoft.com/v1.0/me/messages?$search="${query}"&$select=subject,bodyPreview,from,toRecipients,receivedDateTime,webLink`; const response = await Providers.globalProvider.graph.client.api(url).get(); return response.value; }Компонент , отображает результаты в пользовательском интерфейсе.
TypeScriptoverride async search(query: string) { this.data = await this.graphService.searchEmailMessages(query); }
Изучение кода поиска событий календаря
Поиск событий календаря также можно выполнить с помощью компонента mgt-search-results . Он может обрабатывать отрисовку результатов для вас, но вы также можете определить собственный шаблон, который вы увидите далее в этом упражнении.
Откройте calendar-events.component.html и просмотрите код. Полный путь к файлу client/src/app/calendar-events/calendar-events.component.html. Вы увидите, что это очень похоже на файлы и компоненты электронной почты, которые вы рассмотрели ранее.
HTML<mgt-search-results class="search-results" entity-types="event" [queryString]="searchText" (dataChange)="dataChange($any($event))"> <template data-type="result-event"></template> </mgt-search-results>Этот пример компонента mgt-search-results настроен так же, как и те, которые вы рассмотрели ранее. Единственное различие заключается в том, что
entity-typesатрибут заданeventдля поиска событий календаря и предоставляется пустой шаблон.- Атрибут
classиспользуется для указания того, чтоsearch-resultsкласс CSS должен применяться к компоненту. - Атрибут
entity-typesиспользуется для указания типа данных для поиска. В этом случае используется значениеevent. - Атрибут
queryStringиспользуется для указания термина поиска. - Событие
dataChangeзапускается при изменении результатов поиска. Функция компонента событияdataChange()вызывается, результаты передаются в него, а свойство с именемdataобновляется в компоненте. - Для компонента определен пустой шаблон. В этом сценарии мы сообщаем компоненту не отображать данные. Вместо этого мы отрисуем данные самостоятельно с помощью стандартной привязки данных.
- Атрибут
Непосредственно под компонентом
mgt-search-resultsв calendar-events.component.html вы найдете привязки данных, используемые для отображения событий календаря. В этом примере выполняется итерацию поdataсвойству и записывается дата начала, время и тема события. Пользовательские функции, включенные в компонент, напримерdayFromDateTime()иtimeRangeFromEvent()вызываются для правильного форматирования данных. Привязки HTML также включают ссылку для просмотра события календаря в Outlook и расположения события, если он указан.HTML@if (this.data.length) { <div> @for (event of this.data;track $index) { <div class="root"> <div class="time-container"> <div class="date">{{ dayFromDateTime(event.resource.start.dateTime)}}</div> <div class="time">{{ timeRangeFromEvent(event.resource) }}</div> </div> <div class="separator"> <div class="vertical-line top"></div> <div class="circle"> @if (!this.event.resource.bodyPreview?.includes('Join Microsoft Teams Meeting')) { <div class="inner-circle"></div> } </div> <div class="vertical-line bottom"></div> </div> <div class="details"> <div class="subject">{{ event.resource.subject }}</div> @if (this.event.resource.location?.displayName) { <div class="location"> at <a href="https://bing.com/maps/default.aspx?where1={{event.resource.location.displayName}}" target="_blank" rel="noopener"><b>{{ event.resource.location.displayName }}</b></a> </div> } @if (this.event.resource.attendees?.length) { <div class="attendees"> @for (attendee of this.event.resource.attendees;track attendee.emailAddress.name) { <span class="attendee"> <mgt-person person-query="{{attendee.emailAddress.name}}"></mgt-person> </span> } </div> } @if (this.event.resource.bodyPreview?.includes('Join Microsoft Teams Meeting')) { <div class="online-meeting"> <img class="online-meeting-icon" src="https://img.icons8.com/color/48/000000/microsoft-teams.png" title="Online Meeting" /> <a class="online-meeting-link" href="{{ event.resource.onlineMeetingUrl }}"> Join Teams Meeting </a> </div> } </div> </div> } </div> }
Помимо поиска событий календаря с помощью
search/queryAPI, Microsoft Graph также предоставляетeventsAPI, который также можно использовать для поиска событий календаря. Найдите функциюsearchCalendarEvents()в graph.service.ts.Функция
searchCalendarEvents()создает значения даты и окончания, используемые для определения периода времени для поиска. Затем он создает URL-адрес, который можно использовать для вызоваeventsконечной точки Microsoft Graph и включаетqueryпараметр и переменные даты и окончания. Затем выполняется запрос GET, и результаты возвращаются вызывающей объекту.TypeScriptasync searchCalendarEvents(query:string) { if (!query) return []; const startDateTime = new Date(); const endDateTime = new Date(startDateTime.getTime() + (7 * 24 * 60 * 60 * 1000)); const url = `/me/events?startdatetime=${startDateTime.toISOString()}&enddatetime=${endDateTime.toISOString()}&$filter=contains(subject,'${query}')&orderby=start/dateTime`; const response = await Providers.globalProvider.graph.client.api(url).get(); return response.value; }Ниже приведена разбивка созданного URL-адреса:
- Часть
/me/eventsURL-адреса используется для указания того, что события вошедшего пользователя должны быть извлечены. -
startdatetimeПараметрыenddatetimeиспользуются для определения периода времени для поиска. В этом случае поиск вернет события, начинающиеся в течение следующих 7 дней. - Параметр
$filterзапроса используется для фильтрации результатов поqueryзначению (имя компании, выбранное из datagrid в этом случае). Функцияcontains()используется для поискаqueryзначения вsubjectсвойстве события календаря. - Параметр
$orderbyзапроса используется для упорядочивания результатов свойствомstart/dateTime.
- Часть
urlПосле создания запрос GET выполняется в API Microsoft Graph, используя значениеurl, и результаты возвращаются вызывающей программе.Как и в предыдущих компонентах, вызовы
search()компонента событий календаря (calendar-events.component.ts файла) и отображение результатов.TypeScriptoverride async search(query: string) { this.data = await this.graphService.searchCalendarEvents(query); }Примечание
Вы также можете выполнять вызовы Microsoft Graph из пользовательского API или серверного приложения. Просмотрите следующее руководство , чтобы просмотреть пример вызова API Microsoft Graph из функции Azure.
Теперь вы видели пример использования Microsoft Graph для получения файлов, чатов, сообщений электронной почты и событий календаря. Те же понятия можно применять к другим API Microsoft Graph, а также. Например, можно использовать API пользователей Microsoft Graph для поиска пользователей в организации. Вы также можете использовать API групп Microsoft Graph для поиска групп в организации. Полный список API Microsoft Graph можно просмотреть в документации.
Поздравляем!
Вы завершили работу с этим руководством
Поздравляем! В этом руководстве вы узнали, как:
- Azure OpenAI можно использовать для повышения производительности пользователей.
- Службы коммуникации Azure можно использовать для интеграции функций коммуникации.
- API и компоненты Microsoft Graph можно использовать для получения и отображения данных организации.
С помощью этих технологий можно создавать эффективные решения, повышающие производительность пользователей, свести к минимуму сдвиг контекста и предоставить необходимую информацию о принятии решений.
Очистка ресурсов Azure
Очистка ресурсов Azure, чтобы избежать дополнительных расходов на вашу учетную запись. Перейдите к портал Azure и удалите следующие ресурсы:
- Ресурс поиска ИИ Azure
- ресурс служба хранилища Azure
- Ресурс Azure OpenAI (сначала удалите модели, а затем ресурс Azure OpenAI)
- ресурс Службы коммуникации Azure
Дальнейшие шаги
Документация
- Документация по Azure OpenAI
- Azure OpenAI в данных
- Документация по службам коммуникации Azure
- Документация по Microsoft Graph
- Документация по Набору средств Microsoft Graph
- Документация разработчика Microsoft Teams
Обучающее содержимое
- Применение инженерии запросов с помощью Службы Azure OpenAI
- Начало работы со службой Azure OpenAI
- Общие сведения о службах коммуникации Azure
- Основы Microsoft Graph
- Видеокурс: Основы Microsoft Graph для начинающих
- Изучение сценариев Microsoft Graph для разработки JavaScript
- Изучение сценариев Microsoft Graph для разработки ASP.NET Core
- Начало работы с Microsoft Graph Toolkit
- Создание и развертывание приложений для Microsoft Teams с помощью Набора средств Teams для Visual Studio Code
Возникла проблема с этим разделом? Если это так, отправьте нам отзыв, чтобы мы исправили этот раздел.