Обзор переменных

Note

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

Переменные существуют на четырех уровнях, или областях:

• Переменные тем вы можете использовать только в тех темах, где они созданы. Это область действия по умолчанию для создаваемых вами переменных.
• Глобальные переменные можно использовать во всех темах. Вы можете изменить область действия переменной темы, чтобы сделать ее глобальной.
• Системные переменные, которые Copilot Studio автоматически создает для агента. Они предоставляют больше контекстной информации о разговоре или пользователе. Они доступны во всех темах.
• Переменные среды, которые вы создаете в Power Platform. В Copilot Studio они доступны только для чтения. Они хранят ключи и значения параметров, которые затем могут служить входными данными для различных других объектов приложения, включая Copilot Studio. Отделение параметров от объектов-потребителей позволяет изменять значения в той же среде или при переносе решений в другие среды. Альтернативный вариант — оставить жестко запрограммированные значения параметров в компонентах, которые их используют.

Типы переменных

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

Type	Описание
String	Последовательность символов, используемая для представления текста
Логический	Логическое значение, которое может быть только true или false
Number	Любое вещественное число
таблица	Список значений, но все значения должны быть одного типа
Запись	Коллекция пар имя-значение, где значения могут быть любого типа
DateTime	Дата, время, день недели или месяц относительно момента времени
Выбор	Список строковых значений с соответствующими синонимами
Пустое значение	Заполнитель для "нет значения" или "неизвестного значения"; подробнее см. в разделе Blank в документации Power Fx

Тип переменной задается при первом присвоении ей значения. После этого тип фиксируется, и вы не можете присваивать значения какого-либо другого типа. Например, если вы присваиваете переменной начальное значение 1, ее тип становится Число. Если затем вы попробуете присвоить строковое значение, например "apples", вы получите ошибку.

При тестировании агента может временно появиться переменная с типом неизвестный. Переменная с типом "неизвестный" пока не имеет значения.

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

При создании ветвей с помощью узлов Условие Copilot Studio упорядочивает ветви слева направо. Агент рассматривает узлы в крайней левой ветви перед узлами в крайней правой ветви.

Entities

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

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

Объект	Базовый тип переменной
Параметры с несколькими вариантами выбора	Выбор
Весь ответ пользователя	String
Возраст	Number
Логический	Логический
Город	String
Цвет	String
Continent	String
Страна или регион	String
дата и время;	DateTime
Адрес электронной почты	String
Event	String
Integer	Integer
Language	String
Деньги	Number
Number	Number
Порядковый	Number
Предприятие	String
Процент	Number
Имя	String
Номер телефона	String
Точка интереса	String
Скорость	Number
State	String
Адрес улицы	String
Температура	Number
URL	String
Weight	Number
Почтовый индекс	String
Настраиваемый объект	Выбор

План Teams

Copilot Studio использует сущности для определения определенных типов информации из ответов пользователя. Идентифицированная информация сохраняется в переменной того типа, который подходит для этой информации.

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

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

Объект	Базовый тип переменной
Варианты множественного выбора	String
Весь ответ пользователя	String
Возраст	Number
Логический	Логический
Город	String
Цвет	String
Continent	String
Страна или регион	String
дата и время;	String
Продолжительность	String
Адрес электронной почты	String
Event	String
Language	String
Деньги	String
Number	String
Порядковый	String
Предприятие	String
Процент	Number
Имя	String
Номер телефона	String
Точка интереса	String
Скорость	Number
State	String
Адрес улицы	String
Температура	Number
URL	String
Weight	Number
Почтовый индекс	String
Настраиваемый объект	String

Переменные среды

Переменные среды — это концепция Power Platform. Переменные среды позволяют использовать базовый сценарий управления жизненным циклом приложения (ALM) для перемещения приложения между средами Power Platform. В этом сценарии приложение остается точно таким же, за исключением нескольких ключевых внешних ссылок, которые различаются в исходной среде и целевой среде.

