Интеграция функций OpenAI, коммуникации и организационных данных в бизнес-приложение

Статья
Developer (Средний уровень)
136 мин до завершения

Уровень: промежуточный

В этом руководстве показано, как 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 и извлечения данных организации. Ниже приведен обзор решения приложения, которое вы узнаете в этом руководстве:

Обзор сценария Microsoft Cloud

В этом руководстве описан процесс настройки необходимых ресурсов 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

Клонирование проекта

Осталось 132 мин

Проект кода, используемый в этом руководстве, доступен по адресу 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 и развертывание модели

Осталось 127 мин

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

В этом упражнении вы выполните такие действия:

Создайте ресурс службы Azure OpenAI.
Развертывание модели.
Обновите env-файл со значениями из ресурса службы Azure OpenAI.

Обзор сценария Microsoft Cloud

Создание ресурса службы Azure OpenAI

Посетите портал Azure в браузере и войдите в систему.
Введите openai в строке поиска в верхней части страницы портала и выберите Azure OpenAI из параметров, которые отображаются.
Выберите " Создать " на панели инструментов.

Примечание.

Хотя в этом руководстве основное внимание уделяется Azure OpenAI, если у вас есть ключ API OpenAI и вы хотите его использовать, вы можете пропустить этот раздел и перейти непосредственно к разделу "Обновить env-файл проекта" ниже. Назначьте ключ OPENAI_API_KEY API 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 postgres
```
  - Windows с 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 install
- npm start
+ Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
cd в папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.
- npm install
- npm start
Откроется браузер, в который вы http://localhost:4200перейдете.

ИИ: естественный язык для SQL

Осталось 122 мин

Цитата "Просто потому, что вы не можете означать, что вы должны" является полезным руководством при разработке возможностей ИИ. Например, естественный язык 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:
```
{ 
    "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-запроса он используется для запроса базы данных и возврата результатов.
```
router.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.

async 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() функция и systemPrompt userPrompt передаются в нее значения.
Результаты проверяются, чтобы гарантировать, что в созданный SQL-запрос не включены запрещенные значения. При обнаружении запрещенных значений SQL-запрос имеет пустую строку.

Более подробно рассмотрим системный запрос:
```
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"] 
  }
