Variablenübersicht
Variablen können auf vier Ebenen bzw. in vier Bereichen existieren:
- Thema-Variablen können nur in den Themen verwendet werden, in denen sie erstellt wurden. Dieser Bereich ist der Standardbereich für Variablen, die Sie erstellen.
- Globale Variablen können in allen Themen verwendet werden. Sie können den Bereich einer Thema-Variable ändern, um sie zu einer globalen Variablen zu machen.
- Systemvariablen werden automatisch mit Ihrem Agent erstellt. Sie bieten mehr kontextbezogene Informationen über die Unterhaltung oder den Benutzer. Sie sind in allen Themen verfügbar.
- Umgebungsvariablen werden in Power Platform erstellt und sind in Copilot Studio schreibgeschützt. Sie speichern die Parameterschlüssel und -werte, die dann als Eingabe für verschiedene andere Anwendungsobjekte dienen darunter für Copilot Studio. Durch Trennen der Parameter von den verwendenden Objekten können Sie die Werte in derselben Umgebung oder bei der Migration von Lösungen in andere Umgebungen ändern. Die Alternative besteht darin, fest codierte Parameterwerte in den Komponenten zu belassen, die sie verwenden.
Variablentypen
Eine Variable ist einem Basistyp zugeordnet. Der Typ bestimmt, welche Werte die Variable enthalten kann und welche Operatoren Sie verwenden können, wenn Sie einen logischen Ausdruck mit ihr erstellen.
| Type | Beschreibung |
|---|---|
| Zeichenfolge | Eine Folge von Zeichen zur Darstellung von Text |
| Boolesch | Ein logischer Wert, der nur true oder false sein kann |
| Number | Eine beliebige reelle Zahl |
| Table | Eine Liste mit Werten, aber alle Werte müssen vom gleichen Typ sein |
| Datensatz | Eine Sammlung von Name-Wert-Paaren, bei denen Werte jeden Typs haben können |
| DateTime | Ein Datum, eine Uhrzeit, ein Wochentag oder ein Monat relativ zu einem Zeitpunkt |
| Auswahl | Eine Liste von Zeichenfolgenwerten mit zugehörigen Synonymen |
| Leer | Ein Platzhalter für „kein Wert“ oder „unbekannter Wert“. Weitere Informationen finden Sie unter Leerstellen in Power Fx |
Der Typ einer Variablen wird ihr beim ersten Zuweisen eines Werts festgelegt. Danach wird der Typ für diese Variable festgelegt und ihr können keine Werte eines anderen Typs zugewiesen werden. So wird beispielsweise einer Variablen mit dem Anfangswert 1 der Typ Zahl zugewiesen. Der Versuch, ihn einem String-Wert von "apples" zuzuweisen, führt zu einem Fehler.
Wenn Sie einen Agenten testen, wird möglicherweise vorübergehend eine Variable als Typ Unbekannt angezeigt. Einer Unbekannt Variable wurde noch kein Wert zugewiesen.
Die Reihenfolge der Variablen wird von oben nach unten im Erstellungsbereich festgelegt. Die Knoten am oberen Rand des Erstellungsbereichs werden vor den Knoten am unteren Rand betrachtet.
Wenn Sie Verzweigungen mit Bedingungsknoten erstellen, werden die Verzweigungen von links nach rechts geordnet. Knoten in der Verzweigung ganz links werden vor Knoten in der Verzweigung ganz rechts betrachtet.
Entitäten
Copilot Studio verwendet Entitäten, um eine bestimmte Art von Informationen aus den Antworten eines Benutzers zu identifizieren. Die identifizierten Informationen werden in einer Variablen des Typs gespeichert, der den Informationen entspricht. In der folgenden Tabelle ist der Basistyp der Variablen aufgeführt, die vordefinierten Entitäten zugeordnet sind.
| Entity | Variablen-Basistyp |
|---|---|
| Multiple-Choice-Optionen | Auswahl |
| Die gesamte Antwort des Benutzers | Zeichenfolge |
| Alter | Number |
| Boolesch | Boolesch |
| City | Zeichenfolge |
| Color | Zeichenfolge |
| Kontinent | Zeichenfolge |
| Land oder Region | Zeichenfolge |
| Datum und Uhrzeit | DateTime |
| E‑Mail | Zeichenfolge |
| Event | Zeichenfolge |
| Ganzzahl | Ganzzahl |
| Language | Zeichenfolge |
| Money | Number |
| Number | Number |
| Ordinal | Number |
| Organization | Zeichenfolge |
| Prozentsatz | Number |
| Name der Person | Zeichenfolge |
| Telefon | Zeichenfolge |
| Point of Interest | Zeichenfolge |
| Geschwindigkeit | Number |
| Bundesstaat | Zeichenfolge |
| Straße | Zeichenfolge |
| Temperatur | Number |
| URL | String |
| Schriftstärke | Number |
| Postleitzahl | String |
| Benutzerdefinierte Entität | Auswahl |
Umgebungsvariablen
Umgebungsvariablen sind ein Power Platform-Konzept. Umgebungsvariablen ermöglichen das grundlegende Szenario der Lebenszyklusverwaltung von Anwendungen (Application Lifecycle Management, ALM) zum Verschieben einer Anwendung zwischen Power Platform-Umgebungen. In diesem Szenario bleibt die Anwendung bis auf einige wichtige externe Referenzen, die sich zwischen der Quellumgebung und der Zielumgebung unterscheiden, absolut unverändert.
Verwenden Sie Umgebungsvariablen auf die gleiche Weise wie Themen, globale und Systemvariablen. Ein bemerkenswerter Unterschied besteht darin, dass Umgebungsvariablen schreibgeschützt sind in Copilot Studio. Agenten-Entwickler können Umgebungsvariablen nicht in Copilot Studio ändern. Administratoren können jedoch den Wert von Umgebungsvariablen in Power Apps ändern. In Copilot Studio können Sie den Variablen-Bereich verwenden, um Informationen zu einer Umgebungsvariablen anzuzeigen. Das Bedienfeld Variablen enthält auch einen Link zur nativen Autorenerfahrung.
Die veröffentlichte Version eines Agenten, der Umgebungsvariablen verwendet, weist die Werte auf, die bei der Veröffentlichung des Agenten für diese Variablen festgelegt wurden. Jedes Mal, wenn ein Administrator Umgebungsvariablen aktualisiert, müssen Sie alle Agenten, die diese Variablen verwenden, erneut veröffentlichen, damit die Änderungen zur Laufzeit wirksam werden. Es gibt jedoch eine Ausnahme: Sie müssen Ihre Agenten nicht erneut veröffentlichen, wenn sich der Wert einer Umgebungsvariablen vom Typ Geheimnis ändert. Im Gegensatz zu anderen Umgebungsvariablen werden Geheimnis-Variablen zur Laufzeit abgerufen.
Umgebungsvariablentypen in Copilot Studio werden den folgenden Power Apps-Datentypen zugeordnet:
| Typ in Copilot Studio | Typ in Power Apps |
|---|---|
| Dezimalzahl | Number |
| JSON | Ermitteln Sie den Typ anhand des Wertes. Wenn nicht JSON => Nicht spezifiziert (Validierungsfehler) |
| Text | String |
| Ja/Nein | Boolesch |
| Data source | String |
| Secret | String |
Anmerkung
Umgebungsvariablenfehler sind im Test-Chat und beim Veröffentlichen sichtbar. Diese Fehler werden jedoch in der Liste Thema nicht angezeigt, da es sich nicht um Themenvariablen handelt.
Systemvariablen
Jeder Agent verfügt über integrierte Systemvariablen, die zusätzliche Informationen zu einer Unterhaltung liefern.
Anmerkung
Weitere Informationen zu sprachaktivierten Agentenvariablen finden Sie unter Sprachvariablen verwenden.
Nicht alle Systemvariablen werden in der Liste angezeigt. Auf diese versteckten Systemvariablen müssen Sie mit einer Power Fx Formel zugreifen.
Zum Verwenden von Systemvariablen in einer Power Fx-Formel müssen Sie System. vor dem Variablennamen hinzufügen. Um beispielsweise die Systemvariable User.DisplayName in eine Formel einzubinden, verweisen Sie als System.User.DisplayName darauf.
| Name des Dataflows | typ | Definition |
|---|---|---|
| Activity.Attachments | Tabelle | Die vom Benutzenden bereitgestellten Dateianhänge |
| Activity.Channel | Option | Die Kanal-ID der aktuellen Unterhaltung |
| Activity.ChannelData | Beliebig | Ein Objekt, das kanalspezifische Inhalte enthält |
| Activity.ChannelId | string | Die Kanal-ID des aktuellen Gesprächs als Zeichenfolge |
| Activity.From.Id | string | Die kanalspezifische eindeutige ID des Absenders |
| Activity.From.Name | string | Der kanalspezifische benutzerfreundliche Name des Absenders |
| Activity.Name | string | Der Name des Ereignisses |
| Activity.Recipient.Id | string | Die Typ-Eigenschaft der eingehenden Aktivität. |
| Activity.Recipient.Name | string | Stellt den Anzeigenamen für den Agenten innerhalb des Kanals dar. Im Kontext des Telefoniekanals ist der Wert dieser Variablen die Telefonnummer, an die der Agent angefügt ist. |
| Activity.Text | string | Die letzte vom Benutzer gesendete Nachricht |
| Activity.Type | Option | Typ der Aktivität |
| Activity.TypeId | string | Typ der Aktivität als Zeichenfolge |
| Activity.Value | Beliebig | Offener Wert |
| Bot.EnvironmentId | string | Die Umgebungs-ID des Agenten |
| Bot.Id | string | Die ID des Agenten |
| Bot.Name | string | Der Name Ihres Agenten |
| Bot.SchemaName | string | Der Schemaname des Agenten |
| Bot.TenantId | string | Die Mandanten-ID des Agenten |
| ClientPluginActions | Option | Sammlung dynamischer Client-Plug-In-Aktionen, die bei der generativen Orchestrierung zu berücksichtigen sind |
| Conversation.Id | string | Die eindeutige ID der aktuellen Unterhaltung |
| Conversation.InTestMode | Boolesch | Boolesches Kennzeichen, das angibt, ob die Unterhaltung im Test-Canvas stattfindet |
| Conversation.LocalTimeZone | string | Name der vom Benutzenden zu verwendenden Zeitzone im IANA-Zeitzonendatenbankformat |
| Conversation.LocalTimeZoneOffset | DateTime | Der Zeitunterschied zur UTC für die aktuelle lokale Zeitzone |
| Error.Code | string | Der Fehlercode des aktuellen Fehlers. Die Fehlermeldung, die für den aktuellen Fehler definiert wurde. |
| Error.Message | string | Die Fehlermeldung, die für den aktuellen Fehler definiert wurde. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Error lautet. |
| FallbackCount | Zahl | Diese Variable zählt, wie oft ein Thema nicht der Benutzereingabe zugeordnet werden konnte. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Unknown Intent lautet. |
| InactivityTimer.Continue | Boolesch | Boolesches Kennzeichen, das angibt, ob der Timer fortgesetzt werden muss. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger Inactivity lautet. |
| InactivityTimer.Count | Zahl | Häufigkeit, mit welcher der OnInactivity-Timer aufgrund von Benutzerinaktivität nach der konfigurierten Zeit ausgelöst wurde. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger Inactivity lautet. |
| LastMessage.Id | string | Die ID der vorherigen vom Benutzer gesendeten Nachricht |
| LastMessage.Text | string | Die vorherige vom Benutzer gesendete Nachricht |
| Recognizer.ExtractedEntities | Option | Stellt die extrahierten Entitäten aus der auslösenden Nachricht dar. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet. |
| Recognizer.IntentOptions | Option | Stellt die Absichtsoptionen dar, wenn das Erkennungsmodul mehrdeutige Ergebnisse zurückgibt. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet. |
| Recognizer.SelectedIntent | Option | Stellt die vom Erkennungsmodul ausgewählte Absicht dar. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet. |
| Recognizer.TriggeringMessage.ID | string | Die ID der Benutzernachricht, die das aktuelle Thema ausgelöst hat. |
| Recognizer.TriggeringMessage.Text | string | Die Benutzernachricht, die das aktuelle Thema ausgelöst hat |
| Recognizer.MultipleTopicsMatchedReason | string | Wird verwendet, um zu ermitteln, warum mehrere Themen übereinstimmen. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Select Intent lautet. |
| SignInReason | Option | Wird verwendet, um zu bestimmen, welche Anmeldeoption beim Auslösen des Themas erforderlich ist. Hinweis: Diese Variable wird nur unterstützt, wenn der Trigger On Sign In lautet. |
| User.Language | Option | Mit dieser Variable wird das Gebietsschema der Benutzersprache pro Unterhaltung festgelegt. |
Variablen für integrierte Authentifizierung (Standard)
Die folgenden Variablen sind für Agenten verfügbar, die für die Authentifizierung bei Microsoft konfiguriert sind. Diese Konfiguration verwendet Microsoft Entra ID-Authentifizierung und ist die Standardeinstellung für neue Agenten.
Weitere Informationen finden Sie unter Authentifizierungsvariablen.
| Name des Dataflows | typ | Definition |
|---|---|---|
| User.DisplayName | string | Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht. |
| Benutzer-E-Mail | string | Die E-Mail-Adresse des Benutzers, der gerade mit dem Agent kommuniziert. |
| User.FirstName | string | Der Vorname des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.Id | string | Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.IsLoggedIn | Boolesch | Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht. |
| User.LastName | string | Der Familienname des Benutzers, der gerade mit der Agent spricht. |
| User.PrincipalName | string | Der Benutzerprinzipalname des Benutzers, der derzeit mit der Agent kommuniziert. |
Variablen für die manuelle Authentifizierung mit Generic OAuth 2
Die folgenden Variablen sind für Agenten verfügbar, die für die Verwendung des Dienstanbieters generisch OAuth 2 konfiguriert sind.
| Name des Dataflows | typ | Definition |
|---|---|---|
| User.AccessToken | string | Der Zugriffstoken für den Benutzenden, der sich bei dem Agenten authentifiziert. |
| User.DisplayName | string | Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.Id | string | Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.IsLoggedIn | Boolesch | Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht. |
Variablen für die manuelle Authentifizierung mit Microsoft Entra ID
Die folgenden Variablen sind für Agenten verfügbar, die für die Verwendung der Microsoft Entra ID (früher Azure Active Directory) konfiguriert sind.
| Name des Dataflows | typ | Definition |
|---|---|---|
| User.AccessToken | string | Der Zugriffstoken für den Benutzenden, der sich bei dem Agenten authentifiziert. |
| User.DisplayName | string | Der Anzeigename des Benutzenden, der aktuell mit dem Agenten spricht. |
| Benutzer-E-Mail | string | Die E-Mail-Adresse des Benutzers, der gerade mit dem Agent kommuniziert. |
| User.FirstName | string | Der Vorname des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.Id | string | Die einzigartige ID des Benutzenden, der aktuell mit dem Agenten spricht. |
| User.IsLoggedIn | Boolesch | Boolesches Kennzeichen, das angibt, ob der Benutzer, der gerade mit dem Agent spricht, authentifiziert ist oder nicht. |
| User.LastName | string | Der Familienname des Benutzers, der gerade mit der Agent spricht. |
| User.PrincipalName | string | Der Prinzipalname des Benutzers, der gerade mit der Agent spricht. |
Variablen für sprachaktivierte Agenten
Die folgenden Variablen sind nur für sprachaktivierte Agenten verfügbar.
Anmerkung
Weitere Informationen zu sprachaktivierten Agentenvariablen finden Sie unter Sprachvariablen verwenden.
| Name des Dataflows | typ | Definition |
|---|---|---|
| Activity.InputDTMFKeys | string | Der rohe MFV-Tastenwert, der von der Telefonie empfangen wurde. |
| Activity.SpeechRecognition.Confidence | Zahl | Die Konfidenzbewertung für das gesamte Ergebnis der Azure Site Recovery-Hypothese: 0 bis 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Etwas formatierter Text des Ergebnisses der Hypothese von Azure Site Recovery Zum Beispiel: Fünfhundert Dollar. Wörter werden ausgeschrieben, aber die grundlegende Groß- und Kleinschreibung sowie Zeichensetzung werden berücksichtigt. |
| Activity.UserInputType | Option | Der Eingabetyp aus der letzten Eingabe des Benutzers. Der Wert kann entweder testen, Sprache und MFV sein. |
| Conversation.OnlyAllowDTMF | Boolesch | Boolesche Kennzeichen, das angibt, ob die ISA zur Laufzeit auf den Nur-MFV-Modus eingestellt werden soll. |
| Conversation.SipUuiHeaderValue | string | Die UUI-Headerzeichenfolge, die verwendet wird, um beim Beginn des Anrufs den Kontext an die ISA zu übergeben. |