Используйте переменные среды таким же образом, как переменные темы, глобальные переменные и системные переменные. Одно из заметных отличий заключается в том, что переменные среды доступны только для чтения в Copilot Studio. Авторы агентов не могут изменять переменные среды в Copilot Studio. Однако администраторы могут изменять значение переменных среды в Power Apps. В Copilot Studio можно использовать панель "Переменные" для просмотра информации о переменной среды. Панель свойств переменной также содержит ссылку на Power Apps — интерфейс для создания переменных среды.

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

Типы переменных среды в Copilot Studio сопоставляются с типами данных Power Apps следующим образом:

Тип в Copilot Studio	Тип в Power Apps
Десятичное число	Number
JSON	Тип определяется по значению. Если не JSON => Не указано (ошибка проверки)
Text	String
Логический	Логический
Источник данных	String
Secret	String

Note

Ошибки переменных среды видны в тестовом чате и при публикации. Однако в списке Темы эти ошибки не отображаются, так как переменные среды не являются переменными тем.

Системные переменные

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

Copilot Studio не показывает все системные переменные. Чтобы получить доступ к скрытым системным переменным, используйте формулу Power Fx.

Чтобы использовать системные переменные в формуле Power Fx, добавьте System. перед именем переменной. Например, чтобы включить системную переменную User.DisplayName в формулу, ссылайтесь на нее как System.User.DisplayName.

Name	Type	Definition
Activity.Attachments	table	Вложенные файлы, предоставляемые пользователем.
Activity.Channel	choice	ИД канала текущего разговора.
Activity.ChannelData	any	Объект, содержащий содержимое, относящееся к каналу.
Activity.ChannelId	струна	ИД канала текущего разговора, в виде строки.
Activity.From.Id	струна	Уникальный ИД конкретного канала отправителя.
Activity.From.Name	струна	Понятное имя отправителя для конкретного канала.
Activity.Name	струна	Название мероприятия.
Activity.Recipient.Id	струна	Свойство типа входящего действия.
Деятельность.Получатель.Имя	струна	Представляет отображаемое имя для агента внутри канала. В контексте канала телефонии значением этой переменной является номер телефона, к которому привязан агент.
Activity.Text	струна	Последнее сообщение, отправленное пользователем.
Activity.Type	choice	Тип действия.
Activity.TypeId	струна	Тип действия, в виде строки.
Activity.Value	any	Открытое значение.
Bot.EnvironmentId	струна	Идентификатор среды агента.
Bot.Id	струна	Идентификатор агента.
Bot.Name	струна	Имя агента.
Bot.SchemaName	струна	Имя схемы агента.
Bot.TenantId	струна	Идентификатор арендатора агента.
ClientPluginActions	choice	Коллекция динамических действий подключаемого модуля клиента для рассмотрения для генеративной оркестрации.
Conversation.Id	струна	Уникальный ИД текущего разговора.
Conversation.В режиме тестирования	Логический	Логический флаг, указывающий, происходит ли разговор в тестовом холсте.
Conversation.LocalTimeZone	струна	Название часового пояса, которое будет использоваться пользователем в формате базы данных часовых поясов IANA.
Conversation.LocalTimeZoneOffset	datetime	Смещение времени относительно UTC для текущего местного часового пояса.
Error.Code	струна	Код ошибки для текущей ошибки. Сообщение об ошибке для текущей ошибки.
Error.Message	струна	Сообщение об ошибке для текущей ошибки. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Error.
FallbackCount	Номер	Эта переменная подсчитывает количество раз, когда тему не удалось сопоставить с пользовательским вводом. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Unknown Intent.
InactivityTimer.Continue	Логический	Логический флаг, указывающий, нужно ли продолжать отсчет таймера. Примечание. Эта переменная поддерживается только в том случае, если используется триггер Inactivity.
InactivityTimer.Count	Номер	Количество срабатываний таймера OnInactivity из-за бездействия пользователя по истечении настроенного времени. Примечание. Эта переменная поддерживается только в том случае, если используется триггер Inactivity. Подробнее: Триггер бездействия.
LastMessage.Id	струна	ИД предыдущего сообщения, отправленного пользователем.
LastMessage.Text	струна	Предыдущее сообщение, отправленное пользователем.
Recognizer.ExtractedEntities	choice	Представляет извлеченные сущности из инициирующего сообщения. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent.
Recognizer.IntentOptions	choice	Представляет варианты намерений, когда распознаватель возвращает неоднозначные результаты. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent.
Recognizer.SelectedIntent	choice	Представляет намерение, выбранное из распознавателя. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent.
Recognizer.TriggeringMessage.Id	струна	Идентификатор пользовательского сообщения, инициировавшего текущую тему.
Recognizer.TriggeringMessage.Text	струна	Пользовательское сообщение, инициировавшее текущую тему.
Recognizer.MultipleTopicsMatchedReason	струна	Используется для определения того, почему было сопоставлено несколько тем. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent.
SignInReason	choice	Используется для определения необходимого варианта входа при запуске темы. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Sign In.
Пользователь.Язык	choice	Эта переменная используется для установки языкового стандарта пользователя для каждого разговора.

