次の方法で共有


変数の使用

変数を使用して顧客の応答を保存し、会話の後半でコンテンツを再利用することができます。

変数を使用して、顧客を動的に別の会話パスにルーティングする論理式を作成することもできます。 たとえば、顧客の名前を 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 文字までです。

使用するエンティティを選択する

質問ノードは、デフォルトで複数選択オプション付きで作成されます。 別の事前構築済みエンティティまたはカスタム エンティティを使用するには、 [識別] ボックスをオンにして、エージェント がリッスンする情報の種類を選択します。

識別情報を選択メニューが開き、個人名エンティティが強調表示された質問ノードのスクリーンショット。

変数名を変更する

変数には、作成する時に自動的に名前が付けられます。 ベストプラクティスとしては、エージェント を管理する必要がある他のユーザーに目的が明確に伝わるように、変数に意味のある名前を付けることが挙げられます。

  1. 変数を選択し、変数プロパティ ペインで開きます。

  2. 変数名に、変数の新しい名前を入力します。

変数を設定する

通常、ユーザー入力を変数に保存するには、 Question ノードを使用します。 ただし、自分で値を設定したい場合もあります。 このような場合、変数値の設定ノードを使用します。

  1. ノードの追加 (+) を選択してノードを追加し、変数管理>変数値の設定 を選択します。

  2. 変数の設定の下にあるボックスを選択し、新しい変数を作成するを選択します。

    「新しい変数の作成」ボタンのスクリーンショット。

    新しい変数が作成されました。 値を割り当てるまでその型は不明です。

    変数値の設定ノードに型不明の新しい変数を設定した画面。

  3. 対象値には、次のいずれかの方法で値を指定します:

    • リテラル値を入力します。
    • 同じ型の既存の変数を選択します。 このアクションにより、選択した変数と同じ値が設定されます。
    • Power Fx 式を使用します。 Power Fx 式は、Table 型や Record 型などのリテラル値を使用できない、より複雑な型に有効です。

ヒント

文字列型変数を設定する際に、 変数の設定値への設定の間に不一致が発生した場合、エラー メッセージと 型の不一致を修正 ボタンが表示されます。 選択 ボタンをクリックすると、不一致を解決する Copilot Studio 数式 Power Fx が自動的に生成 されます。

リテラル値の使用

変数値を選択する代わりに、任意の変数にリテラル値を入力することができます。

productName という名前の変数のリテラル値の使用を示すスクリーンショット。

リダイレクト ノードの変数の入力にリテラル値を使用した場合のスクリーンショット。

ノードはリテラル値を文字列、数値、またはブール値として解釈を試みます。 たとえば、123 は数値として解釈されます。 文字列の値として解釈する場合は、"123" のように値を二重引用符で囲んでください。

いくつかのシナリオや、より複雑な型を使用する場合は、特定の型を設定するために Power Fx 式を使用します。

変数ペイン

変数ウィンドウでは、定義または使用されているノードに関係なく、トピックで使用可能なすべての変数を表示することができます。 変数ごとに、他のトピックから値を受け取るか、その値を他のトピックに返すか、またはその両方を行うかを選択できます。 変数を選択して、変数のプロパティ ペインでプロパティを編集することもできます。

変数ウィンドウを開くには、トピックのメニュー バーで、変数を選択します。

Copilot Studio 作成キャンバスの変数ペインのスクリーンショットで、変数ボタンが強調表示されています。

変数プロパティ ペイン

変数のプロパティ ウィンドウで、変数の名前を変更したり、変数が使用されている場所を確認したり、変数をグローバル変数に変換したりすることができます。 ただし、グローバル変数からトピック変数に戻すことはできません。 また、他のトピックから値を受け取るか、その値を他のトピックに渡すかを選択することもできます。

変数プロパティ ペインを開くには、変数ペインで変数を選択します。 任意のノードで変数を選択して、変数のプロパティ ウィンドウを開くこともできます。

変更可能なプロパティ ペインのスクリーンショット。

環境変数

環境 変数は 概念です Power Platform 。 環境変数により、Power Platform 環境間でアプリケーションを移動という基本的なアプリケーション ライフサイクル管理 (ALM) シナリオが可能になります。 このシナリオでは、ソース環境と対象の環境で異なるいくつかの重要な外部参照を除いて、アプリケー ションはまったく同じままです。

環境 変数は、トピックグローバルシステム 変数と同じように使用します。 注目すべき違いのひとつは、環境 変数は 読み取り専用 モードでのみ使用できることです。 エージェント の作成者は、 Copilot Studio の 環境 変数を変更できません。 ただし、管理者は PowerApps ポータルで環境変数の値を変更することができます。

環境変数に var の値を設定するトピック ページのスクリーンショット。

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 がこのキー コンテナーを読み取ることを許可するには、以下の操作を実行する必要があります:

  1. Key Vault Secrets User ロールを Microsoft Virtual Agents Service アプリケーションに割り当てます。

  2. 選択 のすべてのエージェントがシークレットにアクセスできるようにするには、シークレットにタグ AllowedEnvironments を作成し、許可された 選択IDをコンマで区切って追加します。

  3. 環境 の特定のエージェントのみがこの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

現在のエラーのエラー コードです。

