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

Note

Функции, описанные в этой статье, питаются стандартным жгутом, который использует опции выставления счетов, описанные в разделе «Лицензирование для агентов, работающих на стандартном жгуте». Узнайте, как получить доступ к стандартным функциям в стандартных агентах и потоках агентов доступа.

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

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

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

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

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

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

Note

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

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

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

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

3. Сохраните раздел.

План команд

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

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

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

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

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

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

План команд

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

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

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

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

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

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

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

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

План команд

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

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

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

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

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

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

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

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

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

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

План команд

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Note

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

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

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

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

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

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

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

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

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

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

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

   

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

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

Important

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

План команд

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

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

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 также работает в данном примере.

План команд

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

Note

Имя переменной в строке запроса должно совпадать с именем глобальной переменной, без префикса 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));
   

План команд

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));
   

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

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

---

Связанные материалы

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