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

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

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

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

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

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

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

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

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

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

Entities

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

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

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

Classic

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

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

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

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

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

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

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

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

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

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

Замечание

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

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

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

Замечание

Дополнительные сведения о голосовых переменных агент см. в разделе Использование голосовых переменных.

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

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

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

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

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

Дополнительные сведения см. в разделе Переменные проверки подлинности.

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

Переменные для проверки подлинности вручную с помощью Generic OAuth 2

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

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

Переменные для ручной аутентификации с помощью Microsoft Entra ID

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

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

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

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

Замечание

Дополнительные сведения о голосовых переменных агент см. в разделе Использование голосовых переменных.

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