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

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

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

Переменные также могут быть переданы в другие темы и потоки Power Automate и возвращены из них.

Создание переменной

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

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

Совет

Переименуйте узлы, чтобы их было легче идентифицировать. Выберите поле имени узла, чтобы обновить имя напрямую, или выберите значок Дополнительно (…) узла и выберите Переименовать из меню. Можно также переименовывать узлы в редакторе кода.

Невозможно переименовать узлы Триггер и Перейти на шаг.

Имена узлов могут иметь длину до 500 символов.

Классическая версия

На холсте разработки бота добавьте узел вопроса. В узле автоматически создается переменная.

1. Перейдите на страницу тем своего бота и откройте тему, в которую вы хотите добавить переменную.

2. Выберите Добавить узел (+), затем выберите Задать вопрос.

   

   Переменная, содержащая ответ пользователя, создается автоматически.

   

Выбор сущности для использования

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

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

Классическая версия

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

Изменение имени переменной

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

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

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

2. В поле Имя переменной введите новое имя для переменной.

Классическая версия

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

Задание переменной

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

1. Выберите Добавить узел (+), чтобы добавить узел, затем выберите Управление переменными>Задать значение переменной.

2. Выберите поле под Задать переменную, затем выберите Создать новую переменную.

   

   Новая переменная создана. Ее тип неизвестен, пока вы не присвоите ей значение.

   

3. Для До значения назначьте значение, используя один из следующих вариантов:

   • Введите литеральное значение.
   • Выберите существующую переменную того же типа. Это действие задает вашей переменной такое же значение, что и у выбранной переменной.
   • Используйте формулу Power Fx. Формулы Power Fx полезны для более сложных типов, где нельзя использовать литеральные значения, например для типов "Таблица" и "Запись".

Заметка

Если при установке переменной строкового типа вы столкнетесь с несоответствием между параметрами Задать переменную и равной значению, появится сообщение об ошибке и кнопка Исправить несоответствие типов. Нажмите кнопку, чтобы Copilot Studio автоматически создал формулу Power Fx, устраняющую несоответствие.

Использование переменных в узлах действия

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

Использование литеральных значений для вводных данных переменных

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

Узел пытается интерпретировать литеральные значения в виде строки, числа или логического значения. Например, 123 интерпретируется как число. Если вы хотели, чтобы это интерпретировалось как строковое значение, вы можете заключить это значение в двойные кавычки, например так: "123".

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

Использование переменных среды для секретов Azure Key Vault

Переменная среды может ссылаться на секрет в хранилище ключей Key Vault. Секретные переменные среды — это частный случай переменных среды с уникальными особенностями.

Чтобы создать переменную среды, содержащую секрет, на портале Power Apps вы должны настроить его Key Vault.

Чтобы дать разрешение Copilot Studio на чтение этого хранилища ключей Key Vault, необходимо выполнить следующие действия:

1. Назначьте роль Key Vault Secrets User для приложения Microsoft Virtual Agents Service.

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

3. Чтобы разрешить использование этого хранилища ключей Key Vault только определенным агентам из среды, создайте тег AllowedAgents и поместите идентификатор агента в формате {envId}/{schemaName}. В случае нескольких значений разделяйте их запятыми.

Если вы достигли максимального количества символов, но вам все еще нужно добавить больше агентов, добавьте еще один тег с описательным, но уникальным именем (например: AllowedAgents2).

Значение секрета кэшируется в среде выполнения диалога в течение пяти минут. Неудачные чтения кэшируются на 30 секунд.

Предупреждение

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

Панель "Переменные"

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

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

Чтобы открыть панель Переменные, в строке меню темы, выберите Переменные.

Классическая версия

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

1. В строке меню темы выберите Переменные.

   

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

   

Панель свойств переменной

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

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

Передача переменных между темами

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

Получение значений из других тем

Когда тема определяет переменную (например, с помощью узла Вопрос), агент задает вопрос пользователю для заполнения значения переменной. Если значение уже получено агентом в предыдущей теме, нет причин снова задавать вопрос. Для этих случаев эту переменную можно задать как Получение значений из других тем. Когда другая тема перенаправляет на эту тему, она может передать значение переменной или литеральное значение в эту переменную и пропустить этот вопрос. Это приводит к беспроблемному общению пользователя с агентом.

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

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

Вот поток темы Разговор с клиентом:

Как показано на тестовой панели, если эта тема активируется первой, она спрашивает пользователя: «Как мне вас называть?». Она сохраняет значение в строковой переменной customerName. Переменная customerName также задана для получения значения из других тем. Тема завершается сообщением: «Я надеюсь, что у вас замечательный день, customerName!»

Вот поток темы Приветствие:

Как показано на тестовой панели, если эта тема активируется первой, она спрашивает пользователя: «Как вас зовут?». Она сохраняет значение в строковой переменной customerName. В теме отправляется сообщение: «Рад познакомиться, customerName!» Затем выполняется перенаправление на тему Разговор с клиентом, которая отправляет сообщение: "Я надеюсь, что у вас замечательный день, customerName! Обратите внимание, однако, что в теме Разговор с клиентом имя пользователя повторно не запрашивается. Вместо этого используется значение переменной customerName, переданное из темы Приветствие.

Наконец, вот еще раз этот второй разговор, на этот раз с точки зрения темы Разговор с клиентом:

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

Настройка темы назначения

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

1. Создайте новую тему и назовите ее "Поговорите с клиентом".

2. Добавьте триггерные фразы, такие как «поговори со мной», «пообщайся со мной», «поболтай со мной».

3. Добавьте узел Вопрос и введите «Как мне вас называть?» для сообщения.

4. В разделе Идентификация выберите предварительно созданную сущность Имя человека.

