Обзор переменных
Переменные могут существовать на четырех уровнях или областях действия:
- Переменные темы могут использоваться только в темах, в которых они были созданы. Это область действия по умолчанию для создаваемых вами переменных.
- Глобальные переменные могут использоваться во всех темах. Вы можете изменить область действия переменной темы, чтобы сделать ее глобальной.
- Системные переменные создаются автоматически вашим агентом. Они предоставляют больше контекстной информации о разговоре или пользователе. Они доступны во всех темах.
- Переменные среды создаются в Power Platform и доступны только для чтения в Copilot Studio. Они хранят ключи и значения параметров, которые затем служат входными данными для различных других объектов приложения, включая Copilot Studio. Отделение параметров от объектов-потребителей позволяет изменять значения в той же среде или при переносе решений в другие среды. Альтернативный вариант — оставить жестко запрограммированные значения параметров в компонентах, которые их используют.
Типы переменных
Переменная связана с базовым типом. Тип определяет значения, которые может содержать переменная, и операторы, которые можно использовать при построении логического выражения с ней.
| Type | Описание: |
|---|---|
| String | Последовательность символов, используемая для представления текста |
| Логический | Логическое значение, которое может быть только true или false |
| Число | Любое вещественное число |
| Таблицу | Список значений, но все значения должны быть одного типа |
| Запись | Коллекция пар имя-значение, где значения могут быть любого типа |
| Дата/время | Дата, время, день недели или месяц относительно момента времени |
| Выбранный вариант | Список строковых значений с соответствующими синонимами |
| Чистого листа | Заполнитель для «нет значения» или «неизвестное значение»; дополнительную информацию см. в разделе Пустые значения в Power Fx |
Тип переменной устанавливается при первом присвоении ей значения. После этого тип этой переменной фиксируется, и ей не могут быть присвоены значения любого другого типа. Например, переменной с заданным начальным значением 1 присваивается тип Число. Попытка присвоить ей строковое значение "apples" приводит к ошибке.
При тестировании агента переменная может временно отображаться как тип неизвестно. Переменной неизвестный еще не присвоено значение.
Порядок переменных определяется сверху вниз на холсте разработки. Узлы в верхней части холста разработки рассматриваются перед узлами в нижней.
При создании ветвей с узлами Условие ветви упорядочиваются слева направо. Узлы в крайней левой ветви рассматриваются перед узлами в крайней правой ветви.
Сущности
Copilot Studio использует сущности для определения определенного типа информации из ответов пользователя. Идентифицированная информация сохраняется в переменной того типа, который подходит для этой информации. В следующей таблице перечислены базовые типы переменных, связанные с предварительно созданными сущностями.
| Объект | Тип базовой переменной |
|---|---|
| Параметры с несколькими вариантами выбора | Выбранный вариант |
| Весь ответ пользователя | String |
| Возраст | Число |
| Логический | Логический |
| City | String |
| Color | String |
| Континент | String |
| Страна или регион | String |
| Дата и время | Дата/время |
| Электронное письмо | String |
| Мероприятие | String |
| Целое | Целое |
| Язык | String |
| Money | Число |
| Число | Число |
| Порядковое число | Число |
| Организация | String |
| Процент | Число |
| Имя человека | String |
| Номер телефона. | String |
| Точка интереса | String |
| Скорость | Число |
| State | String |
| Улица, дом | String |
| Температура | Число |
| URL | String |
| Толщина | Число |
| Почтовый индекс | String |
| Настраиваемый объект | Выбранный вариант |
Переменные среды
Переменные среды — это концепция Power Platform. Переменные среды позволяют использовать базовый сценарий управления жизненным циклом приложения (ALM) для перемещения приложения между средами Power Platform. В этом сценарии приложение остается точно таким же, за исключением нескольких ключевых внешних ссылок, которые различаются в исходной среде и целевой среде.
Используйте переменные среды таким же образом, как переменные темы, глобальные переменные и системные переменные. Одно из заметных отличий заключается в том, что переменные среды доступны только для чтения в Copilot Studio. Авторы агентов не могут изменять переменные среды в Copilot Studio. Однако администраторы могут изменять значения переменных среды в Power Apps. В Copilot Studio вы можете использовать панель переменных для просмотра информации о переменной среды. На панели Переменные также есть ссылка на собственный интерфейс разработки.
Опубликованная версия агента, использующая переменные среды, имеет значения, которые были установлены для этих переменных при публикации агента. Всякий раз, когда администратор обновляет переменные среды, необходимо повторно опубликовать все агенты, использующие эти переменные, чтобы изменения вступили в силу во время выполнения. Однако есть одно исключение: вам не нужно повторно публиковать агенты при изменении значения переменной среды типа секрет. В отличие от других переменных среды, секретные переменные извлекаются во время выполнения.
Типы переменных среды в Copilot Studio сопоставляются с типами данных Power Apps следующим образом:
| Тип в Copilot Studio | Тип в Power Apps |
|---|---|
| Десятичное число | Число |
| JSON | Тип определяется по значению. Если не JSON => Не указано (ошибка проверки) |
| Текст | String |
| Да/нет | Логический |
| Источник данных | String |
| Секрет | String |
Заметка
Ошибки переменных среды видны в тестовом чате и при публикации. Однако эти ошибки не отображаются в списке Тема, поскольку они не являются переменными темы.
Системные переменные
Каждый агент поставляется со встроенными системными переменными, которые предоставляют дополнительную информацию о разговоре.
Заметка
Дополнительные сведения о голосовых переменных агент см. в разделе Использование голосовых переменных.
В списке показаны не все системные переменные. Вы должны получить доступ к этим скрытым системным переменным с помощью формулы Power Fx.
Чтобы использовать системные переменные в формуле Power Fx, вы должны добавить System. перед именем переменной. Например, чтобы включить системную переменную User.DisplayName в формулу, ссылайтесь на нее как System.User.DisplayName.
| Полное имя | Type | Определение |
|---|---|---|
| Activity.Attachments | таблица | Файловые вложения, предоставленные пользователем |
| Activity.Channel | вариант | ИД канала текущего разговора |
| Activity.ChannelData | любое | Объект, содержащий содержимое, относящееся к каналу |
| 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 | любое | Открытое значение |
| Bot.EnvironmentId | string | Идентификатор среды агента |
| Bot.Id | string | Идентификатор агента |
| Bot.Name | string | Имя вашего агента |
| Bot.SchemaName | string | Имя схемы агента |
| Bot.TenantId | string | Идентификатор клиента агента |
| ClientPluginActions | вариант | Коллекция динамических действий подключаемого модуля клиента для рассмотрения для генеративной оркестрации |
| Conversation.Id | string | Уникальный ИД текущей беседы |
| Conversation.InTestMode | Логический | Логический флаг, указывающий, происходит ли разговор в тестовом холсте |
| 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 | ИД предыдущего сообщения, отправленного пользователем |
| LastMessage.Text | string | Предыдущее сообщение, отправленное пользователем |
| Recognizer.ExtractedEntities | вариант | Представляет извлеченные сущности из инициирующего сообщения. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent. |
| Recognizer.IntentOptions | вариант | Представляет варианты намерений, когда распознаватель возвращает неоднозначные результаты. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent. |
| Recognizer.SelectedIntent | вариант | Представляет намерение, выбранное из распознавателя. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent. |
| Recognizer.TriggeringMessage.Id | string | Идентификатор пользовательского сообщения, инициировавшего текущую тему |
| Recognizer.TriggeringMessage.Text | string | Пользовательское сообщение, инициировавшее текущую тему |
| Recognizer.MultipleTopicsMatchedReason | string | Используется для определения того, почему было сопоставлено несколько тем. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Select Intent. |
| SignInReason | вариант | Используется для определения необходимого варианта входа при запуске темы. Примечание. Эта переменная поддерживается только в том случае, если используется триггер On Sign In. |
| User.Language | вариант | Эта переменная используется для установки языкового стандарта пользователя для каждого разговора. |
Переменные для интегрированной аутентификации (по умолчанию)
Следующие переменные доступны для агентов, настроенных для аутентификации с помощью Microsoft. Эта конфигурация использует проверку подлинности Microsoft Entra ID и используется по умолчанию для новых агентов.
Дополнительные сведения см. в разделе Переменные проверки подлинности.
| Полное имя | Type | Определение |
|---|---|---|
| User.DisplayName | string | Отображаемое имя пользователя, который в данный момент общается с агент. |
| User.Email | string | Адрес электронной почты пользователя, который в данный момент общается с агент. |
| User.FirstName | string | Имя пользователя, который в данный момент общается с агент. |
| User.Id | string | Уникальный идентификатор пользователя, который в данный момент общается с агент. |
| User.IsLoggedIn | Логический | Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент. |
| User.LastName | string | Имя семейства пользователя, который в данный момент общается с агентом. |
| User.PrincipalName | string | Имя участника-пользователя, который в данный момент общается с агентом. |
Переменные для проверки подлинности вручную с помощью Generic OAuth 2
Следующие переменные доступны для агентов, настроенных для использования поставщика услуг Generic OAuth 2.
| Полное имя | Type | Определение |
|---|---|---|
| User.AccessToken | string | Маркер доступа для пользователя, прошедшего проверку подлинности с помощью агент. |
| User.DisplayName | string | Отображаемое имя пользователя, который в данный момент общается с агент. |
| User.Id | string | Уникальный идентификатор пользователя, который в данный момент общается с агент. |
| User.IsLoggedIn | Логический | Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент. |
Переменные для ручной аутентификации с помощью Microsoft Entra ID
Следующие переменные доступны для агентов, настроенных для использования поставщиков услуг Microsoft Entra ID (ранее Azure Active Directory).
| Полное имя | Type | Определение |
|---|---|---|
| User.AccessToken | string | Маркер доступа для пользователя, прошедшего проверку подлинности с помощью агент. |
| User.DisplayName | string | Отображаемое имя пользователя, который в данный момент общается с агент. |
| User.Email | string | Адрес электронной почты пользователя, который в данный момент общается с агент. |
| User.FirstName | string | Имя пользователя, который в данный момент общается с агент. |
| User.Id | string | Уникальный идентификатор пользователя, который в данный момент общается с агент. |
| User.IsLoggedIn | Логический | Логический флаг, который определяет, аутентифицирован ли пользователь, который в данный момент общается с агент. |
| User.LastName | string | Имя семейства пользователя, который в данный момент общается с агентом. |
| User.PrincipalName | string | Имя субъекта пользователя, который в данный момент общается с агентом. |
Переменные для голосовых агентов
Следующие переменные доступны только для агентов с поддержкой голосовой связи.
Заметка
Дополнительные сведения о голосовых переменных агент см. в разделе Использование голосовых переменных.
| Полное имя | 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 при начале вызова. |