変数の使用
変数を使用して顧客の応答を保存し、会話の後半でコンテンツを再利用することができます。
変数を使用して、顧客を動的に別の会話パスにルーティングする論理式を作成することもできます。 たとえば、顧客の名前を UserName という変数に保存し、コパイロットは会話が継続しているときに名前で顧客に対応できます。
また、変数は他のトピックやPower Automateフローに渡したり、返したりすることができます。
変数は 4 つのレベル、またはスコープで存在できます:
- トピック 変数は、作成されたトピック内でのみ使用できます。 このスコープが、作成された変数の既定値です。
- グローバル変数 はすべてのトピックで使用できます。 トピック変数のスコープを変更し、グローバル変数にすることができます。
- システム変数 は副操縦士によって自動的に作成されます。 それらは、会話またはユーザーについてより多くのコンテキスト情報を提供します。 すべてのトピックで使用可能です。
- トリガー 変数 は Power Platform で作成され、 Copilot Studioで読み取り専用になります。 パラメーターのキーと値が格納され、Copilot Studio を含む他のさまざまなアプリケーション オブジェクトの入力として機能します。 消費オブジェクトからパラメーターを分離すると、同じ環境内で、または他の環境にソリューションを移行するときに値を変更できます。 代替方法は、ハードコーディングされたパラメーター値を、それらを使用するコンポーネント内に残すことです。
変数の型
変数は基本タイプと関連付けられます。 型は、変数が含むことのできる値や、論理式を構成する際に使用できる演算子を決定します。
| タイプ | Description |
|---|---|
| String | テキストを表すために使用される一連の文字 |
| ブール型 | true または false の論理値 |
| 回数 | 任意の実数 |
| テーブル | 値のリスト。ただし、すべての値は同じ型である必要があります |
| Record | 名前と値のペアのコレクション。値は任意の型 |
| DateTime | ある時点に関する日付、時刻、曜日、または月 |
| 選択肢 | 関連する同義語を含む文字列値のリスト |
| 空白 | 「値がない」または「不明な値」のプレースホルダー。詳細については、Power Fx の空白を参照してください |
変数の型は、値が最初に割り当てられるときに設定されます。 その後、変数の型は固定され、他の型の値を割り当てることはできなくなります。 たとえば、開始値 1 の変数には 数値 型が割り当てられます。 これを String value "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 の作成者は、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 をカンマ区切りで追加します。環境から特定のコパイロットだけにこのキー コンテナーの使用を許可するには、タグ
AllowedCopilotsを作成し、コパイロット識別子を{envId}/{schemaName}の形式で記述します。 複数の値を指定する場合は、カンマで区切ってください。
文字数の上限に達しても、さらにコパイロットを追加する必要がある場合は、説明的で一意の名前 (例: AllowedCopilots2) を持つ別のタグを追加してください。
シークレット値はダイアログのランタイムに 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 |
選択肢 | トピック をトリガーするときに必要なサインイン オプションを決定するために使用されます。 注: この変数は、トリガー が |
統合認証の変数 (既定)
コパイロットをマイクロソフトで認証するように構成した場合、以下の変数を使用できます。 この場合、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 つのトピックを使用します。 両方のトピックが顧客の名前を尋ねます。 ただし、「グリーティング」トピックが最初に実行される場合、「顧客と交渉する」トピックはその質問をスキップします。 代わりに、「グリーティング」トピックから渡された変数の値を使用します。
「顧客と交渉する」トピックのフローは次のとおりです。
コパイロットのテスト ペインに示されているように、このトピックが最初にトリガーされると、ユーザーに「何とお呼びしたらよいですか?」と尋ねます。値を userName という文字列変数に格納します。 userName 変数は、他のトピックから値を取得するようにも設定されています。 トピックは「素晴らしい一日になることを願っています、{userName}!」というメッセージで締めくくります。
「グリーティング」トピックのフローは次のとおりです。
コパイロットのテスト ペインに示されているように、このトピックが最初にトリガーされると、ユーザーに「お名前は?」と尋ねます。値を 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という名前を付けて、元のトピックへ値を返すを選択します。
トピックを保存します。
返される変数の宛先トピックを設定する
変数をトピックに返す場合、宛先トピックはリダイレクトを行っているトピックのことで、他のトピックから値を受け取るトピックです。 この例では、「グリーティング」です。
宛先のトピックに移動します。
ソース トピックで選択した変数は、リダイレクト ノードに出力変数として表示されます。
トピックを保存します。
.png)
.png)
.png)
.png)
