Работа с глобальными переменными

Переменные хранят ответы ваших клиентов на вопросы агента. Например, вы можете сохранить имя клиента в переменной с именем UserName. Затем агент может обратиться к клиенту по имени, поскольку разговор продолжается.

По умолчанию значение переменной может использоваться только в теме, в которой эта переменная создана. Однако можно повторно использовать одно и то же значение в разных темах. Например, в теме "Добро пожаловать" запрашивается имя клиента и адрес электронной почты. В теме «Резервирование встречи» нужно, чтобы агент запомнил, что ввел клиент, и не переспрашивал.

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

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

Создание глобальной переменной

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

Заметка

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

Веб-приложение

1. Создайте переменную или используйте панель «Переменные», чтобы открыть существующую переменную.

2. На панели Свойства переменной выберите Глобальная (любая тема может получить доступ).

   Имя переменной получает префикс Global., чтобы отличить ее от переменных уровня темы. Например, переменная UserName отображается как Global.UserName.

3. Сохраните тему.

Классическое/Teams

1. Выберите требуемую переменную.

2. На панели Свойства переменной в разделе Использование выберите Бот (любая тема может получить доступ).

3. Имя переменной помечается префиксом bot., чтобы отличать ее от переменных уровня темы. Например, переменная UserEmail теперь отображается как bot.UserEmail.

Использование глобальных переменных

Веб-приложение

Когда вы создаете сообщение в узле Сообщение или Вопрос, выберите значок {x} для просмотра переменных, доступных для темы. Глобальные переменные отображаются на вкладке Пользовательские вместе с любыми переменными темы. Переменные перечислены в алфавитном порядке.

Классическое/Teams

Когда вы создаете сообщение в узле Сообщение или Вопрос, выберите значок {x} для просмотра переменных, доступных для темы. Переменные перечислены в алфавитном порядке, и все глобальные переменные отображаются вместе, потому что все они начинаются с bot..

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

Поиск всех тем, использующих глобальную переменную

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

Веб-приложение

1. Выберите нужную глобальную переменную на холсте разработки или на панели Переменные.

2. На панели Свойства переменной в разделе Ссылка выберите Просмотреть все ссылки.

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

Классическое/Teams

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

• Чтобы перейти непосредственно к узлу, в котором была создана глобальная переменная, выберите Перейти к источнику.

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

Удаление глобальных переменных

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

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

Темы с узлами, которые содержат ссылки на удаленные глобальные переменные, могут перестать работать. Перед публикацией агента убедитесь, что вы удалили или исправили все темы, которые использовали удаленную переменную.

Жизненный цикл глобальных переменных

Веб-приложение

По умолчанию значение глобальной переменной сохраняется до тех пор, пока сеанс не завершится. Узел Очистить значения переменных сбрасывает значения глобальных переменных и используется в системной теме Сброс разговора. Когда перенаправление активирует эту тему (или когда пользователь вводит фразу, например "Начать сначала"), все глобальные переменные сбрасываются.

Классическое/Teams

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

Значение очищается только тогда, когда пользователь агента перенаправлен в системную тему Начать сначала или когда пользователь запускает эту тему напрямую (например, набрав «Начать сначала»). В этом случае все глобальные переменные сбрасываются и не имеют значения.

Инициализация глобальной переменной

Если глобальная переменная запускается до того, как была инициализирована (или "заполнена"), агент автоматически запускает ту часть темы, где глобальная переменная была впервые определена, — даже если она находится в другой теме, — прежде чем вернуться к оригинальной теме. Такое поведение позволяет агенту заполнить все переменные, не прерывая разговор.

Например, клиент начинает разговор по теме "резервирование встречи", в которой глобальная переменная bot.UserName используется. Однако переменная bot.UserName сначала определяется в теме "Добро пожаловать".

Когда разговор доходит до точки в разделе темы "резервирование встречи", где имеется ссылка на bot.UserName, агент плавно переходит к узлу вопроса, где сначала определяется bot.UserName.

После того как клиент ответит на вопрос, агент возобновляет тему "Резервирование встречи".

Поведение глобальной переменной при реализации действий через потоки Power Automate или навыки

Иногда вы можете использовать поток или навык для инициализации или заполнения переменной.

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

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

Установка глобальных переменных из внешних источников

Веб-приложение

Чтобы убедиться, что агент начинает разговор с каким-либо контекстом, вы можете использовать глобальную переменную и задать ее значение из внешнего источника. Допустим, ваш сайт требует от пользователей входа в систему. Если вы сохраните имя пользователя в глобальной переменной и передадите его своему агенту, агент сможет приветствовать клиентов по имени до того, как они начнут вводить свой первый вопрос. Другим примером сценария является передача контекста из Dynamics 365 Customer Service агенту, чтобы он мог начать разговор со знанием того, чего хочет достичь клиент.

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

Заметка

Агенты, опубликованные в канале Dynamics 365 Contact Center для сценариев использования IVR, не поддерживают значения времени ожидания, настроенные для глобальных переменных, заданных внешними источниками.

1. Создайте специальную тему для хранения конфигурации для всех переменных, которые должны быть установлены из внешних источников. Например, вы можете назвать эту тему "Установка переменных контекста". Этот раздел не служит никаким другим целям, поэтому в нем не нужно задавать фразы-триггеры.

2. Добавьте узел Задать значение переменной в специальную тему.

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

4. Выберите имя новой переменной по умолчанию. Появится панель Свойства переменной.

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

