Microsoft Copilot Studio は、Power Platform API を介したエージェントの検査アクションなど ボットのセキュリティとコンプライアンスを管理するための信頼性の高いツール を管理者に提供します。
エージェントの検査は、Copilot Studio の広範なセキュリティ フレームワークの一部であり、Copilot Studio の全体的なセキュリティ アプローチと連携して機能します。
たとえば、データ損失防止 (DLP) ポリシーに違反 しているボットや コンプライアンス ドキュメントがない ボットは、監査、ランタイム保護、またはその他の管理者レポートまたは通知の一部としてフラグを設定できます。 その後、管理者は検査 API を使用して、セキュリティとコンプライアンスの問題を調査および修復しながら、非準拠エージェントを隔離できます。
検査されたエージェントは、エージェント ユーザー (および Copilot Studio のエージェント作成者) には引き続き表示されますが、エージェントと対話したり使用したりすることはできません。
重要
以前の powervirtualgents 名前空間は非推奨となり、2025 年末までに削除される予定です。
この記事に示すように、API 呼び出しで copilotstudio 名前空間を使用します。
前提条件
- Power Platform テナント管理者か、Power Platform Administrator または Dynamics 365 サービス管理者である必要があります。
- ターゲット エージェントのボット ID と環境 ID があります。
- API を使用するサービスまたはユーザーの認証トークンがあります。
- 認証 URL の暗黙的なフローを使用して、Microsoft Entra ID OAuth2 経由で認証されます:
https://login.microsoftonline.com/common/oauth2/authorize?resource=https://api.powerplatform.com。
エージェント検査管理の API 操作
Copilot Studio では、Power Platform API の一部として、エージェント検査を管理するための 3 つの主要な REST API 操作がサポートされています。
Power Platform API の使用方法と使用タイミングの詳細については、以下を参照してください:
- Power Platform API と SDK: UX 優先から API 優先まで (ブログ) (Power Platform 開発者ブログ)
- プログラミングと拡張性の概要 (Power Platform のドキュメント)
- Power Platform API の概要 (プレビュー) (Power Platform のドキュメント)
この記事では、Power Platform API リファレンス ドキュメントにも定義 されている、 使用可能な操作について説明します。
重要
copilotstudio 名前空間は、Copilot Studio 関連の API 操作に使用する必要があります。
以前の powervirtualgents 名前空間は非推奨となり、2025 年末までに削除される予定です。
powervirtualagents 名前空間を以前に使用したことがある場合は、copilotstudio 名前空間を使用するように API 呼び出しを更新して、継続的な機能を確保します。
エージェントの検査状態を取得する
- エンドポイント:
GET https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/GetBotQuarantineStatus?api-version=1。 - 目的: エージェントの現在の検査状態を取得します。
- 応答: ブール値の
isBotQuarantinedとlastUpdateTimeUtcを返します。
パラメーターの要件と応答コードについては、検査状態に関する API リファレンス ドキュメント を参照してください。
エージェントを検査済みとして設定する
- エンドポイント:
POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/SetAsQuarantined?api-version=1。 - 目的: エージェントを検査済みとしてマークし、その利用可能性と対話を制限します。
- 応答: 検査状態の更新を確認します。
パラメーターの要件と応答コードについては、エージェントの検査に関する API リファレンス ドキュメント を参照してください。
エージェントを未検査として設定する
- エンドポイント:
POST https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/botQuarantine/SetAsUnquarantined?api-version=1。 - 目的: 危険評価と対策の後にエージェントを検査から削除します。
- 応答: 検査状態の更新を確認します。
パラメーターの要件と応答コードについては、エージェントの未検査に関する API リファレンス ドキュメント を参照してください。