5. Выберите имя переменной. Откроется панель Свойства переменной.

6. Замените имя по умолчанию на "customerName", затем выберите Получение значений из других тем.

   

7. Добавьте узел Сообщение.

8. В поле сообщения введите "Надеюсь, у вас замечательный день, ".

9. Выберите значок Вставить переменную ({x}), затем выберите customerName.

10. Выберите пробел после переменной и введите "!".

11. Сохраните тему.

Настройка исходной темы

Исходная тема — это тема, выполняющая перенаправление, которая предоставляет значение и передает его целевому разделу. В нашем примере это Приветствие.

1. Перейдите в тему Приветствие и удалите узлы по умолчанию, кроме узла Триггер.

2. Добавьте узел Вопрос и введите «Как вас зовут?» для сообщения.

3. В разделе Идентификация выберите предварительно созданную сущность Имя человека.

4. Замените имя по умолчанию на "customerNameFromGreeting".

5. Добавьте узел Сообщение.

6. В окне сообщения введите «Рад познакомиться, ».

7. Выберите значок Вставить переменную ({x}), затем выберите customerNameFromGreeting.

8. Выберите пробел после переменной и введите "!".

9. Добавьте узел Перенаправление и выберите целевую тему Разговор с клиентом.

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

    

11. Выберите значок >, затем выберите переменную, значение которой вы хотите передать, customerNameFromGreeting в этом примере.

    Узел Перенаправление должен выглядеть следующим образом:

    

12. Сохраните тему.

Классическая версия

Чтобы получать значения из других тем, установите свойство переменной:

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

2. В области Свойства переменных в Тема (ограниченный объем) выберите Получение значений из других тем.

   

   Заметка

   Переменные типа "Дата и время", "Длительность" или "Множественный выбор", а также переменные, основанные на настраиваемой сущности, нельзя передавать из одной темы в другую.

3. Сохраните тему.

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

5. Выберите + Добавление входных данных для темы назначения.

   

6. Выберите переменную в перенаправленной теме, в которую вы хотите передать переменную.

   

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

   

   Переменная отображается в перенаправленном узле.

   

Возврат значений к исходным темам

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

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

Давайте продолжим пример из предыдущего раздела. Мы задаем новый вопрос в теме Разговор с клиентом, затем возвращаем ответ в тему Приветствие.

Настройте исходную тему для возвращаемой переменной

Когда вы возвращаете переменную в тему, исходная тема — это тема, которая предоставляет значение для передачи обратно в исходную тему. В этом примере исходной темой является Разговор с клиентом.

1. Перейдите в исходную тему.

2. Добавьте узел Вопрос и введите «В каком городе Вы живете?» для сообщения.

3. В разделе Идентификация выберите предварительно созданную сущность Город.

4. Выберите эту переменную, чтобы открыть панель Свойства переменной. Назовите ее "customerCity" и выберите Возврат значений в исходные темы.

   

5. Добавьте узел Сообщение.

6. Выберите значок Вставить переменную ({x}), затем выберите customerCity.

7. После переменной в окне сообщения введите «В должно быть красиво в это время года!».

8. Сохраните тему.

Настройте тему назначения для возвращенной переменной

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

1. Перейдите в тему назначения.

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

   

3. Сохраните тему.

Классическая версия

Чтобы вернуть переменную в исходную тему, установите свойство переменной:

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

2. В области Свойства переменных в Тема (ограниченный объем) выберите Возврат значений к исходным темам.

   

   Заметка

   Переменные типа "Дата и время", "Длительность" или "Множественный выбор", а также переменные, основанные на настраиваемой сущности, нельзя передавать из одной темы в другую.

3. Сохраните тему.

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

   Переменная, возвращаемая в тему, отображается в перенаправленной теме. Используйте возвращенную переменную в вашей теме.

   

Узел «Анализировать значение»

Узел Анализировать значение позволяет преобразовать значение одного типа в значение другого типа. При добавлении узла в тему выберите значок Добавить узел , наведите указатель мыши на Управление переменными и выберите Анализировать значение.

Ключевые сценарии, в которых используется узел Анализировать значение, предполагают преобразование необработанных данных JSON или нетипизированных переменных (значение или структура которых неизвестны до времени выполнения, например ChannelData) в конкретные типы.

Процесс начинается, когда вызывается поток, который, в свою очередь, вызывает API. API затем возвращает результат. Как правило, вам нужно проанализировать этот ответ и вернуть одну или несколько примитивных переменных. С помощью узла Анализировать значение вы можете отправить весь полученный от API результат в виде строки. Например:

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

При использовании этого нового узла строковая переменная, которая у вас есть сейчас, может быть преобразована в переменную «Запись» с полной поддержкой intellisense в Power Fx. Пример с использованием демонстрационных данных поможет проиллюстрировать этот процесс.

Пример использования узла «Анализировать значение»

1. Добавьте узел Анализировать значение и выберите переменную, которую хотите проанализировать.

   

2. Выберите тип данных. В данном случае выберите Из демонстрационных данных.

   

3. Выберите Получить схему из примера JSON и введите нужный пример JSON в открывшемся редакторе.

   

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

   

   Обратите внимание, что выходная переменная теперь имеет правильный тип — Запись.

   

Помимо синтаксического анализа строк JSON, ключевым использованием узла Анализировать значение является синтаксический анализ UntypedObjects во время выполнения. Наиболее распространенный случай использования — когда вы получаете событие и вам нужно проанализировать значение события. Кроме того, может потребоваться проанализировать свойство System.Activity.ChannelData, которое изменяется во время выполнения в зависимости от канала.

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

Связанный контент

• Использование переменных для переноса контента между темами
• Настройка внешнего вида агента