Переменные для голосовых агентов

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

Name	Type	Definition
Activity.InputDTMFKeys	струна	Необработанное значение DTMF-кнопки из телефонии.
Activity.SpeechRecognition.Confidence	Номер	Степень уверенности для всего результата гипотезы автоматического распознавания речи — от 0 до 1.
Activity.SpeechRecognition.MinimallyFormattedText	струна	Слегка отформатированный текст результата гипотезы автоматического распознавания речи. Например: "Пятьсот долларов". Числа записываются словами, но сохраняется базовая пунктуация и заглавные буквы.
Activity.UserInputType	choice	Тип последнего ввода пользователя агента. Значение может быть тест, речь или DTMF.
Conversation.OnlyAllowDTMF	Логический	Логический флаг, указывающий, следует ли перевести IVR в режим "только DTMF" во время выполнения.
Conversation.SipUuiHeaderValue	струна	Строка заголовка UUI, используемая для передачи контекста в IVR при начале вызова.

Переменные для интегрированной аутентификации (по умолчанию)

Следующие переменные доступны для агентов, настроенных для аутентификации с помощью Microsoft. Эта конфигурация использует аутентификацию с помощью Microsoft Entra ID и используется по умолчанию для новых агентов. Подробнее: Переменные аутентификации.

Name	Type	Definition
User.DisplayName	струна	Отображаемое имя пользователя, который в данный момент общается с агент.
User.Email	струна	Адрес электронной почты пользователя, который в данный момент общается с агент.
Пользователь.FirstName	струна	Имя пользователя, который в данный момент общается с агент.
User.Id	струна	Уникальный идентификатор пользователя, который в данный момент общается с агент.
User.IsLoggedIn	Логический	Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент.
Пользователь.Фамилия	струна	Имя семейства пользователя, который в данный момент общается с агентом.
User.PrincipalName	струна	Имя участника-пользователя, который в данный момент общается с агентом.

Переменные для ручной аутентификации с помощью универсального протокола OAuth 2

Следующие переменные доступны агентам, настроенным на использование универсального провайдера OAuth 2.

Name	Type	Definition
User.AccessToken	струна	Маркер доступа для пользователя, прошедшего проверку подлинности с помощью агент.
User.DisplayName	струна	Отображаемое имя пользователя, который в данный момент общается с агент.
User.Id	струна	Уникальный идентификатор пользователя, который в данный момент общается с агент.
User.IsLoggedIn	Логический	Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент.

Переменные для ручной аутентификации через Microsoft Entra ID

Следующие переменные доступны для агентов, настроенных для использования Microsoft Entra ID (бывший Azure Active Directory).

Name	Type	Definition
User.AccessToken	струна	Маркер доступа для пользователя, прошедшего проверку подлинности с помощью агент.
User.DisplayName	струна	Отображаемое имя пользователя, который в данный момент общается с агент.
User.Email	струна	Адрес электронной почты пользователя, который в данный момент общается с агент.
Пользователь.FirstName	струна	Имя пользователя, который в данный момент общается с агент.
User.Id	струна	Уникальный идентификатор пользователя, который в данный момент общается с агент.
User.IsLoggedIn	Логический	Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент.
Пользователь.Фамилия	струна	Имя семейства пользователя, который в данный момент общается с агентом.
User.PrincipalName	струна	Имя субъекта пользователя, который в данный момент общается с агентом.