変数の使用

変数は 4 つのレベル、またはスコープで存在できます:

• トピック 変数は、作成されたトピック内でのみ使用できます。 このスコープが、作成された変数の既定値です。
• グローバル変数 はすべてのトピックで使用できます。 トピック変数のスコープを変更し、グローバル変数にすることができます。
• システム変数 は副操縦士によって自動的に作成されます。 それらは、会話またはユーザーについてより多くのコンテキスト情報を提供します。 すべてのトピックで使用可能です。
• トリガー 変数 は Power Platform で作成され、 Copilot Studioで読み取り専用になります。 パラメーターのキーと値が格納され、Copilot Studio を含む他のさまざまなアプリケーション オブジェクトの入力として機能します。 消費オブジェクトからパラメーターを分離すると、同じ環境内で、または他の環境にソリューションを移行するときに値を変更できます。 代替方法は、ハードコーディングされたパラメーター値を、それらを使用するコンポーネント内に残すことです。

変数の型

変数は基本タイプと関連付けられます。 型は、変数が含むことのできる値や、論理式を構成する際に使用できる演算子を決定します。

変数の型は、値が最初に割り当てられるときに設定されます。 その後、変数の型は固定され、他の型の値を割り当てることはできなくなります。 たとえば、開始値 1 の変数には 数値 型が割り当てられます。 これを String value "apples" に割り当てようとすると、エラーが発生します。

副操縦士をテストしているときに、変数が一時的にタイプ 不明として表示される場合があります。 不明の変数はまだ値が割り当てられていない場合を指します。

変数の順序は、作成キャンバスの上から下に決定されます。 オーサリング キャンバスの上部にあるノードは、下部にあるノードよりも先に考慮されます。

条件ノードで分岐を作成するとき、ブランチは左から右に並べられます。 左端のブランチのノードは、右端のブランチのノードよりも先に考慮されます。

エンティティ

Copilot Studio は、エンティティ を使用して、ユーザーの応答から特定の種類の情報を識別します。 識別された情報は、情報に適した型の変数に保存されます。 次の表は、事前構築されたエンティティに関連付けられている変数の基本タイプを示しています。

変数を作成する

質問 ノードなど、出力として変数を選択するよう求めるノードは、適切な型の出力変数を自動で作成します。

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

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

変数名を変更する

変数には、作成する時に自動的に名前が付けられます。 ベスト プラクティスは、変数にわかりやすい名前を付けて、コパイロットを管理する必要がある他のユーザーに目的を明確にすることです。

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

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

変数を設定する

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

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

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

   

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

   

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

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

リテラル値の使用

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

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

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

変数ペイン

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

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

変数プロパティ ペイン

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

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

環境変数

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

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

Copilot Studio の環境変数の型は、以下のように PowerApps のデータ型にマッピングされます:

Copilot Studio では環境変数を作成したり編集したりすることはできません。 環境変数を変更または設定するには、PowerApps ポータルを使用する必要があります。 Copilot Studio から 変数 ペインを使用して、環境変数に関する情報を確認できます。 変数 ペインには、ネイティブ作成エクスペリエンスへのリンクもあります。

Azure Key Vault シークレットの環境変数を使用する

環境変数は、キー コンテナー内のシークレットを参照できます。 これは、独自の考慮事項がある環境変数の特殊なケースです。

PowerApps ポータルでシークレットの環境変数を作成するには、そのキー コンテナーを構成する必要があります。

上記の構成に加え、Copilot Studio がこのキー コンテナーを読み取ることを許可するには、以下の操作を実行する必要があります:

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

2. 環境内のすべてのコパイロットにシークレットへのアクセスを許可するには、そのシークレットにタグ AllowedEnvironments を作成し、許可する環境 ID をカンマ区切りで追加します。

3. 環境から特定のコパイロットだけにこのキー コンテナーの使用を許可するには、タグ AllowedCopilots を作成し、コパイロット識別子を {envId}/{schemaName} の形式で記述します。 複数の値を指定する場合は、カンマで区切ってください。

文字数の上限に達しても、さらにコパイロットを追加する必要がある場合は、説明的で一意の名前 (例: AllowedCopilots2) を持つ別のタグを追加してください。

シークレット値はダイアログのランタイムに 5 分間キャッシュされます。 失敗した読み取りは 30 秒間キャッシュされます。

システム変数

すべてのコパイロットには、会話に関する追加情報を提供する組み込みシステム変数が用意されています。

すべてのシステム変数が一覧に表示されるわけではありません。 これら非表示のシステム変数にアクセスするには、Power Fx 式を使用する必要があります。

Power Fx 式でシステム変数を使用するには、変数名の前に System. を付ける必要があります。 たとえば、システム変数 User.DisplayName を数式に含めるには、次を参照します: System.User.DisplayName。

統合認証の変数 (既定)

