Переменные помощника применяются во время одного сеанса пользователя. Вы указываете, какие переменные следует рассматривать как переменные помощника, чтобы отличать их от переменных уровня темы.
Создание глобальной переменной
Вы создаете глобальную переменную, изменяя область действия переменной темы.
Создайте переменную или используйте панель Переменные, чтобы открыть существующую переменную.
На панели Свойства переменной выберите Глобальная (любая тема может получить доступ).
Имя переменной получает префикс Global.
, чтобы отличить ее от переменных уровня темы. Например, переменная UserName
отображается как Global.UserName
.
Сохраните тему.
Имя глобальной переменной должно быть уникальным во всех темах. В случае конфликта вам необходимо переименовать переменную перед сохранением темы.
Использование глобальных переменных
При составлении сообщения помощника в узле «Сообщение» или узле «Вопрос» выберите значок {x} для просмотра переменных, доступных теме. Глобальные переменные отображаются на вкладке Пользовательские вместе с любыми переменными темы. Переменные перечислены в алфавитном порядке.
Поиск всех тем, использующих глобальную переменную
Вы можете найти, где глобальная переменная определена и какие другие темы ее используют. Это может быть полезно, если вы работаете над новым помощником или если у вас есть несколько переменных и сложное ветвление тем.
Выберите глобальную переменную на холсте разработки или откройте панель Переменные и выберите глобальную переменную.
На панели Свойства переменной в разделе Ссылка выберите любую из тем, где используется переменная, чтобы перейти напрямую к этой теме и узлу.
Жизненный цикл глобальных переменных
По умолчанию значение глобальной переменной сохраняется до тех пор, пока сеанс не завершится. Узел Очистить значения переменных сбрасывает значения глобальных переменных и используется в системной теме Сброс разговора. Эта тема может запускаться либо путем перенаправления, либо когда пользователь вводит триггерную фразу, например «Начать сначала». В этом случае все глобальные переменные сбрасываются.
Установка значения глобальной переменной из внешних источников
Если вы хотите быть уверенным, что помощник начнет разговор с некоторым контекстом, вы можете инициализировать глобальную переменную с помощью внешнего источника. Допустим, ваш сайт требует от пользователей входа в систему. Поскольку ваш помощник уже знает имя пользователя, он может приветствовать клиентов по имени, прежде чем они начнут вводить свой первый вопрос.
Выберите глобальную переменную.
На панели Свойства переменных выберите Внешние источники могут задавать значения.
Установите глобальные переменные во встроенном помощнике
Если вы встраиваете свой помощник в простую веб-страницу, вы можете добавить переменные и их определения к URL-адресу помощника. Или, если вы хотите немного больше контроля, вы можете использовать блок кода <script>
для программного вызова и использования переменных.
Имя переменной в строке запроса URL-адреса должно совпадать с именем глобальной переменной, без префикса Global.
. Например, глобальная переменная Global.UserName
в запросе будет указываться как UserName
.
В приведенных ниже примерах представлено простое объявление для переменных. В производственном сценарии вы можете передать в качестве параметра запроса или определения переменной другую переменную, в которой уже сохранено имя пользователя (например, если у вас есть имя пользователя из сценария входа).
Добавьте переменные и их определения в URL-адрес помощника как параметры строки запроса (в формате botURL?variableName1=variableDefinition1&variableName2=variableDefinition2
).
Например:
Имя параметра не зависит от регистра.
username=Renata
также будет работать в этом примере.
Добавление глобальных переменных на пользовательский холст
Вы также можете добавить переменную на пользовательский холст.
В разделе <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);
});
Внутри вашего раздела <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));
Переменные помощника применяются во время одного сеанса пользователя. Вы указываете переменные, которые рассматриваются как переменные помощника, чтобы отличать их от переменных уровня темы.
Задание переменных помощника
После того как вы установите переменную помощника, она будет доступна всем темам.
Когда вы выбираете кнопку {x}
в узле сообщения или узле вопроса при составлении сообщения помощника, вы увидите, что переменная помощника доступна. Переменные отсортированы в алфавитном порядке, поэтому вы обнаружите, что все переменные помощника сгруппированы в меню переменных, потому что все они начинаются с символов copilot.
.
Когда вы используете узел условия, узел действия потока или узел навыка, вы также увидите доступные для него переменные помощника.
Повторно используйте переменную в разных темах, установив ее как переменную помощника
Выберите любую переменную на холсте разработки.
На панели Свойства переменной в разделе Использование выберите помощник (любая тема может получить доступ).
Имя переменной получит префиксную строку copilot.
, чтобы дифференцировать ее от переменных уровня темы. Например, переменная UserName
теперь отображается как copilot.UserName
.
Заметка
Имя переменной помощника должно быть уникальным во всех темах. В случае конфликта вам необходимо переименовать переменную перед сохранением изменений.
Управление переменными помощника
После того, как вы создали переменную помощника, вы можете увидеть, где она впервые определена и какие другие темы ее используют. Это может быть полезно, если вы работаете над новым помощником или если у вас есть несколько переменных и сложное ветвление тем.
Переход к источнику определения переменной помощника
Выберите любую переменную на холсте разработки.
На панели Свойства переменной выберите Перейти к источнику.
Это приведет вас к узлу в теме, где была создана переменная помощника.
Поиск всех тем, использующих переменную помощника
Выберите любую переменную помощника на холсте разработки.
На панели Свойства переменной в разделе Используется выберите любую из тем, где используется переменная, чтобы перейти прямо к этой теме и узлу.
Инициализация переменной помощника
Если переменная помощника запускается до того, как была инициализирована (или "заполнена"), помощник автоматически вызывает ту часть темы, где переменная помощника была впервые определена, — даже если она находится в другой теме, — прежде чем вернуться к оригинальной теме. Это позволяет помощнику заполнить все переменные, не прерывая разговор.
Например, клиент начинает разговор по теме "резервирование встречи", в которой переменная помощника copilot.UserName
используется. Однако переменная copilot.UserName
сначала определяется в теме "Добро пожаловать".
Когда разговор доходит до точки в разделе темы "резервирование встречи", где имеется ссылка на copilot.UserName
, помощник плавно переходит к узлу вопроса, где сначала определяется copilot.UserName
.
После того как клиент ответит на вопрос, помощник возобновляет тему "резервирование встречи".
Поведение переменной помощника при реализации "Действий" через потоки Power Automate или навыки
Иногда вы можете использовать поток или навык для инициализации или заполнения переменной в помощнике.
Однако, когда пользователь взаимодействует с помощником, переменная может быть заполнена на более раннем этапе разговора, или у вас могут быть уже установлены переменные извне.
В этой ситуации поток или навык по-прежнему будут выполняться и заполнять переменную, перезаписывая все, что было ранее сохранено в переменной.
Жизненный цикл переменных помощника и сброс их значения
Переменные помощника доступны из любой темы, и присвоенное значение переменной помощника сохраняется на всем протяжении сеанса.
Значение очищается только тогда, когда пользователь помощника перенаправлен в системную тему Начать сначала или когда пользователь запускает эту тему напрямую (например, набрав Начать сначала). В этом случае все переменные помощника будут сброшены и не будут иметь никаких значений.
Установка значения переменной помощника из внешних источников
Вы можете установить переменную помощника для инициализации с помощью внешнего источника. Это позволяет помощнику начать разговор с некоторого контекста.
Например, клиент открывает чат помощника с вашего веб-сайта, и сайт уже знает имя клиента. Вы сообщаете помощнику имя пользователя до начала разговора, и помощник может вести более умный разговор с клиентом, не спрашивая его имя снова.
Установка значения переменной помощника из внешнего источника
Выберите любую переменную на холсте разработки.
На панели Свойства переменной в разделе Использование установите флажок Внешние источники могут задавать значения.
Вы можете добавить переменные и их определения, если вы просто встроите ваш помощник в простую веб-страницу, или вы можете использовать блок кода <script>
для вызова и использования переменных программно.
Заметка
Имя переменной в строке запроса должно совпадать с именем переменной помощника, без префикса copilot.
. Например, переменная помощника copilot.UserName
должна быть представлена как UserName=
.
В описанных здесь примерах для переменных сделано простое объявление. В производственном сценарии вы можете передать в качестве параметра запроса или определения переменной другую переменную, в которой уже сохранено имя пользователя (например, если у вас есть имя пользователя из сценария входа).
Чтобы добавить переменную во встроенный помощник
Добавьте переменные и их определения в URL-адрес помощника как параметры строки запроса (в формате botURL?variableName1=variableDefinition1&variableName2=variableDefinition2
), например:
Имя параметра не зависит от регистра. Это означает, что username=Renata
также будет работать в этом примере.
В разделе <script>
на странице, где у вас есть помощник, определите переменные следующим образом, подставив variableName1
для имени переменной без префикса copilot.
и 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);
});
Внутри вашего раздела <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));
Удаление переменных помощника
При удалении переменной помощника, используемой в других темах, ссылки на эту переменную в темах будут помечены как Unknown
.
Вы получите предупреждение об удалении переменной помощника, прежде чем сможете подтвердить операцию.
Узлы, которые содержат ссылки на удаленную переменную помощника, сообщат вам, что они содержат неизвестную переменную.
Темы с узлами, которые содержат ссылки на удаленные переменные помощника, могут перестать работать. Перед публикацией убедитесь, что вы удалили или исправили все темы, которые использовали удаленную переменную.
В зависимости от настроек аутентификации помощника вам будет доступен набор переменных помощника, связанных с поставщиком аутентификации. Подробнее о том, какой набор переменных доступен и как их использовать, см. в теме Добавление аутентификации конечного пользователя в темы.
Поиск всех тем, использующих переменную помощника в Teams
Выберите любую переменную помощника на холсте разработки.
На панели Свойства переменной в разделе Используется выберите любую из тем, где используется переменная, чтобы перейти прямо к этой теме и узлу.
Удаление переменных помощника
При удалении переменной помощника, используемой в других темах, ссылки на эту переменную в темах будут помечены как Unknown
.
Вы получите предупреждение об удалении переменной помощника, прежде чем сможете подтвердить операцию.
Узлы, которые содержат ссылки на удаленную переменную помощника, сообщат вам, что они содержат неизвестную переменную.
Темы с узлами, которые содержат ссылки на удаленные переменные помощника, могут перестать работать. Перед публикацией убедитесь, что вы удалили или исправили все темы, которые использовали удаленную переменную.
Расширенное использование переменных помощника
Дополнительные сведения о сложных и расширенных сценариях использования переменных помощника, включая аутентификацию, внешние источники и потоки инициализации, см. в версии веб-приложения Microsoft Copilot Studio этой статьи.