针对 Microsoft 365 Copilot 的 API 插件的确认提示

默认情况下，Microsoft 365 Copilot 要求用户在发送插件之前确认将数据发送到插件，以防止外部系统中出现意外后果。 用户可以查看要发送的数据，并可以选择允许或拒绝。 对于某些 API作，会为用户提供始终允许发送数据的选项，这将阻止将来对该特定作的确认提示。

通常，Microsoft 365 Copilot 向用户显示 HTTP GET作的 “始终允许 ”选项，并且不显示 POST、PATCH、PUT 和 DELETE 选项。 API 插件开发人员可以在其 API 中更改单个作的此行为。 开发人员还可以自定义 Copilot 在确认提示中向用户显示的文本。

重写提示行为

开发人员可以通过在其 API 的 OpenAPI 文档中添加 x-openai-isConsequential 属性来控制 Microsoft 365 Copilot 是否显示特定作的“始终允许”选项。 将此属性设置为 true 将禁用 Always allow 选项，并将其设置为 false 启用它。 通常，外部系统中具有副作用的任何作都应标记为 true ，以确保用户处于控制状态，并防止外部系统中具有副作用的作产生意外后果。

例如，假设有一个 API 创建提醒： POST /reminders。 由于这是 POST作，Microsoft 365 Copilot 每次使用此 API 时都会要求用户确认，并且不会为用户提供始终允许此作的选项。

若要启用 “始终允许 ”选项，请将 x-openai-isConsequential 属性设置为 false，如以下示例所示。

post:
  x-openai-isConsequential: false
  summary: Create a new reminder
  description: Create a new budget with a specified name and due date
  operationId: CreateReminder
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Reminder'
    required: true

现在，假设有一个检索现有提醒的相关 API： GET /reminders。 由于它是 GET，因此 Microsoft 365 Copilot 向用户显示 “始终允许” 选项。

可以通过将 set 添加到 x-openai-isConsequential true 来更改此行为。

get:
  x-openai-isConsequential: true
  summary: Get existing reminders
  description: Gets a list of existing reminders
  operationId: GetReminders

自定义确认文本

开发人员可以通过在插件清单中函数的 Function 功能对象中的 Confirmation 对象中设置 body 属性来指定确认文本。 的值 body 应指示函数的作用。 如果清单中不存在此属性， description 则改用 Function 对象 中的 属性。

{
  "name": "GetBudgets",
  "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
  "capabilities": {
    "confirmation": {
      "type": "AdaptiveCard",
      "title": "Search budgets",
      "body": "Do you want to allow searching for budgets?"
    }
  }
}

本地化确认文本

可以将 可本地化字符串 配置为用作确认提示。 以下步骤介绍了该过程。

步骤 1：在插件清单中使用本地化密钥

例如，在插件清单 (plugin.json) ，使用 格式将文本字符串替换为本地化键：

    {
      "schema_version": "v2.3",
      "name_for_human": "[[plugin_name]]",
      "description_for_human": "[[plugin_description]]"
    }

例如， plugin_name 这些键 (， plugin_description) 必须与本地化文件中的条目匹配，并符合正则表达式 ^[a-zA-Z_][a-zA-Z0-9_]*。

步骤 2：创建本地化文件

创建 JSON 格式的本地化文件，并包含一个 localizationKeys 属性，该属性将每个键映射到其已翻译的字符串，如以下示例所示。

    {
  "localizationKeys": {
    "plugin_name": "Weather Assistant",
    "plugin_description": "Provides weather updates and forecasts."
      }
    }

可以为不同的语言创建多个本地化文件， (例如，en.json、fr.json、de.json) 并在插件配置中引用它们。

步骤 3：添加到 localizationInfo 应用清单

在应用清单中包含引用本地化文件的 localizationInfo 部分。 例如，

    "localizationInfo": {
      "defaultLanguageTag": "en",
      "defaultLanguageFile": "en.json",
      "additionalLanguages": [
        {
          "languageTag": "fr",
          "file": "fr.json"
        }
      ]
    }

相关内容

适用于 Microsoft 365 Copilot 的 API 插件