コパイロットをマイクロソフトで認証するように構成した場合、以下の変数を使用できます。 この場合、Entra ID 認証が使用され、Teams と PowerApps チャンネルのみが許可されます。 これは、新しいコパイロットの既定値です。

詳細については、「 認証変数」を参照してください。

Generic OAuth 2による手動認証の変数

Generic OAuth 2サービス プロバイダーを使用するようにコパイロットを構成した場合、次の変数が使用可能になります。

Microsoft Entra ID による手動認証の変数

コパイロットで Microsoft Entra ID (旧称: Azure Active Directory) サービス プロバイダーを使用するように構成した場合、以下の変数を使用できます。

音声対応コパイロット用変数

以下の変数は、音声対応のコパイロットでのみ使用できます。

トピック間で変数を渡す

あるトピックを別のトピックにリダイレクトすると、元のトピックと宛先トピックの間で変数の値を渡すことができます。 トピック間で変数を渡すことは、後のトピックが必要とする情報がすでに収集されている場合に特に役立ちます。 ユーザーは、同じ質問に再度答える必要がないことを評価するでしょう。

他のトピックから値を受け取る

トピックが変数を (例えば、質問ノードで) 定義すると、コパイロットは変数の値を入力するようにユーザーに質問を行います。 前のトピックですでにコパイロットが値を取得している場合は、再度質問をする理由はありません。 このような場合、変数を他のトピックから値を受け取るに設定することができます。 別のトピックがこのトピックにリダイレクトされるとき、この変数に変数の値 (またはリテラル値) を渡して、質問をスキップすることができます。 ユーザーからコパイロットへの会話のエクスペリエンスはシームレスです。

この例では、「グリーティング」と「顧客と交渉する」の 2 つのトピックを使用します。 両方のトピックが顧客の名前を尋ねます。 ただし、「グリーティング」トピックが最初に実行される場合、「顧客と交渉する」トピックはその質問をスキップします。 代わりに、「グリーティング」トピックから渡された変数の値を使用します。

「顧客と交渉する」トピックのフローは次のとおりです。

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

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

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

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

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

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

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

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

   

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

   

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

   

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

値を元のトピックに戻す

トピックがリダイレクトされる場合や、質問をすることや他の方法で変数を取得する場合、変数は元のトピックに返すことができます。 変数も元のトピックの一部となり、他の変数と同様に使用することができます。 コパイロットが取得する情報がトピック全体で利用できるようにし、グローバル変数 の必要性を減らすことができます。

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

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

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

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

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

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

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

   

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

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

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

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

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

   

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

エンティティおよび変数型

Copilot Studio は、エンティティ を使用して、ユーザーの応答から特定の種類の情報を識別します。 変数型は、保存時に識別された情報に関連付けられます。 変数型はエンティティに似ています。

次の表に一覧表示されているように、各エンティティまたは変数型は基本的な型にマップされます。 基本型は、対応する変数を使用して論理式を作成するときに使用できる演算子を決定します。 また、入力パラメーターとして変数をフローにフィードまたはBot Framework スキルにフィードできるかどうかも決定します。

たとえば、ブール値 の基本型は、可能な値が True または False の演算子「次の値に等しい」にマップされます。 数値 の基本型は、「次の値に等しい」、「次の値より大きい」、「次の値以上」などの数値演算子を提供します。

変数を作成する

ボット作成キャンバスで質問ノードを追加します。 変数はノードに自動的に作成されます。

1. ボット の トピック ページ に移動し、変数を追加する トピック を開きます。

2. ノードの追加 (+) を選択して、質問するを選択します。

   

   ユーザーの応答を含む変数が自動的に作成されます。

   

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

既定では、質問ノードは複数選択式オプションで作成されます。 別の事前構築済みエンティティまたはカスタム エンティティを使用するには、ノードから識別する対象を選択します。

変数名を変更する

自動的に作成された変数には、既定の名前が付けられます。 変数名を変更するには変数名を選択し、新しい名前を入力して 完了 を選択します。

アクション ノードで変数を使用する

アクション ノードで変数を使用する際に、その基本型がフローまたは Bot Framework スキルに指定されたパラメーター型と一致する場合は、そのパラメータにフィードできます。 アクション ノードからの出力は、新しい変数を生成します。

アクション ノードでリテラル値を使用する

メニューから変数を選択する代わりに、アクション ノードの変数入力フィールドにリテラル値を入力できます。

値の解析ノード

値の解析ノードを使用すると、ある型の値を別の型の値に変換することができます。 トピックにノードを追加する場合は、「ノードの追加 (＋)」、「変数管理」、「値の解析」を選択します。

値の解析ノードを使用する主なシナリオは、生の JSON または型なし変数 (実行時まで値や構造がわからない、ChannelData など) を具象型に変換することに重点を置いています。