: この変数は、トリガー が On Error の場合にのみサポートされます。

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 の場合にのみサポートされます。

User.Language 選択肢 この変数は、会話ごとにユーザーの言語ロケールを設定するために使用されます。
SignInReason 選択肢

トピック をトリガーするときに必要なサインイン オプションを決定するために使用されます。

: この変数は、トリガー が On Sign In の場合にのみサポートされます。

統合認証の変数 (既定)

エージェント を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エージェント ペインに示されているように、この トピック が最初にトリガーされると、ユーザーに「何とお呼びすればよいですか?」と尋ねます。その値は、という文字列変数に格納されます userNameuserName 変数は、他のトピックから値を取得するようにも設定されています。 トピックは「素晴らしい一日になることを願っています、{userName}!」というメッセージで締めくくります。

「グリーティング」トピックのフローは次のとおりです。

あいさつトピック 会話フローのスクリーンショット。

Testエージェント ペインに示されているように、この トピック が最初にトリガーされると、ユーザーに「お名前は何ですか?」と尋ねます。その値は、という文字列変数に格納されます UserName。 トピックは、「はじめまして、{UserName}!」というメッセージを送信します。次に、「顧客と交渉する」トピックにリダイレクトされ、「素晴らしい一日になることを願っています、{userName}!」というメッセージが送信されます。ただし、「顧客と交渉する」トピックでは、ユーザーの名前を再度尋ねることがスキップされたことに注目してください。 代わりに、「グリーティング」トピックから渡された UserName 変数の値が使用されました。

最後に、2 つ目の会話を再度示します。今回は「顧客と交渉する」トピックの視点からです。

あいさつトピック が最初にトリガーされたときの顧客 トピック 会話フローのスクリーンショット。

他のトピックから値を受け取るようにトピックを設定する手順を見ていきましょう。 現在の例を使用しますが、トピックが以前のトピックから値を取得する必要がある場合はいつでも同じ手順が機能します。

宛先のトピックを設定する

宛先トピックは、リダイレクト先のトピックであり、他のトピックから値を受け取ります。 この例では、「顧客と交渉する」です。

  1. 宛先トピックを作成するか、そこに移動します。

  2. 質問ノードを追加し、メッセージに What should I call you? を入力します。

  3. 特定の下で、構築済みエンティティ 個人名 を選択します。

  4. 変数を選択し、変数プロパティ ウィンドウが開きます。 userName という名前を付けて、他のトピックから値を受け取るを選択します。

    userName 変数とそのプロパティが強調表示された顧客 トピック との会話のスクリーンショット。

  5. メッセージ ノードを追加します

  6. メッセージ ボックスに、I hope you're having a wonderful day, を入力します。

  7. 変数の挿入アイコン ({x}) を選択し、userName を選択します。

  8. 変数の後のスペースを選択し、! と入力します。

  9. トピックを保存します。

ソース トピックを設定する

ソース トピックはリダイレクトを行うトピックのことで、宛先トピックに渡される値を提供します。 この例では、「グリーティング」です。

  1. ソース トピックに移動します。

  2. リダイレクト ノードを追加し 、宛先を トピック します 選択。

  3. + 入力の追加を選択し、値を渡す先の宛先トピックからの変数を選択します。

    リダイレクト ノードの入力として userName 変数が追加されたあいさつトピック のスクリーンショット。

  4. > アイコンを選択し、値を渡す変数を選択します。

    UserName 変数値を選択した Greeting トピックのスクリーンショット。

    リダイレクト ノードは次のようになります。

    Redirect ノードが完成した Greeting トピックのスクリーンショット。

  5. トピックを保存します。

値を元のトピックに戻す

トピックがリダイレクトされる場合や、質問をすることや他の方法で変数を取得する場合、変数は元のトピックに返すことができます。 変数も元のトピックの一部となり、他の変数と同様に使用することができます。 エージェント が取得する情報はトピック間で利用できるため、 グローバル変数の必要性が軽減されます。

前のセクションからの例を継続しましょう。 「顧客と交渉する」トピックで新しい質問をしてから、「グリーティング」トピックに回答を返します。

返される変数のソース トピックを設定する

トピックに変数を返す場合、ソース トピックはリダイレクトされたトピックであり、元のトピックに戻される値を提供します。 この例では、「顧客と交渉する」です。

  1. ソース トピックに移動します。

  2. 質問ノードを追加し、メッセージに What city do you live in? を入力します。

  3. 特定 配下で、構築済みエンティティ 都市 を選択します。

  4. 変数を選択し、変数プロパティ ウィンドウが開きます。 userCity という名前を付けて、元のトピックへ値を返すを選択します。

    userCity 変数とそのプロパティが強調表示された顧客 トピック との会話のスクリーンショット。

  5. トピックを保存します。

返される変数の宛先トピックを設定する

変数をトピックに返す場合、宛先トピックはリダイレクトを行っているトピックのことで、他のトピックから値を受け取るトピックです。 この例では、「グリーティング」です。

  1. 宛先のトピックに移動します。

  2. ソース トピックで選択した変数は、リダイレクト ノードに出力変数として表示されます。

    Redirect ノードで返された変数を使用した Greeting トピック 会話フローのスクリーンショット。

  3. トピックを保存します。