6. В разделе Использование выберите Глобальная (доступна из любой темы) и Внешние источники могут задавать значения.

7. В разделе Ссылка выберите три точки (⋮) в правом верхнем углу и выберите Получить значение из этого узла, если пусто.

8. (Дополнительный) Задайте задержку тайм-аута в миллисекундах. Это значение определяет, как долго агент может ожидать установки переменной внешним источником, прежде чем истечет время ожидания и он продолжит со значением по умолчанию, заданным в узле Задать значение переменной. Этот параметр актуален в сценариях, где переменная зависит от длительного или асинхронного процесса, но агент должен соблюдать максимальную задержку для обеспечения хорошего взаимодействия с пользователем.

   Для переменных, поступающих из Многоканального взаимодействия для Customer Service, мы предлагаем значение 10 секунд (10 000 мс) в качестве максимального времени ожидания.

9. В узле Задать значение переменной введите значение по умолчанию, которое будет использоваться по истечении времени ожидания. Во время выполнения агент будет ожидать значения с тем же типом данных. Если вы хотите, чтобы это значение по умолчанию было пустой строкой, используйте Text("") в качестве формулы.

   

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

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

Внимание!

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

Классическое/Teams

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

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

1. Выберите нужную глобальную переменную.

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

Установите глобальные переменные во встроенном агенте

Веб-приложение

Если вы встраиваете свой агент в простую веб-страницу, вы можете добавить переменные и их определения к URL-адресу агента. Или, если вы хотите немного больше контроля, вы можете использовать блок кода <script> для программного вызова и использования переменных.

Имя переменной в строке запроса URL-адреса должно совпадать с именем глобальной переменной, без префикса Global.. Например, глобальная переменная Global.UserName в запросе будет указываться как UserName.

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

Добавьте переменные и их определения в URL-адрес агента как параметры строки запроса в формате botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

Например:

• У вас есть глобальная переменная с именем Global.UserName.
• URL-адрес вашего агента https://web.powerva.microsoft.com/webchat/bots/12345.
• Чтобы передать имя пользователя при запуске разговора агента на веб-сайте, прикрепите строку запроса UserName= как: https://web.powerva.microsoft.com/webchat/bots/12345?UserName=Ana.

Имя параметра не зависит от регистра. username=Ana будет работать и в этом примере.

Классическое/Teams

Вы можете добавить переменные и их определения, если вы просто встроите ваш агент в простую веб-страницу, или вы можете использовать блок кода <script> для программного вызова и использования переменных.

Заметка

Имя переменной в строке запроса должно совпадать с именем глобальной переменной, без префикса bot.. Например, глобальная переменная bot.UserEmail должна отображаться как UserEmail=.

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

1. Добавьте переменные и их определения в URL-адрес агента как параметры строки запроса (в формате botURL?variableName1=variableDefinition1&variableName2=variableDefinition2), например:

   • У вас есть глобальная переменная с именем bot.UserEmail.
   • URL-адрес вашего агента https://web.powerva.microsoft.com/webchat/bots/12345.
   • Чтобы передать имя пользователя при запуске разговора агента на веб-сайте, вы можете прикрепить строку запроса UserEmail= как: https://web.powerva.microsoft.com/webchat/bots/12345?UserEmail=Ana@contoso.com.

2. Имя параметра не зависит от регистра. Это означает, что useremail=Ana@contoso.com также работало бы в этом примере.

Добавление глобальных переменных на пользовательский холст

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

Веб-приложение

1. В разделе <script> на странице, где у вас есть агент, определите переменные следующим образом, подставив variableName1 для имени переменной без префикса Global. и variableDefinition1 для определения. Разделите несколько переменных запятыми (,).

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. В разделе <script> вызовите store, когда вы встраиваете свой агент, как в следующем примере, где store вызывается непосредственно перед вызовом styleOptions (вы должны заменить BOT_ID идентификатором вашего агента):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));
   

Классическое/Teams

1. В разделе <script> на странице, где у вас есть агент, определите переменные следующим образом, подставив variableName1 для имени переменной без префикса bot. и variableDefinition1 для определения. Разделите несколько переменных запятыми ,,

      const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
        if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
          dispatch({
             type: "WEB_CHAT/SEND_EVENT",
             payload: {
               name: "pvaSetContext",
               value: {
                  "variableName1": "variableDefinition1",
                  "variableName2": "variableDefinition2"
               }
             },
           });
         }
           return next(action);
       });
   

2. В разделе <script> вызовите store, когда вы встраиваете свой агент, как в следующем примере, где store вызывается непосредственно перед вызовом styleOptions (вы должны заменить BOT_ID вашим идентификатором):

   const BOT_ID = "12345-5678";
   const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
   fetch(theURL)
       .then(response => response.json())
       .then(conversationInfo => {
           window.WebChat.renderWebChat(
               {
                   directLine: window.WebChat.createDirectLine({
                       token: conversationInfo.token,
                   }),
                   store,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })
       .catch(err => console.error("An error occurred: " + err));
   

Глобальные переменные, связанные с аутентификацией

В зависимости от настроек аутентификации агента вам доступен набор глобальных переменных, связанных с выбранным поставщиком аутентификации. Подробнее о том, какой набор переменных доступен и как их использовать, см. в теме Добавление аутентификации пользователя в темы.

---

Связанный контент

• Работа с переменными
• Настройка внешнего вида агента