変数は、次の 4 つのレベル (スコープ) で存在します。
- トピック変数は、作成するトピックでのみ使用できます。 このスコープが、作成された変数の既定値です。
- すべてのトピックで使用できるグローバル変数。 トピック変数のスコープを変更し、グローバル変数にすることができます。
- Copilot Studio がエージェントに対して自動的に作成するシステム変数。 それらは、会話またはユーザーについてより多くのコンテキスト情報を提供します。 すべてのトピックで使用可能です。
- Power Platform で作成する環境変数。 Copilot Studio では読み取り専用です。 パラメーターのキーと値を保存し、Copilot Studio を含むさまざまな他のアプリケーション オブジェクトへの入力として機能します。 消費オブジェクトからパラメーターを分離すると、同じ環境内で、または他の環境にソリューションを移行するときに値を変更できます。 代わりに、パラメーターの値を、それらを使用するコンポーネント内にハード コードされたパラメーター値で残す方法があります。
変数の型
各変数には、基本タイプがあります。 型によって、変数が保持できる値と、それを使用して論理式を構築するときに使用できる演算子が決まります。
| タイプ | 説明 |
|---|---|
| 文字列 | テキストを表すために使用される一連の文字 |
| ブール値 |
true または false のみに設定できる論理値 |
| 数 | 任意の実数 |
| テーブル | 値のリスト。ただし、すべての値は同じ型である必要があります |
| 記録 | 名前と値のペアのコレクション。値は任意の型 |
| 日付時刻 | ある時点に関する日付、時刻、曜日、または月 |
| 選択肢 | 関連する同義語を含む文字列値のリスト |
| 空白 | "値なし" または "不明な値" のプレースホルダー。詳細については、Power Fx ドキュメントの空白を参照してください |
変数の型は、初めて値を代入するときに設定します。 その後、型は固定され、他の型の値を割り当てることはできません。 たとえば、変数に開始値 1 を割り当てる場合、その型を数値に設定します。 その後、 などの"apples"値を割り当てようとすると、エラーが発生します。
エージェントをテストすると、変数が一時的に型不明で表示される場合があります。 不明な変数には、まだ値がありません。
変数の順序は、オーサリング キャンバスの上から下に決定されます。 作成キャンバスの上部にあるノードは、下部にあるノードよりも先に考慮されます。
条件ノードで分岐を作成するとき、ブランチは左から右に並べられます。 左端の分岐のノードは、右端の分岐のノードよりも先に考慮されます。
エンティティ
Copilot Studio は、エンティティを使用して、ユーザーの応答から特定の種類の情報を識別します。 識別された情報は、情報に適した型の変数に保存されます。 次の表に、構築済みエンティティに関連する変数ベースタイプを示します。
| エンティティ | 変数の基本型 |
|---|---|
| 複数選択オプション | 選択肢 |
| ユーザーの応答全体 | 文字列 |
| 年齢 | 数 |
| ブール値 | ブール値 |
| 都市 | 文字列 |
| 色 | 文字列 |
| 大陸 | 文字列 |
| 国または地域 | 文字列 |
| 日時 | 日付時刻 |
| 文字列 | |
| イベント | 文字列 |
| 整数 | 整数 |
| Language | 文字列 |
| お金 | 数 |
| 数 | 数 |
| 序数 | 数 |
| 組織 | 文字列 |
| パーセント | 数 |
| 個人名 | 文字列 |
| 電話番号 | 文字列 |
| 注目ポイント | 文字列 |
| 速度 | 数 |
| 状態 | 文字列 |
| 番地 | 文字列 |
| 温度 | 数 |
| URL | 文字列 |
| 重量 | 数 |
| 郵便番号 | 文字列 |
| ユーザー定義エンティティ | 選択肢 |
環境変数
環境変数は、Power Platform の概念です。 環境変数により、Power Platform 環境間でアプリケーションを移動という基本的なアプリケーション ライフサイクル管理 (ALM) シナリオが可能になります。 このシナリオでは、ソース環境と対象の環境で異なるいくつかの重要な外部参照を除いて、アプリケー ションはまったく同じままです。
環境 変数は、トピック、グローバル、システム変数と同じように使用します。 顕著な違いの 1 つは、Copilot Studioでは環境変数が読み取り専用であることです。 エージェント作成者は、Copilot Studio の環境変数を変更できません。 ただし、管理者は Power Apps で環境変数の値を変更できます。 Copilot Studioでは、変数パネルを使用して、環境変数に関する情報を表示できます。 変数プロパティ パネルには、環境変数の作成エクスペリエンスである Power Apps へのリンクもあります。
環境変数を使用するエージェントの公開バージョンには、エージェントの公開時にこれらの変数に設定された値があります。 管理者が環境変数を更新するたびに、これらの変数を使用するエージェントを再公開し、実行時に変更を有効にする必要があります。 ただし、1つだけ例外があります。secret 型の環境変数の値が変更された場合、エージェントを再公開する必要はありません。 他の環境変数とは異なり、シークレット変数は実行時に取得されます。
Copilot Studio の環境変数の型は、次のように Power Apps のデータ型にマップされます。
| Copilot Studio で入力する | Power Apps にタイプする |
|---|---|
| 10 進数 | 数 |
| JSON | 値から型を検出します。 JSON ではない場合 = > 未指定 (検証エラー) |
| テキスト | 文字列 |
| はい/いいえ | ブール値 |
| データ ソース | 文字列 |
| シークレット | 文字列 |
注意
環境変数のエラーは、テスト チャットと公開時に表示されます。 ただし、これらのエラーはトピック変数ではないため、トピック リストには表示されません。
システム変数
すべてのエージェントには、会話に関する追加情報を提供する組み込みシステム変数が付属しています。
注意
音声対応の エージェント 変数の詳細については、「音声変数を使用する 」を参照してください。
Copilot Studio では、すべてのシステム変数が表示されるわけではありません。 非表示のシステム変数にアクセスするには、Power Fx 数式を使用します。
Power Fx 数式でシステム変数を使用するには、変数名の前に System. を追加します。 たとえば、システム変数 User.DisplayName を数式に含めるには、次を参照します: System.User.DisplayName。
| 名前 | タイプ | 定義 |
|---|---|---|
| アクティビティ.添付ファイル | テーブル | ユーザーが提供する添付ファイル。 |
| アクティビティ・チャネル | 選択肢 | 現在の会話のチャンネル ID。 |
| Activity.ChannelData | 任意 | チャンネル固有のコンテンツを含むオブジェクトです。 |
| Activity.ChannelId | 文字列 | 現在の会話のチャンネル ID (文字列)。 |
| Activity.From.Id | 文字列 | 送信者のチャンネル固有の一意の ID。 |
| Activity.From.Name | 文字列 | チャンネル固有のユーザー フレンドリーな送信者名。 |
| アクティビティ.ネーム | 文字列 | イベントの名前。 |
| Activity.Recipient.Id | 文字列 | 受信アクティビティのタイプ プロパティ。 |
| Activity.Recipient.Name | 文字列 | チャネル内のエージェントの表示名を表します。 テレフォニー チャネルのコンテキストでは、この変数の値は エージェント が付加されている電話番号になります。 |
| アクティビティ.テキスト | 文字列 | ユーザが最後に送信したメッセージ。 |
| アクティビティ・タイプ | 選択肢 | 活動の種類です。 |
| Activity.TypeId | 文字列 | アクティビティの種類です (文字列)。 |
| アクティビティ.バリュー | 任意 | オープン エンドの値です。 |
| Bot.EnvironmentId | 文字列 | エージェントの環境 ID です。 |
| Bot.Id | 文字列 | エージェントの ID。 |
| Bot.Name | 文字列 | エージェントの名前。 |
| Bot.SchemaName | 文字列 | エージェントのスキーマ名。 |
| Bot.TenantId | 文字列 | エージェントのテナント ID。 |
| ClientPluginActions | 選択肢 | 生成オーケストレーションのために考慮すべきダイナミック クライアント プラグイン アクションのコレクション。 |
| Conversation.Id | 文字列 | 現在の会話の一意の ID。 |
| 会話.テストモード | ブール値 | テスト キャンバスで会話が行われているかどうかを表すブール値のフラグです。 |
| Conversation.LocalTimeZone | 文字列 | IANA タイム ゾーン データベース形式でユーザーが使用するタイム ゾーンの名前です。 |
| 会話.ローカルタイムゾーンオフセット | datetime | 現在のローカルタイムゾーンの UTC からの時間オフセットです。 |
| Error.Code | 文字列 | 現在のエラーのエラー コードです。 現在のエラーのエラーメッセージです。 |
| エラーメッセージ | 文字列 | 現在のエラーのエラーメッセージです。 注: この変数は、トリガーが On Error の場合のみサポートされます。 |
| FallbackCount | 数値 | この変数は、トピックがユーザー入力と一致しなかった回数をカウントします。 注: この変数は、トリガーが On Unknown Intent の場合のみサポートされます。 |
| InactivityTimer.Continue | ブール値 | タイマーを継続する必要があるかどうかを表すブール値 フラグです。 注: この変数は、トリガーが Inactivity の場合のみサポートされます。 |
| InactivityTimer.Count | 数値 | 設定した時間が経過した後、ユーザーが非アクティブであったために OnInactivity タイマーが起動した回数。 注: この変数は、トリガーが Inactivity の場合のみサポートされます。 |
| LastMessage.Id | 文字列 | ユーザが前に送信したメッセージの ID。 |
| LastMessage.Text | 文字列 | ユーザーが前に送信したメッセージです。 |
| Recognizer.ExtractedEntities | 選択肢 | トリガー メッセージから抽出されたエンティティを表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.IntentOptions (レコグナイザー.インテントオプション) | 選択肢 | 認識エンジンがあいまいな結果を返す場合の意図オプションを表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.SelectedIntent (レコグナイザー.セレクティドインテント) | 選択肢 | 認識装置から選択された意図を表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.TriggeringMessage.Id | 文字列 | 現在のトピックをトリガーしたユーザー メッセージの ID。 |
| Recognizer.TriggeringMessage.Text | 文字列 | 現在のトピックをトリガーしたユーザー メッセージ。 |
| 認識器.複数のトピックの一致理由 | 文字列 | 複数のトピックが一致した理由を特定するために使用されます。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| サインイン理由 | 選択肢 | トピック をトリガーするときに必要なサインイン オプションを決定するために使用されます。 注: この変数は、トリガーが On Sign In の場合のみサポートされます。 |
| User.Language | 選択肢 | この変数は、会話ごとにユーザーの言語ロケールを設定するために使用されます。 |
統合認証の変数 (既定)
Microsoft で認証するように構成されたエージェントでは、以下の変数が使用できます。 この構成は Microsoft Entra ID 認証を使用し、新しいエージェントの既定値です。
詳細については、認証変数 を参照してください。
| 名前 | タイプ | 定義 |
|---|---|---|
| ユーザー.表示名 | 文字列 | 現在 エージェント と会話しているユーザーの表示名。 |
| ユーザー.Email | 文字列 | 現在 エージェント と話しているユーザーのメールアドレス。 |
| ユーザー.FirstName | 文字列 | 現在 エージェント と話しているユーザーの名。 |
| User.Id | 文字列 | 現在 エージェント と会話しているユーザーの一意の ID。 |
| User.IsLoggedIn | ブール値 | 現在 エージェント と話しているユーザーが認証されているかどうかを表すブール値フラグ。 |
| ユーザー.姓 | 文字列 | 現在エージェントと会話しているユーザーのファミリー名です。 |
| User.PrincipalName | 文字列 | 現在エージェントと会話しているユーザーのユーザー プリンシパル名です。 |
汎用 OAuth 2 による手動認証の変数
次の変数は、汎用 OAuth 2 サービス プロバイダーを使用するように構成されたエージェントで使用できます。
| 名前 | タイプ | 定義 |
|---|---|---|
| User.AccessToken | 文字列 | エージェント で認証するユーザーのアクセス トークン。 |
| ユーザー.表示名 | 文字列 | 現在 エージェント と会話しているユーザーの表示名。 |
| User.Id | 文字列 | 現在 エージェント と会話しているユーザーの一意の ID。 |
| User.IsLoggedIn | ブール値 | 現在 エージェント と話しているユーザーが認証されているかどうかを表すブール値フラグ。 |
Microsoft Entra ID による手動認証の変数
次の変数は、Microsoft Entra ID (以前の Azure Active Directory) サービス プロバイダーを使用するように構成されたエージェントで使用できます。
| 名前 | タイプ | 定義 |
|---|---|---|
| User.AccessToken | 文字列 | エージェント で認証するユーザーのアクセス トークン。 |
| ユーザー.表示名 | 文字列 | 現在 エージェント と会話しているユーザーの表示名。 |
| ユーザー.Email | 文字列 | 現在 エージェント と話しているユーザーのメールアドレス。 |
| ユーザー.FirstName | 文字列 | 現在 エージェント と話しているユーザーの名。 |
| User.Id | 文字列 | 現在 エージェント と会話しているユーザーの一意の ID。 |
| User.IsLoggedIn | ブール値 | 現在 エージェント と話しているユーザーが認証されているかどうかを表すブール値フラグ。 |
| ユーザー.姓 | 文字列 | 現在エージェントと会話しているユーザーのファミリー名です。 |
| User.PrincipalName | 文字列 | エージェントと現在話しているユーザーのプリンシパル名です。 |
音声有効化エージェントの変数
次の変数は、音声対応エージェントでのみ使用できます。
注意
音声対応の エージェント 変数の詳細については、「音声変数を使用する 」を参照してください。
| 名前 | タイプ | 定義 |
|---|---|---|
| Activity.InputDTMFKeys | 文字列 | テレフォニーからの未加工の DTMF キー値。 |
| アクティビティ.音声認識.信頼度 | 数値 | Azure Site Recovery 仮説全体の結果の信頼度スコア (0 ～ 1)。 |
| Activity.音声認識.最小限書式設定テキスト | 文字列 | Azure Site Recovery 仮説の結果をわずかに整形したテキストです。 たとえば、"500 ドル" などです。単語は綴られていますが、基本的な大文字と句読点が含まれています。 |
| Activity.UserInputType | 選択肢 | エージェント ユーザーからの最新の入力のタイプ。 値はテスト、スピーチ、DTMF のいずれかを指定します。 |
| Conversation. DTMFのみを許可する | ブール値 | 実行時に IVR を DTMF のみのモードに設定するかどうかを表す選択フラグです。 |
| Conversation.SipUuiHeaderValue | 文字列 | 通話開始時にコンテキストを IVR に渡すために使用される UUI ヘッダー文字列です。 |