変数の概要
変数は 4 つのレベル、またはスコープで存在できます:
- トピック変数は、作成されたトピック内でのみ使用することができます。 このスコープが、作成された変数の既定値です。
- グローバル変数はすべてのトピックで使用することができます。 トピック変数のスコープを変更し、グローバル変数にすることができます。
- システム変数は エージェントで自動的に作成されます。 それらは、会話またはユーザーについてより多くのコンテキスト情報を提供します。 すべてのトピックで使用可能です。
- 環境変数 は Power Platform で作成され、Copilot Studio で読み取り専用となります。 パラメーターのキーと値が格納され、Copilot Studio を含む他のさまざまなアプリケーション オブジェクトの入力として機能します。 消費オブジェクトからパラメーターを分離すると、同じ環境内で、または他の環境にソリューションを移行するときに値を変更できます。 代替方法は、ハードコーディングされたパラメーター値を、それらを使用するコンポーネント内に残すことです。
変数の型
変数は基本タイプと関連付けられます。 型は、変数が含むことのできる値や、論理式を構成する際に使用できる演算子を決定します。
| タイプ | Description |
|---|---|
| String | テキストを表すために使用される一連の文字 |
| ブール型 | true または false の論理値 |
| 回数 | 任意の実数 |
| テーブル | 値のリスト。ただし、すべての値は同じ型である必要があります |
| Record | 名前と値のペアのコレクション。値は任意の型 |
| DateTime | ある時点に関する日付、時刻、曜日、または月 |
| 選択肢 | 関連する同義語を含む文字列値のリスト |
| 空白 | 「値がない」または「不明な値」のプレースホルダー。詳細については、Power Fx の空白を参照してください |
変数の型は、値が最初に割り当てられるときに設定されます。 その後、変数の型は固定され、他の型の値を割り当てることはできなくなります。 たとえば、開始値 1 の変数には 数値 型が割り当てられます。 これを 文字列 の値 "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 |
| ユーザー定義エンティティ | 選択肢 |
環境変数
環境変数 は Power Platform のコンセプトです。 環境変数により、Power Platform 環境間でアプリケーションを移動という基本的なアプリケーション ライフサイクル管理 (ALM) シナリオが可能になります。 このシナリオでは、ソース環境と対象の環境で異なるいくつかの重要な外部参照を除いて、アプリケー ションはまったく同じままです。
環境 変数は、トピック、グローバル、システム変数と同じように使用します。 Copilot Studioでの注目すべき違いの 1 つは、環境変数が 読み取り専用 であることです。 エージェント 作成者は Copilot Studio の環境変数を変更できません。 しかし、管理者は Power Apps で環境変数の値を変更することができます。 Copilot Studio では、変数パネル を使って環境変数の情報を見ることができます。 変数 パネルには、直感的な作成体験へのリンクもあります。
環境変数を使用するエージェントの公開バージョンには、エージェントが公開されたときにこれらの変数に設定された値が含まれます。 管理者が環境変数を更新するたびに、実行時に変更を有効にするために、これらの変数を使用するエージェントを再公開する必要があります。 ただし、1つだけ例外があります。secret 型の環境変数の値が変更された場合、エージェントを再公開する必要はありません。 他の環境変数とは異なり、シークレット変数は実行時に取得されます。
Copilot Studio の環境変数の型は、以下のように Power Apps のデータ型にマッピングされます:
| Copilot Studio に入力します | Power Apps に入力します |
|---|---|
| 10 進数 | 回数 |
| JSON | 値から型を検出します。 JSON ではない場合 = > 未指定 (検証エラー) |
| Text | String |
| はい/いいえ | ブール値 |
| Data source | String |
| Secret | String |
ヒント
環境変数のエラーは、テスト チャットと公開時に表示されます。 ただし、これらのエラーはトピック変数ではないため、トピック リストには表示されません。
システム変数
すべてのエージェントには、会話に関する追加情報を提供する組み込みのシステム変数が付属しています。
ヒント
音声対応の エージェント 変数の詳細については、「音声変数を使用する 」を参照してください。
すべてのシステム変数が一覧に表示されるわけではありません。 これら非表示のシステム変数にアクセスするには、Power Fx 式を使用する必要があります。
Power Fx 式でシステム変数を使用するには、変数名の前に System. を付ける必要があります。 たとえば、システム変数 User.DisplayName を数式に含めるには、次を参照します: System.User.DisplayName。
| 件名 | タイプ | Definition |
|---|---|---|
| すべての活動添付ファイル | テーブル | ユーザーが提供するファイル添付ファイル |
| 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 | 現在のエラーのエラーメッセージです。 注: この変数は、トリガーが On Error の場合のみサポートされます。 |
| FallbackCount | number | この変数は、トピックがユーザー入力と一致しなかった回数をカウントします。 注: この変数は、トリガーが On Unknown Intent の場合のみサポートされます。 |
| InactivityTimer.Continue | ブール値 | タイマーを継続する必要があるかどうかを表すブール値 フラグです。 注: この変数は、トリガーが Inactivity の場合のみサポートされます。 |
| InactivityTimer.Count | number | 設定された時間経過後にユーザーが非アクティブであったために OnInactivity タイマーが起動した回数です。 注: この変数は、トリガーが Inactivity の場合のみサポートされます。 |
| LastMessage.Id | string | ユーザが前に送信したメッセージの ID |
| LastMessage.Text | string | ユーザーが前に送信したメッセージです |
| Recognizer.ExtractedEntities | 選択肢 | トリガー メッセージから抽出されたエンティティを表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.IntentOptions | 選択肢 | 認識エンジンがあいまいな結果を返す場合の意図のオプションを表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.SelectedIntent | 選択肢 | 認識装置から選択された意図を表します。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| Recognizer.TriggeringMessage.Id | string | 現在のトピックをトリガーしたユーザー メッセージの ID |
| Recognizer.TriggeringMessage.Text | string | 現在のトピックをトリガーしたユーザー メッセージ |
| Recognizer.MultipleTopicsMatchedReason | string | 複数のトピックが一致した理由を特定するために使用されます。 注: この変数は、トリガーが On Select Intent の場合のみサポートされます。 |
| SignInReason | 選択肢 | トピック をトリガーするときに必要なサインイン オプションを決定するために使用されます。 注: この変数は、トリガーが On Sign In の場合のみサポートされます。 |
| User.Language | 選択肢 | この変数は、会話ごとにユーザーの言語ロケールを設定するために使用されます。 |
統合認証の変数 (既定)
Microsoft で認証するように構成されたエージェントでは、以下の変数が使用できます。 この構成は Microsoft Entra ID 認証を使用し、新規エージェントの既定です。
詳細については、認証変数 を参照してください。
| 件名 | タイプ | Definition |
|---|---|---|
| User.DisplayName | string | 現在 エージェント と会話しているユーザーの表示名。 |
| User.Email | string | 現在 エージェント と話しているユーザーのメールアドレス。 |
| User.FirstName | string | 現在 エージェント と話しているユーザーの名。 |
| User.Id | string | 現在 エージェント と会話しているユーザーの一意の ID。 |
| User.IsLoggedIn | ブール値 | 現在 エージェント と話しているユーザーが認証されているかどうかを表すブール値フラグ。 |
| User.LastName | string | 現在エージェントと会話しているユーザーのファミリー名です。 |
| User.PrincipalName | string | 現在エージェントと会話しているユーザーのユーザー プリンシパル名です。 |
汎用 OAuth による手動認証のための変数 2
以下の変数は、汎用 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 | Azure Site Recovery 仮説全体の結果の信頼度スコア (0 ～ 1)。 |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Azure Site Recovery 仮説の結果をわずかに整形したテキストです。 例: 500 ドル。 単語は綴られていますが、基本的な大文字と句読点は含まれています。 |
| Activity.UserInputType | 選択肢 | ユーザーの最新の入力からの入力タイプ。 値はテスト、スピーチ、DTMF のいずれかを指定します。 |
| Conversation.OnlyAllowDTMF | ブール値 | 実行時に IVR を DTMF のみのモードに設定するかどうかを表す選択フラグです。 |
| Conversation.SipUuiHeaderValue | string | 通話開始時にコンテキストを IVR に渡すために使用される UUI ヘッダー文字列です。 |