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

Note

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

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

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

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

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

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

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

Tip

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

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

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

План команд

1. Перейдите на страницу Темы для вашего классического чат-бота и откройте нужную тему.

2. Выберите значок Добавить узел под тем узлом, после которого вы хотите добавить узел с вопросом. Затем выберите Задать вопрос. Copilot Studio автоматически создает переменную для хранения ответа пользователя.

   

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

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

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

План команд

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

Переименование переменной

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

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

1. Выберите переменную. Появится панель Свойства переменной.

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

План команд

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

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

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

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

2. Выберите Управление переменными>Задать значение переменной. На холсте появляется узел Задать значение переменной.

3. Выберите поле в разделе Задать переменную. Откроется панель Выбор переменной.

   • Если переменная, которую вы хотите задать, уже существует, выберите ее.

   • В противном случае выберите Создать новое. Это действие создает новую переменную. Ее тип неизвестен, пока вы не присвоите ей значение.

     

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

   • Введите литеральное значение.

   • Выберите существующую переменную того же типа.

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

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

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

Подробнее см. в:

• Вызов потока агента из агента
• Используйте потоки с агентом

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

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

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

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

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

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

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

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

1. Назначьте роль Пользователь секретов Key Vault приложению Microsoft Copilot Studio Service.

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

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

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

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

Warning

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

Панель «Переменные»

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

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

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

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

План команд

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

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. На панели Свойства переменной в разделе В теме (ограниченная область) выберите Получение значений из других тем.

   

   Note

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

3. Сохраните раздел.

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

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

   

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

   

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

   

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

   

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

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

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

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

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

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

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

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

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

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

   

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

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

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

8. Сохраните раздел.

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

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

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

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

   

3. Сохраните раздел.

План команд

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

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

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

   

   Note

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

3. Сохраните раздел.

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

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

   

Анализ значений

Узел Анализ значения преобразует значение из одного типа данных в другой. Распространенный пример использования узла Анализ значения — преобразование необработанного JSON. Например, агент вызывает поток, который вызывает API. API возвращает результат. Вам нужен способ разобрать этот результат и вернуть одну или несколько примитивных переменных. С помощью узла Анализ значения вы можете передать весь результат API как строку, например:

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

Узел Анализ значения преобразует строковую переменную в переменную типа Запись. Редактор Power Fx предоставляет функцию автодополнения кода IntelliSense и подсказки для этого типа.

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

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

Чтобы добавить узел Анализ значения в тему:

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

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

   

3. Для типа данных выберите Из примера данных.

   

4. Выберите Извлечь схему из примера JSON, в открывшемся редакторе введите требуемый образец JSON и выберите Подтвердить.

   

5. Выберите переменную для хранения разобранного значения. Обычно создается новая переменная.

   

   Выходная переменная теперь имеет ожидаемый тип: запись.

   

Связанные материалы

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