プロセスは、フローが呼び出されたときに開始され、フローが API を呼び出します。 API が計算結果を返します。 通常は、この応答を解析し、1 つ以上のプリミティブ変数を Copilot Studio に返す必要があります。 値の解析ノードを使用すると、API の結果全体を文字列として送信できます。

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

現在使用している文字列変数は、この新しいノードを使うことで、Power Fx の完全なインテリセンス対応で、Record 変数に変換することができます。 サンプル データを使用した例は、このプロセスを説明する際に役立ちます。

値の解析ノードの使用例

1. 値の解析ノードを追加し、解析する変数を選択します。

   

2. データ型を選択します。 この場合は「サンプルデータから」を選択します。

   

3. 以上で、「サンプル JSON からスキーマを取得」をクリックして JSON を提供できるようになりました。 これをクリックするとエディタが開き、例を貼り付けることができます。

   

4. 最後に、解析された値をどの変数に配置するかを指定します。 通常は、これに対して新しい変数を作成します。

   

   出力変数が正しい型であるレコードになったことに注意してください。

   

以上で、新しい変数を使用できるようになりました。 ここでは、Power Fx エディターで、さまざまなプロパティに対して完全なインテリセンスが得られることがわかります。

JSON 文字列の解析と同様に、値の解析ノードの主な用途は、実行時の UntypedObject の解析です。 最も一般的なのは、イベントを受信し、イベント値を解析する必要がある場合です。 あるいは、チャンネルによって実行時に異なる System.Activity.ChannelData プロパティを解析する場合もあります。

次の例では、イベントが Teams からのものである場合、Teams 開発者ドキュメントを使用して、受信イベントがどのようになるかの例を見つけ、このセクションで説明されているように、サンプル データから使用する必要があります。

トピック間で変数を渡す

他のトピックにリダイレクトする際に、目的のトピックの変数に値を渡したり、そこから変数を取得し直すことができます。 トピック間で変数を渡すことは、トピックが必要とする情報がすでにある場合に特に役立ちます。 ユーザーは、質問に再度答える必要がないことを評価するでしょう。 また、トピックをリファクターして再利用可能なコンポーネントに分割し、トピック間で変数を渡す場合にも役立ちます。

他のトピックから値を受け取る

トピックが (質問ノードなどで) 変数を定義すると、ボットは変数の値を入力するためにユーザーに質問を行います。 すでにボットが値を取得している場合は、再度質問をする理由はありません。 このような場合、変数を 他のトピックから値を受け取る ように定義することができます。 別のトピックがこのトピックにリダイレクトされると、この変数に変数 (または リテラル値) を渡して、質問をスキップできます。 ユーザーがボットと対話するエクスペリエンスはシームレスです。

他のトピックから値を受け取るには、その変数のプロパティを設定します:

1. 質問ノードで、他のトピックから値を受け取る変数を選択します。

2. 変数のプロパティ ペインにある トピック (限定されたスコープ) の下で、他のトピックから値を受け取る を選択します。

   

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

4. リダイレクト先のトピックに移動します。 別のトピックにリダイレクトする の手順に従い、正しいトピックにリダイレクトします。

5. 宛先のトピックにインプットを + 追加を選択します。

   

6. リダイレクトされたトピックで、変数を渡す変数を選択します。

   

7. 値の入力または選択 の下で、リダイレクトされたトピックに渡す、現在のトピックの変数を選択します。

   

   変数はリダイレクトされたノードに表示されます。

   

値を元のトピックに戻す

トピックが質問する場合や、他の方法でアクションから変数を取得する場合、変数はリダイレクトした元のトピックに返すことができます。

この場合、その変数も元のトピックの一部となり、他の変数と同様に使用することができます。 これにより、ボットが取得する情報がトピック全体で利用できるようにトピックを構築し、グローバル変数の必要性を減らすことができます。

変数を元のトピックに戻すには、その変数のプロパティを設定します:

1. 質問ノードで、他のトピックから値を受け取る変数を選択します。

2. 変数のプロパティ ペインにある トピック (限定されたスコープ) の下で、値を元のトピックに戻す を選択します。

   

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

4. リダイレクト先のトピックに移動します。 別のトピックにリダイレクトする の手順に従い、正しいトピックにリダイレクトします。

   リダイレクトされたトピックには、その変数が表示されます。 トピックで返された変数を使用します。

   

変数ペインを使用する

変数 ペインを使用して、複数の変数の受信状態や戻り状態を一度に選択します。

1. トピックのメニュー バーで 変数 を選択します。

   

2. トピック内の各変数について、トピック間で値を渡すか、受け取るか、またはその両方を行うかを選択します。

   

変数の入力にリテラル値を使用する

リテラル値と変数をトピックに渡すことができます。 リテラル値を渡す場合は、変数を選択するのではなく、入力として使用する値を入力します。