`;
```
- Определяется тип используемого помощника по искусственному интеллекту. В этом случае "естественный язык для бота 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.
```
function 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() .
```
async 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() .
```
async 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: содержит сообщения для создания завершения чата. В этом примере содержатся два сообщения: один из системы (определение поведения и правил) и один из пользователей (содержащий текст запроса).
- Return Value (Возвращаемое значение).
  - Функция возвращает объект завершения, созданный Azure OpenAI.
Закомментируйте следующие строки в getSQLFromNLP() функции:
```
// 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-запрос не будет выполняться в базе данных.
```
function 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() функции. Сохраните файл.
```
if (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.

ИИ: создание завершений

Осталось 112 мин

Помимо естественного языка в компоненте 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 . Затем результаты возвращаются клиенту.
```
router.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().

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

Примечание.

Это иллюстрирует важность инженерных запросов с правильными сведениями и правилами, чтобы обеспечить правильные результаты возврата. Дополнительные сведения об этом процессе см. в статье "Введение в документацию по проектированию запросов".
Отмените внесенные изменения systemPrompt completeEmailSMSMessages(), сохраните файл и повторно запустите его еще раз, но используйте Order is ahead of schedule. правило (не включайте отрицательное правило). На этот раз вы увидите сообщения электронной почты и SMS, возвращенные должным образом.
Перед переходом к следующему упражнению следует рассмотреть несколько окончательных пунктов:
- Важно иметь человека в цикле для просмотра созданных сообщений. В этом примере завершения Azure OpenAI возвращают предлагаемые сообщения электронной почты и SMS, но пользователь может переопределить их перед отправкой. Если вы планируете автоматизировать сообщения электронной почты, имея некоторый тип процесса проверки человека, чтобы убедиться, что утвержденные сообщения отправляются важно. Просматривайте ИИ как copilot, а не автопилот.
- Завершения будут выполняться только так же хорошо, как и правила, которые вы добавляете в запрос. Время на тестирование запросов и возвращаемых завершений. Рассмотрите возможность использования потока запросов для создания комплексного решения, упрощающего прототипирование, экспериментирование, итерацию и развертывание приложений ИИ. Пригласите других заинтересованных лиц проекта, чтобы также просмотреть завершения.
- Возможно, потребуется включить код после обработки, чтобы обеспечить правильную обработку непредвиденных результатов.
- Используйте системные запросы, чтобы определить правила и сведения, которые должен следовать помощнику по ИИ. Используйте запросы пользователя, чтобы определить правила и сведения, которые пользователь хотел бы включить в завершения.

ИИ: Azure OpenAI в данных

Осталось 102 мин

Интеграция Azure OpenAI Natural Language Processing (NLP) и возможностей завершения обеспечивает значительный потенциал для повышения производительности пользователей. Используя соответствующие запросы и правила, помощник по искусственному интеллекту может эффективно создавать различные формы связи, такие как сообщения электронной почты, SMS-сообщения и многое другое. Эта функция приводит к повышению эффективности пользователей и оптимизации рабочих процессов.

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

Ниже приведен краткий обзор работы функции "перенос собственных данных" из документации по Azure OpenAI.

Примечание.

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

В этом упражнении вы выполните следующие действия.

Создайте пользовательский источник данных с помощью Azure AI Studio.
Разверните модель внедрения с помощью Azure AI Studio.
Отправка пользовательских документов.
Запустите сеанс чата на игровой площадке чата, чтобы поэкспериментировать с созданием завершений на основе собственных данных.
Изучите код, использующий поиск ИИ Azure и Azure OpenAI для создания завершений на основе собственных данных.

Давайте начнем с развертывания модели внедрения и добавления пользовательского источника данных в Azure AI Studio.

Добавление пользовательского источника данных в Azure AI Studio

Перейдите в 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 Studio и выберите созданный ресурс хранилища BLOB-объектов из раскрывающегося списка "Выбор ресурса хранилища BLOB-объектов Azure". Если вы не видите его в списке, щелкните значок обновления рядом с раскрывающимся списком.
Для доступа к учетной записи хранения необходимо включить общий доступ к ресурсам между источниками (CORS). Выберите "Включить CORS" в диалоговом окне Azure AI Studio.
В раскрывающемся списке "Выбор ресурса поиска ИИ Azure" выберите "Создать новый ресурс поиска ИИ Azure".
При этом вы вернеесь к портал Azure, где можно выполнить следующие задачи:
- Введите уникальное имя ресурса поиска ИИ, например byodsearch-[ваше фамилия].
- Выберите регион, близкий к вашему расположению.
- В разделе "Ценовая категория" выберите "Изменить ценовую категорию" и выберите "Базовый" и "Выбрать". Уровень "Бесплатный" не поддерживается, поэтому вы очистите ресурс поиска ИИ в конце этого руководства.
- Выберите "Рецензирование", а затем "Создать".
После создания ресурса поиска ИИ перейдите на страницу обзора ресурсов и скопируйте значение URL-адреса в локальный файл.
Выберите параметры -->Ключи в меню навигации.
На странице управления доступом к API выберите "Оба", чтобы включить доступ к службе с помощью управляемого удостоверения или с помощью ключа. При появлении запроса нажмите Да.

Примечание.

Хотя мы будем использовать ключ API в этом упражнении, так как добавление назначений ролей может занять до 10 минут, с небольшими дополнительными усилиями вы можете включить управляемое удостоверение, назначаемое системой, для доступа к службе более безопасно.
Выберите ключи в меню навигации слева и скопируйте значение ключа первичного администратора в локальный файл. Позже в упражнении потребуются значения URL-адреса и ключа.
Выберите "Параметры -> Семантический рангер" в меню навигации и убедитесь, что выбран параметр "Бесплатный ".

Примечание.

Чтобы проверить, доступен ли семантический рангировщик в определенном регионе, просмотрите страницу "Доступные по регионам" на веб-сайте Azure, чтобы узнать, указан ли ваш регион.
Вернитесь в диалоговое окно добавления данных в Azure AI Studio и выберите созданный ресурс поиска в раскрывающемся списке "Выбор поиска ИИ Azure". Если вы не видите его в списке, щелкните значок обновления рядом с раскрывающимся списком.
Введите значение byod-search-index для значения имени индекса.
Установите флажок "Добавить векторный поиск" в этот ресурс поиска.
В раскрывающемся списке "Выбор модели внедрения" выберите созданную ранее модель преобразования текста ada-002.
В диалоговом окне "Отправка файлов" нажмите кнопку "Обзор файла".
Перейдите в папку документов клиента проекта (расположенную в корне проекта) и выберите следующие файлы:
- Часы A102 Установка Instructions.docx
- FAQs.docx компании
Примечание.

В настоящее время эта функция поддерживает следующие форматы файлов для создания локального индекса: .txt, MD, .html, .pdf, .docx и .pptx.
Щелкните Upload files (Передать файлы). Файлы будут отправлены в контейнер fileupload-byod-search-index в ресурсе хранилища BLOB-объектов, созданном ранее.
Нажмите кнопку "Рядом", чтобы перейти к диалоговому оккуму управления данными.
В раскрывающемся списке "Тип поиска" выберите "Гибридная+ семантика".

Примечание.

Этот параметр обеспечивает поддержку поиска ключевых слов и векторов. После возврата результатов дополнительный процесс ранжирования применяется к результирующем набору с помощью моделей глубокого обучения, что повышает релевантность поиска для пользователя. Дополнительные сведения о семантической поиске см . в документации по семантической поиску в Azure AI .
Убедитесь, что для параметра "Выбор размера " задано значение 1024.
Выберите Далее.
Для типа проверки подлинности ресурсов Azure выберите ключ API. Дополнительные сведения о выборе подходящего типа проверки подлинности в документации по проверке подлинности поиска ИИ Azure.
Выберите Далее.
Просмотрите сведения и нажмите кнопку "Сохранить и закрыть".
После отправки пользовательских данных данные будут индексированы и доступны для использования на игровой площадке чата. Этот процесс может занять несколько минут. По завершении перейдите к следующему разделу.

Использование пользовательского источника данных на площадке чата

Найдите раздел сеанса чата страницы в Azure OpenAI Studio и введите следующий запрос пользователя:
```
What safety rules are required to install a clock?
```
После отправки запроса пользователя вы увидите результат, аналогичный следующему:
Разверните раздел " 1 ссылок " в ответе чата и обратите внимание, что файл "Часы A102 Установка Instructions.docx " указан и вы можете выбрать его для просмотра документа.
Введите следующее сообщение пользователя:
```
What should I do to mount the clock on the wall?
```
Вы увидите результат, аналогичный следующему:
Теперь давайте поэкспериментируем с документом часто задаваемых вопросы о компании. Введите следующий текст в поле запроса пользователя:
```
What is the company's policy on vacation time?
```
Вы должны увидеть, что для этого запроса не найдена информация.
Введите следующий текст в поле запроса пользователя:
```
How should I handle refund requests?
```
Вы увидите результат, аналогичный следующему:
Разверните раздел " 1 ссылки " в ответе чата и обратите внимание, что файл корпоративного FAQs.docx указан и вы можете выбрать его для просмотра документа.
Выберите "Просмотреть код" на панели инструментов игровой площадки чата.
Обратите внимание, что вы можете переключаться между разными языками, просматривать конечную точку и получать доступ к ключу конечной точки. Закройте диалоговое окно "Пример кода ".
Включите переключатель "Показать необработанный 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 файл. Если вы не выполнили эти действия, следуйте инструкциям в конце предыдущего упражнения, прежде чем продолжить.
После загрузки приложения в браузере щелкните значок справки чата в правом верхнем углу приложения.
В диалоговом окне чата должен появиться следующий текст:
```
How should I handle a company refund request?
```
Нажмите кнопку "Получить справку ". Вы увидите результаты, возвращенные компанией FAQs.docx документ, который вы добавили ранее в Azure OpenAI Studio. Если вы хотите прочитать документ, его можно найти в папке документов клиента в корне проекта.
Измените текст на следующий и нажмите кнопку "Получить справку ":
```
What 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 . Затем результаты возвращаются клиенту.
```
router.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().
```
async 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() вызова функции.

function 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.
```
async 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() вызывается с помощью , userPrompttemperatureи dataSources значенийsystemPrompt. Эта функция используется для вызова API OpenAI Azure и возврата результатов.
- После возврата ответа ссылки на документ записываются в консоль. Затем содержимое сообщения завершения возвращается вызывающей объекту.
Перед переходом к следующему упражнению следует рассмотреть несколько окончательных пунктов:
- В примере приложения используется один индекс в поиске ИИ Azure. С помощью Azure OpenAI можно использовать несколько индексов и источников данных. Свойство dataSources в getAzureOpenAIBYODCompletion() функции можно обновить, чтобы включить несколько источников данных по мере необходимости.
- Безопасность должна тщательно оцениваться с помощью этого типа сценария. Пользователи не смогут задавать вопросы и получать результаты из документов, к которым они не могут получить доступ.
Теперь, когда вы узнали о Azure OpenAI, запросах, завершениях и способах использования собственных данных, давайте рассмотрим следующее упражнение, чтобы узнать, как можно использовать возможности взаимодействия для улучшения приложения. Если вы хотите узнать больше о Azure OpenAI, просмотрите обучающее содержимое службы Azure OpenAI . Дополнительные сведения об использовании собственных данных с Azure OpenAI можно найти в документации по Azure OpenAI .

Обмен данными. Создание ресурса Службы коммуникации Azure

Осталось 87 мин

Эффективное взаимодействие важно для успешных пользовательских бизнес-приложений. С помощью Службы коммуникации Azure (ACS) вы можете добавлять такие функции, как телефонные звонки, динамический чат, аудио- и видеозвонки, а также сообщения электронной почты и SMS-сообщения в приложения. Ранее вы узнали, как Azure OpenAI может создавать завершения для сообщений электронной почты и SMS. Теперь вы узнаете, как отправлять сообщения. Вместе ACS и OpenAI могут улучшить приложения, упрощая взаимодействие, повышая взаимодействие и повышая производительность бизнеса.

В этом упражнении вы выполните следующие действия.

Создайте ресурс Службы коммуникации Azure (ACS).
Добавьте бесплатный номер телефона с возможностями звонков и SMS.
Подключите домен электронной почты.
Обновите env-файл проекта со значениями из ресурса ACS.

Обзор сценария Microsoft Cloud

Создание ресурса Службы коммуникации 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 и выберите Email -->Domains в меню ресурсов.
- Выберите 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 и веб-сервер, выполните следующие действия.
1. В следующих шагах вы создадите три окна терминала в Visual Studio Code.
2. Щелкните правой кнопкой мыши env-файл в списке файлов Visual Studio Code и выберите "Открыть в интегрированном терминале". Перед продолжением убедитесь, что терминал находится в корне проекта — openai-acs-msgraph .
3. Выберите один из следующих параметров, чтобы запустить базу данных 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 postgres
```
    - Windows с 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
```
4. После запуска контейнера базы данных нажмите + значок на панели инструментов терминала Visual Studio Code, чтобы создать второе окно терминала.
5. cd в папку server/typescript и выполните следующие команды, чтобы установить зависимости и запустить сервер API.
  - npm install
  - npm start
6. + Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
7. cd в папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.
  - npm install
  - npm start
8. Откроется браузер, в который вы http://localhost:4200перейдете.

Обмен данными: звонок по телефону

Осталось 79 мин

Интеграция возможностей звонков Службы коммуникации 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 сообщение и номер телефона клиента с помощью шины событий.
```
openCallDialog(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.
```
ngOnInit() {
    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() .
Прежде чем изучить код, который делает телефонный звонок, давайте рассмотрим, как извлекается маркер доступа ACS и как создаются объекты звонков по телефону. Найдите функцию ngOnInit() в phone-call.component.ts.
```
async 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.services.ts и найдите функцию getAcsToken() . Полный путь к файлу — client/src/app/core/acs.service.ts. Функция выполняет HTTP-запрос GET к маршруту, предоставляемому /acstoken сервером API.
```
getAcsToken(): Observable<AcsUser> {
    return this.http.get<AcsUser>(this.apiUrl + 'acstoken')
    .pipe(
        catchError(this.handleError)
    );
}
```
Функция сервера API с именем createACSToken() извлекает идентификатор пользователя и маркер доступа и возвращает его клиенту. Его можно найти в файле server/typescript/acs.ts .
```
import { 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 значения.
Теперь, когда вы узнали, как извлекается идентификатор пользователя и маркер, вернитесь к phone-call.component.ts функции и найдите ее startCall() .

Эта функция вызывается при выборе звонка в компоненте телефонного звонка. Он использует объект, упомянутый CallAgent ранее, для запуска вызова. Функция callAgent.startCall() принимает объект, представляющий номер для вызова и номер телефона ACS, используемый для вызова.

startCall() {
    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() вызывается при выборе функции "Зависание" в компоненте телефонного звонка.
```
endCall() {
    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() функций соответственно.
Теперь, когда вы узнали, как можно интегрировать телефонные звонки в приложение, давайте переключим наше внимание на использование Службы коммуникации Azure для отправки сообщений электронной почты и SMS.

Коммуникация: отправка сообщений электронной почты и SMS

Осталось 69 мин

Помимо телефонных звонков, Службы коммуникации 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_ADDRESS CUSTOMER_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 .
```
openEmailSmsDialog(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() выполняет следующие задачи:
- Проверяет, содержит phone ли data объект (который представляет строку из datagrid) и email свойство. Если это так, он создает dialogData объект, содержащий сведения для передачи в диалоговое окно.
- Открывает диалоговое EmailSmsDialogComponent окно и передает dialogData объект в него.
- Подписывается на afterClosed() событие диалогового окна. Это событие запускается при закрытии диалогового окна. Объект response содержит сведения, введенные в диалоговое окно.
Откройте файл email-sms-dialog.component.ts. Полный путь к файлу — client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
Найдите функцию sendEmail() :
```
sendEmail() {
    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() выполняет следующие задачи:
- Проверяет, установлен trueли acsEmailEnabled флаг компонента. Этот флаг проверяет, имеет ли 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.
```
sendEmail(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() функцией с помощью оператора RxJS catchError .
Теперь давайте рассмотрим, как приложение взаимодействует с функцией электронной почты ACS. Откройте файл acs.ts и найдите функциюsendEmail(). Полный путь к файлу — server/typescript/acs.ts.
Функция sendEmail() выполняет следующие задачи:
- Создает новый EmailClient объект и передает в него строка подключения ACS (это значение извлекается из переменной ACS_CONNECTION_STRING среды).
```
const emailClient = new EmailClient(connectionString);
```
- Создает новый EmailMessage объект и передает сведения отправителя, субъекта, сообщения и получателя.
```
const msgObject: EmailMessage = {
    senderAddress: process.env.ACS_EMAIL_ADDRESS as string,
    content: {
        subject: subject,
        plainText: message,
    },
    recipients: {
        to: [
            {
                address: customerEmailAddress,
                displayName: customerName,
            },
        ],
    },
};
```
- Отправляет сообщение электронной почты с помощью emailClient.beginSend() функции и возвращает ответ. Хотя функция отправляется только одному получателю в этом примере, beginSend() эта функция также может использоваться для отправки нескольким получателям.
```
const poller = await emailClient.beginSend(msgObject);
```
- Ожидает, пока poller объект будет сигнализировать о завершении и отправляет ответ вызывающему объекту.

Изучение SMS-кода

Вернитесь к файлу email-sms-dialog.component.ts , который вы открыли ранее. Полный путь к файлу — client/src/app/email-sms-dialog/email-sms-dialog.component.ts.
Найдите функцию sendSms() :
```
sendSms() {
    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() выполняет следующие задачи:
- Проверяет, установлен trueли acsPhoneEnabled флаг компонента. Этот флаг проверяет, имеет ли 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.
```
sendSms(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() функцией с помощью оператора RxJS catchError .
Наконец, давайте рассмотрим, как приложение взаимодействует с функцией SMS ACS. Откройте файл acs.ts. Полный путь к файлу — server/typescript/acs.ts и найдите функцию sendSms() .
Функция sendSms() выполняет следующие задачи:
- Создает новый SmsClient объект и передает в него строка подключения ACS (это значение извлекается из переменной ACS_CONNECTION_STRING среды).
```
const smsClient = new SmsClient(connectionString);
```
- smsClient.send() Вызывает функцию и передает номер телефона ACS (), номер телефона клиента (fromto) и SMS-сообщение:
```
const sendResults = await smsClient.send({
    from: process.env.ACS_PHONE_NUMBER as string,
    to: [customerPhoneNumber],
    message: message
});
return sendResults;
```
- Возвращает ответ вызывающего абонента.
Дополнительные сведения о функциях электронной почты ACS и SMS см. в следующих статьях:
- Электронная почта в Службы коммуникации Azure
- SMS в Службы коммуникации Azure
Прежде чем перейти к следующему упражнению, давайте рассмотрим основные понятия, описанные в этом упражнении:
- Файл acs.service.ts инкапсулирует функции электронной почты ACS и SMS, используемые клиентским приложением. Он обрабатывает вызовы API к серверу и возвращает ответ вызывающему объекту.
- API на стороне сервера использует ACS EmailClient и SmsClient объекты для отправки сообщений электронной почты и SMS.
Теперь, когда вы узнали, как можно отправлять сообщения электронной почты и SMS, давайте переключим наше внимание на интеграцию данных организации в приложение.

Организационные данные: создание регистрации приложения идентификатора Записи Майкрософт

Осталось 59 мин

Повышение производительности пользователей путем интеграции данных организации (сообщений электронной почты, файлов, чатов и событий календаря) непосредственно в пользовательские приложения. Используя API Microsoft Graph и идентификатор Microsoft Entra, вы можете легко получать и отображать соответствующие данные в приложениях, уменьшая потребность пользователей в переключении контекста. Указывает, ссылается ли сообщение электронной почты, отправленное клиенту, просмотр сообщения Teams или доступ к файлу, пользователи могут быстро найти нужную информацию, не выходя из приложения, оптимизируя процесс принятия решений.

В этом упражнении вы выполните следующие действия.

Создайте регистрацию приложения идентификатора Microsoft Entra, чтобы Microsoft Graph смог получить доступ к данным организации и перенести его в приложение.
Поиск team и channel идентификаторы из Microsoft Teams, необходимые для отправки сообщений чата в определенный канал.
Обновите env-файл проекта со значениями из регистрации приложения идентификатора Microsoft Entra.

Обзор сценария Microsoft Cloud

Создание регистрации приложений идентификатора записи Майкрософт

Перейдите к портал Azure и выберите идентификатор Microsoft Entra.
Выберите "Управление -->Регистрация приложений", а затем + Новая регистрация.
Введите сведения о новой форме регистрации приложения, как показано ниже, и нажмите кнопку "Зарегистрировать".
- Имя: microsoft-graph-app
- Поддерживаемые типы учетных записей: учетные записи в любом каталоге организации (любой клиент идентификатора Microsoft Entra — Multitenant)
- URI перенаправления:
  - Выберите одностраничные приложения (SPA) и введите http://localhost:4200 в поле URI перенаправления.
- Щелкните Зарегистрировать, чтобы создать регистрацию приложения.

Выберите "Обзор" в меню ресурсов и скопируйте 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 и веб-сервер, выполните следующие действия.
1. В следующих шагах вы создадите три окна терминала в Visual Studio Code.
2. Щелкните правой кнопкой мыши env-файл в списке файлов Visual Studio Code и выберите "Открыть в интегрированном терминале". Перед продолжением убедитесь, что терминал находится в корне проекта — openai-acs-msgraph .
3. Выберите один из следующих параметров, чтобы запустить базу данных 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 postgres
```
    - Windows с 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
```
4. После запуска контейнера базы данных нажмите + значок на панели инструментов терминала Visual Studio Code, чтобы создать второе окно терминала.
5. cd в папку server/typescript и выполните следующие команды, чтобы установить зависимости и запустить сервер API.
  - npm install
  - npm start
6. + Нажмите значок еще раз на панели инструментов терминала Visual Studio Code, чтобы создать третье окно терминала.
7. cd в папку клиента и выполните следующие команды, чтобы установить зависимости и запустить веб-сервер.
  - npm install
  - npm start
8. Откроется браузер, в который вы http://localhost:4200перейдете.

Организационные данные: вход пользователя и получение маркера доступа

Осталось 51 мин

Пользователям необходимо пройти проверку подлинности с помощью идентификатора 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, используемых в приложении.
```
import { registerMgtLoginComponent, registerMgtSearchResultsComponent, registerMgtPersonComponent,  } from '@microsoft/mgt-components';
```
Прокрутите внизу файла и запишите следующий код:
```
registerMgtLoginComponent();
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. Вы увидите следующий импорт и код:
```
import { 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.
```
@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.microsoft365Enabled trueзначения. Этот пользовательский флаг проверяет наличие переменной ENTRAID_CLIENT_ID среды, чтобы убедиться, что приложение правильно настроено и может пройти проверку подлинности в идентификаторе Microsoft Entra. Флаг добавляется для размещения случаев, когда пользователи предпочитают выполнять только упражнения ИИ или коммуникации в рамках руководства, а не после всей последовательности упражнений.
Откройте header.component.ts и найдите функцию loginCompleted . Эта функция вызывается, когда loginCompleted событие создается и обрабатывает извлечение вошедшего в систему профиля пользователя с помощью Providers.globalProvider.
```
async 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

Осталось 41 мин

В современной цифровой среде пользователи работают с широким набором данных организации, включая сообщения электронной почты, чаты, файлы, события календаря и многое другое. Это может привести к частым сменам контекста — переключению между задачами или приложениями, что может нарушить фокус и снизить производительность. Например, пользователю, работающему над проектом, может потребоваться переключиться с текущего приложения в 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и другие, которые вы видели ранее:
```
Providers.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 и обратите внимание на следующие атрибуты:
```
<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. Если поисковый запрос не передается, возвращается пустой массив.
```
async searchFiles(query: string) {
    const files: DriveItem[] = [];
    if (!query) return files;

    ...
}
```
- Затем создается фильтр, определяющий тип выполняемого поиска. В этом случае код ищет файлы в OneDrive для бизнеса поэтому driveItem используется так же, как вы видели ранее с компонентомmgt-search-results. Это то же самое, что передача driveItem entity-types в компонент mgt-search-results , который вы видели ранее. Затем параметр query добавляется в queryString фильтр вместе с ContentType:Document.
```
const filter = {
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": `${query} AND ContentType:Document`
            }
        }
    ]
};
```
- Затем вызов выполняется в /search/query API Microsoft Graph с помощью Providers.globalProvider.graph.client.api() функции. Объект filter передается post() функции, которая отправляет данные в API.
```
const searchResults = await Providers.globalProvider.graph.client.api('/search/query').post(filter);
```
- Затем результаты поиска итерируются для поиска hits. Каждый hit содержит сведения о найденном документе. Свойство с именем resource содержит метаданные документа и добавляется в files массив.
```
if (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 массив возвращается вызывающей объекту.
```
return 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 свойству компонента.
```
override async search(query: string) {
    this.data = await this.graphService.searchFiles(query);
}
```
Затем компонент файлов может использовать data свойство для отображения результатов поиска. Это можно обрабатывать с помощью пользовательских привязок HTML или с помощью другого элемента управления Microsoft Graph Toolkit с именем mgt-file-list. Ниже приведен пример привязки data свойства к одному из свойств компонента с именем files и обработкой itemClick события по мере взаимодействия пользователя с файлом.
```
<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 и teamIdchannelIdAPI выполняется /teams/${chat.teamId}/channels/${chat.channelId}/messages/${chat.messageId} второй вызов, который передается.messageId Возвращает полные сведения о сообщении.
- Выполняются дополнительные задачи фильтрации, а полученные сообщения возвращаются вызывающей searchChatMessages() программе.
Откройте файл chats.component.ts и найдите функциюsearch(). Полный путь к файлу — client/src/app/chats/chats.component.ts. Функция search() вызывается searchChatMessages() в graph.service.ts и передает query параметр в него.
```
override async search(query: string) {
    this.data = await this.graphService.searchChatMessages(query);
}
```
Результаты поиска назначаются data свойству компонента и привязке данных используются для итерации по массиву результатов и отрисовки данных. В этом примере для отображения результатов поиска используется компонент карточки Angular Material.
```
@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-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}/messages Microsoft Graph.

В следующем коде вы увидите, что создается URL-адрес, включающий teamId значения и channelId значения. Значения переменной среды используются для идентификатора команды и идентификатора канала в этом примере, но эти значения могут быть динамически получены, а также с помощью Microsoft Graph. Константа body содержит сообщение для отправки. Затем выполняется запрос POST, и результаты возвращаются вызывающей объекту.

async 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 непосредственно из приложения, которое они уже используют.

Организационные данные: получение сообщений электронной почты и событий календаря

Осталось 21 мин

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

@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/query API, который вы видели ранее, может быть использован, но более простой messages вариант — ЭТО API.
Чтобы узнать, как вызвать этот API, вернитесь к graph.service.ts и найдите функцию searchEmailMessages() . Он создает URL-адрес, который можно использовать для вызова messages конечной точки Microsoft Graph и присваивает query значение параметру $search . Затем код выполняет запрос GET и возвращает результаты вызывающей объекту. Оператор $search автоматически ищет query значение в полях темы, текста и отправителя.
```
async 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;
}
```
Компонент электронной почты, расположенный в emails.component.ts звонкахsearchEmailMessages(), отображает результаты в пользовательском интерфейсе.
```
override 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. Вы увидите, что это очень похоже на файлы и компоненты электронной почты, которые вы рассмотрели ранее.
```
<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 и расположения события, если он указан.

@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/query API, Microsoft Graph также предоставляет events API, который также можно использовать для поиска событий календаря. Найдите функцию searchCalendarEvents() в graph.service.ts.
Функция searchCalendarEvents() создает значения даты и окончания, используемые для определения периода времени для поиска. Затем он создает URL-адрес, который можно использовать для вызова events конечной точки Microsoft Graph и включает query параметр и переменные даты и окончания. Затем выполняется запрос GET, и результаты возвращаются вызывающей объекту.
```
async 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/events URL-адреса используется для указания того, что события вошедшего пользователя должны быть извлечены.
  - enddatetime Параметры startdatetime используются для определения периода времени для поиска. В этом случае поиск вернет события, начинающиеся в течение следующих 7 дней.
  - Параметр $filter запроса используется для фильтрации результатов по query значению (имя компании, выбранное из datagrid в этом случае). Функция contains() используется для поиска query значения в subject свойстве события календаря.
  - Параметр $orderby запроса используется для упорядочивания результатов свойством start/dateTime .
url После создания запрос GET выполняется в API Microsoft Graph, используя значениеurl, и результаты возвращаются вызывающей программе.
Как и в предыдущих компонентах, вызовы search() компонента событий календаря (calendar-events.component.ts файла) и отображение результатов.
```
override 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 можно просмотреть в документации.

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

Интеграция функций OpenAI, коммуникации и организационных данных в бизнес-приложение

Что вы создадите в этом руководстве

Выбор собственного приключения

Необходимые компоненты

Технологии Microsoft Cloud, используемые в этом руководстве

Клонирование проекта

Клонирование репозитория GitHub и создание .env файла

ИИ: создание ресурса Azure OpenAI и развертывание модели

Создание ресурса службы Azure OpenAI

Обновление файла проекта .env

Запуск служб приложений

ИИ: естественный язык для SQL

Использование естественного языка для компонента SQL

Изучение естественного языка в КОДе SQL

ИИ: создание завершений

Использование функции завершения ИИ

Изучение кода завершения ИИ

ИИ: Azure OpenAI в данных

Добавление пользовательского источника данных в Azure AI Studio

Использование пользовательского источника данных на площадке чата

Использование собственной функции данных в приложении

Изучение кода

Обмен данными. Создание ресурса Службы коммуникации Azure

Создание ресурса Службы коммуникации Azure

Включение возможностей звонков и SMS

Подключение домена электронной почты

.env Обновление файла

Запуск и перезапуск серверов приложений и API

Обмен данными: звонок по телефону

Использование функции звонков по телефону

Изучение кода звонков по телефону

Коммуникация: отправка сообщений электронной почты и SMS

Использование функций электронной почты и SMS

Изучение кода электронной почты

Изучение SMS-кода

Организационные данные: создание регистрации приложения идентификатора Записи Майкрософт

Создание регистрации приложений идентификатора записи Майкрософт

Обновление env-файла проекта

Запуск и перезапуск серверов приложений и API

Организационные данные: вход пользователя и получение маркера доступа

Использование функции входа

Изучение кода входа

Организационные данные: получение файлов, чатов и отправки сообщений в Teams

Использование функции данных организации

Изучение кода поиска файлов

Изучение кода поиска сообщений чата Teams

Отправка сообщения в канал Microsoft Teams

Организационные данные: получение сообщений электронной почты и событий календаря

Изучение кода поиска сообщений электронной почты

Изучение кода поиска событий календаря

Поздравляем!

Вы завершили работу с этим руководством

Очистка ресурсов Azure

Next Steps

Документация

Обучающее содержимое

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

Клонирование репозитория GitHub и создание `.env` файла

Обновление файла проекта `.env`

`.env` Обновление файла