変数の使用
変数を使用して顧客の応答を保存し、会話の後半でコンテンツを再利用することができます。
変数を使用して、顧客を動的に別の会話パスにルーティングする論理式を作成することもできます。 たとえば、顧客の名前を UserName
という変数に保存すると、会話が続く間、エージェント は顧客の名前で呼びかけることができます。
また、変数は他のトピックやPower Automateフローに渡したり、返したりすることができます。
変数は 4 つのレベル、またはスコープで存在できます:
- トピック 変数は、作成されたトピック内でのみ使用できます。 このスコープが、作成された変数の既定値です。
- グローバル変数 はすべてのトピックで使用できます。 トピック変数のスコープを変更し、グローバル変数にすることができます。
- システム変数 は、エージェント とともに自動的に作成されます。 それらは、会話またはユーザーについてより多くのコンテキスト情報を提供します。 すべてのトピックで使用可能です。
- 環境 変数 は Power Platform で作成され、 Copilot Studioで読み取り専用になります。 パラメーターのキーと値が格納され、Copilot Studio を含む他のさまざまなアプリケーション オブジェクトの入力として機能します。 消費オブジェクトからパラメーターを分離すると、同じ環境内で、または他の環境にソリューションを移行するときに値を変更できます。 代替方法は、ハードコーディングされたパラメーター値を、それらを使用するコンポーネント内に残すことです。
変数の型
変数は基本タイプと関連付けられます。 型は、変数が含むことのできる値や、論理式を構成する際に使用できる演算子を決定します。
タイプ | Description |
---|---|
String | テキストを表すために使用される一連の文字 |
ブール型 | true または false の論理値 |
回数 | 任意の実数 |
テーブル | 値のリスト。ただし、すべての値は同じ型である必要があります |
Record | 名前と値のペアのコレクション。値は任意の型 |
DateTime | ある時点に関する日付、時刻、曜日、または月 |
選択肢 | 関連する同義語を含む文字列値のリスト |
空白 | 「値がない」または「不明な値」のプレースホルダー。詳細については、Power Fx の空白を参照してください |
変数の型は、値が最初に割り当てられるときに設定されます。 その後、変数の型は固定され、他の型の値を割り当てることはできなくなります。 たとえば、開始値 1
の変数には 数値 型が割り当てられます。 これを String value of "apples"
に割り当てようとすると、エラーが発生します。
エージェント をテストしているときに、変数が一時的に型 不明 として表示される場合があります。 不明の変数はまだ値が割り当てられていない場合を指します。
変数の順序は、作成キャンバスの上から下に決定されます。 オーサリング キャンバスの上部にあるノードは、下部にあるノードよりも先に考慮されます。
条件ノードで分岐を作成するとき、ブランチは左から右に並べられます。 左端のブランチのノードは、右端のブランチのノードよりも先に考慮されます。
エンティティ
Copilot Studio は、エンティティ を使用して、ユーザーの応答から特定の種類の情報を識別します。 識別された情報は、情報に適した型の変数に保存されます。 次の表は、事前構築されたエンティティに関連付けられている変数の基本タイプを示しています。
Entity | 変数の基本型 |
---|---|
複数選択オプション | 選択肢 |
ユーザーの応答全体 | String |
年齢 | 回数 |
ブール型 | ブール型 |
都市 | String |
Color | String |
大陸 | String |
国または地域 | String |
日時 | DateTime |
メール | String |
イベント | String |
整数 | 整数 |
Language | String |
Money | 回数 |
回数 | 回数 |
Ordinal | 回数 |
Organization | String |
Percentage | 回数 |
個人名 | String |
電話番号 | String |
注目ポイント | String |
速度 | Number |
状態 | String |
番地 | String |
温度 | 回数 |
[URL] | String |
重さ | 回数 |
郵便番号 | String |
ユーザー定義エンティティ | 選択肢 |
変数を作成する
質問 ノードなど、出力として変数を選択するよう求めるノードは、適切な型の出力変数を自動で作成します。
チップ
名前を変更し、ノードを識別しやすくします。 ノードの名前フィールドを選択して名前を直接更新するか、ノードのその他 (…) アイコンを選択してメニューから名前の変更を選択します。 コード エディター でノードの名前を変更することもできます。
トリガー ノードと 手順に進む ノードの名前を変更することはできません。
ノード名の長さは 500 文字までです。
使用するエンティティを選択する
質問ノードは、デフォルトで複数選択オプション付きで作成されます。 別の事前構築済みエンティティまたはカスタム エンティティを使用するには、 [識別] ボックスをオンにして、エージェント がリッスンする情報の種類を選択します。
変数名を変更する
変数には、作成する時に自動的に名前が付けられます。 ベストプラクティスとしては、エージェント を管理する必要がある他のユーザーに目的が明確に伝わるように、変数に意味のある名前を付けることが挙げられます。
変数を選択し、変数プロパティ ペインで開きます。
変数名に、変数の新しい名前を入力します。
変数を設定する
通常、ユーザー入力を変数に保存するには、 Question ノードを使用します。 ただし、自分で値を設定したい場合もあります。 このような場合、変数値の設定ノードを使用します。
ノードの追加 (+) を選択してノードを追加し、変数管理>変数値の設定 を選択します。
変数の設定の下にあるボックスを選択し、新しい変数を作成するを選択します。
新しい変数が作成されました。 値を割り当てるまでその型は不明です。
対象値には、次のいずれかの方法で値を指定します:
- リテラル値を入力します。
- 同じ型の既存の変数を選択します。 このアクションにより、選択した変数と同じ値が設定されます。
- Power Fx 式を使用します。 Power Fx 式は、Table 型や Record 型などのリテラル値を使用できない、より複雑な型に有効です。
ヒント
文字列型変数を設定する際に、 変数の設定 と 値への設定の間に不一致が発生した場合、エラー メッセージと 型の不一致を修正 ボタンが表示されます。 選択 ボタンをクリックすると、不一致を解決する Copilot Studio 数式 Power Fx が自動的に生成 されます。
リテラル値の使用
変数値を選択する代わりに、任意の変数にリテラル値を入力することができます。
ノードはリテラル値を文字列、数値、またはブール値として解釈を試みます。 たとえば、123
は数値として解釈されます。 文字列の値として解釈する場合は、"123"
のように値を二重引用符で囲んでください。
いくつかのシナリオや、より複雑な型を使用する場合は、特定の型を設定するために Power Fx 式を使用します。
変数ペイン
変数ウィンドウでは、定義または使用されているノードに関係なく、トピックで使用可能なすべての変数を表示することができます。 変数ごとに、他のトピックから値を受け取るか、その値を他のトピックに返すか、またはその両方を行うかを選択できます。 変数を選択して、変数のプロパティ ペインでプロパティを編集することもできます。
変数ウィンドウを開くには、トピックのメニュー バーで、変数を選択します。
変数プロパティ ペイン
変数のプロパティ ウィンドウで、変数の名前を変更したり、変数が使用されている場所を確認したり、変数をグローバル変数に変換したりすることができます。 ただし、グローバル変数からトピック変数に戻すことはできません。 また、他のトピックから値を受け取るか、その値を他のトピックに渡すかを選択することもできます。
変数プロパティ ペインを開くには、変数ペインで変数を選択します。 任意のノードで変数を選択して、変数のプロパティ ウィンドウを開くこともできます。
環境変数
環境 変数は 概念です Power Platform 。 環境変数により、Power Platform 環境間でアプリケーションを移動という基本的なアプリケーション ライフサイクル管理 (ALM) シナリオが可能になります。 このシナリオでは、ソース環境と対象の環境で異なるいくつかの重要な外部参照を除いて、アプリケー ションはまったく同じままです。
環境 変数は、トピック、グローバル、システム 変数と同じように使用します。 注目すべき違いのひとつは、環境 変数は 読み取り専用 モードでのみ使用できることです。 エージェント の作成者は、 Copilot Studio の 環境 変数を変更できません。 ただし、管理者は PowerApps ポータルで環境変数の値を変更することができます。
Copilot Studio の環境変数の型は、以下のように PowerApps のデータ型にマッピングされます:
Copilot Studio に入力します | PowerApps に入力します |
---|---|
10 進数 | 回数 |
JSON | 値から型を検出します。 Json 以外 = > 未指定 (検証エラー) |
Text | string |
はい/いいえ | ブール値 |
Data source | string |
Secret | String |
注意
環境変数のエラーは、テスト チャットと公開時に表示されます。 ただし、これらのエラーはトピック変数ではないため、トピック リストには表示されません。
Copilot Studio では環境変数を作成したり編集したりすることはできません。 環境変数を変更または設定するには、PowerApps ポータルを使用する必要があります。 Copilot Studio から 変数 ペインを使用して、環境変数に関する情報を確認できます。 変数 ペインには、ネイティブ作成エクスペリエンスへのリンクもあります。
Azure Key Vault シークレットの環境変数を使用する
環境変数は、キー コンテナー内のシークレットを参照できます。 これは、独自の考慮事項がある環境変数の特殊なケースです。
PowerApps ポータルでシークレットの環境変数を作成するには、そのキー コンテナーを構成する必要があります。
上記の構成に加え、Copilot Studio がこのキー コンテナーを読み取ることを許可するには、以下の操作を実行する必要があります:
Key Vault Secrets User
ロールをMicrosoft Virtual Agents Service
アプリケーションに割り当てます。選択 のすべてのエージェントがシークレットにアクセスできるようにするには、シークレットにタグ
AllowedEnvironments
を作成し、許可された 選択IDをコンマで区切って追加します。環境 の特定のエージェントのみがこのKey Vaultを使用できるようにするには、タグを作成し、
AllowedAgents
の形式で エージェント 識別子を入力します{envId}/{schemaName}
。 複数の値を指定する場合は、カンマで区切ってください。
最大文字数に達したが、さらにエージェントを追加する必要がある場合は、説明的で一意の名前 (例: AllowedAgents2
) を持つ別のタグを追加します。
シークレット値はダイアログのランタイムに 5 分間キャッシュされます。 失敗した読み取りは 30 秒間キャッシュされます。
警告
エージェント にシークレットを追加すると、環境 で エージェント を編集できるすべてのユーザーにこのシークレットの値が公開される可能性があります。これは、そのようなユーザーが エージェント を編集して SendMessage
ノードに値を返すことができるためです。
システム変数
すべての エージェント には、会話に関する追加情報を提供する組み込みのシステム変数が付属しています。
ヒント
音声対応の エージェント 変数の詳細については、「 音声変数の使用」を参照してください。
すべてのシステム変数が一覧に表示されるわけではありません。 これら非表示のシステム変数にアクセスするには、Power Fx 式を使用する必要があります。
Power Fx 式でシステム変数を使用するには、変数名の前に System.
を付ける必要があります。 たとえば、システム変数 User.DisplayName
を数式に含めるには、次を参照します: System.User.DisplayName
。
件名 | タイプ | Definition |
---|---|---|
Activity.Attachments |
テーブル | ユーザーが提供するファイル添付ファイル |
Activity.Channel |
選択肢 | 現在の会話のチャンネル ID |
Activity.ChannelData |
指定なし | チャンネル固有のコンテンツを含むオブジェクト |
Activity.ChannelId |
string | 現在の会話のチャンネル ID (文字列) |
Activity.From.Id |
string | 送信者のチャンネル固有の一意の ID |
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 | エージェント の 環境ID |
Bot.Id |
string | エージェントのID |
Bot.Name |
string | エージェントの名前 |
Bot.SchemaName |
string | エージェントのスキーマ名 |
Bot.TenantId |
string | エージェントのテナントID |
ClientPluginActions |
選択肢 | 生成オーケストレーションに考慮すべき動的クライアントプラグインアクションのコレクション |
Conversation.Id |
string | 現在の会話の一意の ID |
Conversation.InTestMode |
ブール値 | テスト キャンバスで会話が行われているかどうかを表すブール値のフラグ |
Conversation.LocalTimeZone |
string | IANA タイム ゾーン データベース形式でユーザーが使用するタイム ゾーンの名前 |
Conversation.LocalTimeZoneOffset |
datetime | 現在のローカルタイムゾーンの UTC からの時間オフセット |
Error.Code |
string | 現在のエラーのエラー コードです。 注: この変数は、トリガー が |
Error.Message |
string | 現在のエラーのエラー メッセージです。 注: この変数は、トリガー が |
FallbackCount |
number | この変数は、トピックがユーザー入力と一致しなかった回数をカウントします。 注: この変数は、トリガー が |
InactivityTimer.Continue |
ブール値 | タイマーを継続する必要があるかどうかを表すブール値 フラグです。 注: この変数は、トリガー が |
InactivityTimer.Count |
number | 設定された時間経過後にユーザーが非アクティブであったために OnInactivity タイマーが起動した回数です。 注: この変数は、トリガー が |
LastMessage.Id |
string | ユーザが前に送信したメッセージの ID |
LastMessage.Text |
string | ユーザーが前に送信したメッセージです |
Recognizer.ExtractedEntities |
選択肢 | トリガー メッセージから抽出されたエンティティを表します。 注: この変数は、トリガー が |
Recognizer.IntentOptions |
選択肢 | 認識エンジンがあいまいな結果を返す場合の意図のオプションを表します。 注: この変数は、トリガー が |
Recognizer.SelectedIntent |
選択肢 | 認識装置から選択された意図を表します。 注: この変数は、トリガー が |
Recognizer.TriggeringMessage.Id |
string | 現在のトピックをトリガーしたユーザー メッセージの ID |
Recognizer.TriggeringMessage.Text |
string | 現在のトピックをトリガーしたユーザー メッセージ |
Recognizer.MultipleTopicsMatchedReason |
string | 複数のトピックが一致した理由を判断するために使用されます。 注: この変数は、トリガー が |
User.Language |
選択肢 | この変数は、会話ごとにユーザーの言語ロケールを設定するために使用されます。 |
SignInReason |
選択肢 | トピック をトリガーするときに必要なサインイン オプションを決定するために使用されます。 注: この変数は、トリガー が |
統合認証の変数 (既定)
エージェント をMicrosoftで認証するように構成した場合、次の変数が使用できます。 この場合、Entra ID 認証が使用され、Teams と PowerApps チャンネルのみが許可されます。 これは新しいエージェントのデフォルトです。
詳細については、「 認証変数」を参照してください。
件名 | タイプ | Definition |
---|---|---|
User.DisplayName |
string | 現在 エージェント と会話しているユーザーの 表示名。 |
User.Email |
string | 現在 エージェント と会話しているユーザーのメール アドレス。 |
User.FirstName |
string | 現在 エージェント と会話しているユーザーの 名。 |
User.Id |
string | 現在 エージェント と会話しているユーザーの一意のID。 |
User.IsLoggedIn |
ブール値 | エージェント と現在通信しているユーザーが認証されているかどうかを表す ブール値 フラグ。 |
User.LastName |
string | 現在 エージェント と会話しているユーザーの 姓。 |
User.PrincipalName |
string | 現在 エージェント と通信しているユーザーのユーザー プリンシパル名。 |
Generic OAuth 2による手動認証の変数
エージェント をGeneric OAuth 2サービス プロバイダーを使用するように構成した場合、次の変数が使用できます。
件名 | タイプ | Definition |
---|---|---|
User.AccessToken |
string | エージェント で認証するユーザー用の アクセス トークン。 |
User.DisplayName |
string | 現在 エージェント と会話しているユーザーの 表示名。 |
User.Id |
string | 現在 エージェント と会話しているユーザーの一意のID。 |
User.IsLoggedIn |
ブール値 | エージェント と現在通信しているユーザーが認証されているかどうかを表す ブール値 フラグ。 |
Microsoft Entra ID による手動認証の変数
次の変数は、エージェント を Microsoft Entra ID (旧称 Azure Active Directory) サービス プロバイダーを使用するように構成した場合に使用できます。
件名 | タイプ | Definition |
---|---|---|
User.AccessToken |
string | エージェント で認証するユーザー用の アクセス トークン。 |
User.DisplayName |
string | 現在 エージェント と会話しているユーザーの 表示名。 |
User.Email |
string | 現在 エージェント と会話しているユーザーのメール アドレス。 |
User.FirstName |
string | 現在 エージェント と会話しているユーザーの 名。 |
User.Id |
string | 現在 エージェント と会話しているユーザーの一意のID。 |
User.IsLoggedIn |
ブール値 | エージェント と現在通信しているユーザーが認証されているかどうかを表す ブール値 フラグ。 |
User.LastName |
string | 現在 エージェント と会話しているユーザーの 姓。 |
User.PrincipalName |
string | 現在 エージェント と通信しているユーザーのユーザー プリンシパル名。 |
音声対応エージェントの変数
次の変数は、音声対応エージェントでのみ使用できます。
ヒント
音声対応の エージェント 変数の詳細については、「 音声変数の使用」を参照してください。
件名 | タイプ | Definition |
---|---|---|
Activity.InputDTMFKeys |
string | テレフォニーから受信した生の DTMF キー値。 |
Activity.SpeechRecognition.Confidence |
number | ASR仮説全体の結果に対する信頼スコア。0 から 1。 |
Activity.SpeechRecognition.MinimallyFormattedText |
string | ASR 仮説の結果のわずかにフォーマットされたテキスト。 例: 500 ドル。 単語は綴られていますが、基本的な大文字と句読点は含まれています。 |
Activity.UserInputType |
選択肢 | エンドユーザーの最新の入力からの入力タイプ。 値はテスト、スピーチ、DTMF のいずれかを指定します。 |
Conversation.OnlyAllowDTMF |
ブール値 | 実行時に IVR を DTMF のみのモードに設定するかどうかを表す選択フラグです。 |
Conversation.SipUuiHeaderValue |
string | 通話開始時にコンテキストを IVR に渡すために使用される UUI ヘッダー文字列です。 |
トピック間で変数を渡す
あるトピックを別のトピックにリダイレクトすると、元のトピックと宛先トピックの間で変数の値を渡すことができます。 トピック間で変数を渡すことは、後のトピックが必要とする情報がすでに収集されている場合に特に役立ちます。 ユーザーは、同じ質問に再度答える必要がないことを評価するでしょう。
他のトピックから値を受け取る
トピック が変数を定義すると (たとえば、質問ノードで)、エージェント はユーザーに変数の値を入力するよう質問します。 エージェント が以前の トピック ですでに値を取得している場合は、再度質問する必要はありません。 このような場合、変数を他のトピックから値を受け取るに設定することができます。 別のトピックがこのトピックにリダイレクトされるとき、この変数に変数の値 (またはリテラル値) を渡して、質問をスキップすることができます。 ユーザーからエージェントへの会話のエクスペリエンスはシームレスです。
この例では、「グリーティング」と「顧客と交渉する」の 2 つのトピックを使用します。 両方のトピックが顧客の名前を尋ねます。 ただし、「グリーティング」トピックが最初に実行される場合、「顧客と交渉する」トピックはその質問をスキップします。 代わりに、「グリーティング」トピックから渡された変数の値を使用します。
「顧客と交渉する」トピックのフローは次のとおりです。
Testエージェント ペインに示されているように、この トピック が最初にトリガーされると、ユーザーに「何とお呼びすればよいですか?」と尋ねます。その値は、という文字列変数に格納されます userName
。 userName
変数は、他のトピックから値を取得するようにも設定されています。 トピックは「素晴らしい一日になることを願っています、{userName}!」というメッセージで締めくくります。
「グリーティング」トピックのフローは次のとおりです。
Testエージェント ペインに示されているように、この トピック が最初にトリガーされると、ユーザーに「お名前は何ですか?」と尋ねます。その値は、という文字列変数に格納されます UserName
。 トピックは、「はじめまして、{UserName}!」というメッセージを送信します。次に、「顧客と交渉する」トピックにリダイレクトされ、「素晴らしい一日になることを願っています、{userName}!」というメッセージが送信されます。ただし、「顧客と交渉する」トピックでは、ユーザーの名前を再度尋ねることがスキップされたことに注目してください。 代わりに、「グリーティング」トピックから渡された UserName
変数の値が使用されました。
最後に、2 つ目の会話を再度示します。今回は「顧客と交渉する」トピックの視点からです。
他のトピックから値を受け取るようにトピックを設定する手順を見ていきましょう。 現在の例を使用しますが、トピックが以前のトピックから値を取得する必要がある場合はいつでも同じ手順が機能します。
宛先のトピックを設定する
宛先トピックは、リダイレクト先のトピックであり、他のトピックから値を受け取ります。 この例では、「顧客と交渉する」です。
宛先トピックを作成するか、そこに移動します。
質問ノードを追加し、メッセージに
What should I call you?
を入力します。特定の下で、構築済みエンティティ 個人名 を選択します。
変数を選択し、変数プロパティ ウィンドウが開きます。
userName
という名前を付けて、他のトピックから値を受け取るを選択します。メッセージ ボックスに、
I hope you're having a wonderful day,
を入力します。変数の挿入アイコン ({x}) を選択し、userName を選択します。
変数の後のスペースを選択し、
!
と入力します。トピックを保存します。
ソース トピックを設定する
ソース トピックはリダイレクトを行うトピックのことで、宛先トピックに渡される値を提供します。 この例では、「グリーティング」です。
ソース トピックに移動します。
リダイレクト ノードを追加し 、宛先を トピック します 選択。
+ 入力の追加を選択し、値を渡す先の宛先トピックからの変数を選択します。
> アイコンを選択し、値を渡す変数を選択します。
リダイレクト ノードは次のようになります。
トピックを保存します。
値を元のトピックに戻す
トピックがリダイレクトされる場合や、質問をすることや他の方法で変数を取得する場合、変数は元のトピックに返すことができます。 変数も元のトピックの一部となり、他の変数と同様に使用することができます。 エージェント が取得する情報はトピック間で利用できるため、 グローバル変数の必要性が軽減されます。
前のセクションからの例を継続しましょう。 「顧客と交渉する」トピックで新しい質問をしてから、「グリーティング」トピックに回答を返します。
返される変数のソース トピックを設定する
トピックに変数を返す場合、ソース トピックはリダイレクトされたトピックであり、元のトピックに戻される値を提供します。 この例では、「顧客と交渉する」です。
ソース トピックに移動します。
質問ノードを追加し、メッセージに
What city do you live in?
を入力します。特定 配下で、構築済みエンティティ 都市 を選択します。
変数を選択し、変数プロパティ ウィンドウが開きます。
userCity
という名前を付けて、元のトピックへ値を返すを選択します。トピックを保存します。
返される変数の宛先トピックを設定する
変数をトピックに返す場合、宛先トピックはリダイレクトを行っているトピックのことで、他のトピックから値を受け取るトピックです。 この例では、「グリーティング」です。
宛先のトピックに移動します。
ソース トピックで選択した変数は、リダイレクト ノードに出力変数として表示されます。
トピックを保存します。