Pedidos de confirmação para plug-ins de API para Microsoft 365 Copilot

Por predefinição, Microsoft 365 Copilot pede ao utilizador para confirmar o envio de dados para um plug-in antes de os enviar para evitar consequências indesejadas em sistemas externos. O utilizador consegue ver os dados a enviar e é-lhe dada a opção de permitir ou recusar. Para algumas operações de API, é dada aos utilizadores a opção de permitir sempre o envio de dados, o que impede futuros pedidos de confirmação para essa operação específica.

Normalmente, Microsoft 365 Copilot mostra ao utilizador a opção Permitir sempre para operações HTTP GET e não mostra a opção POST, PATCH, PUT e DELETE. Os programadores de plug-ins de API podem alterar este comportamento para operações individuais na sua API. Os programadores também podem personalizar o texto que o Copilot apresenta ao utilizador como parte do pedido de confirmação.

Comportamento do pedido de substituição

Os programadores podem controlar se Microsoft 365 Copilot mostra a opção Permitir sempre para uma operação específica ao adicionar a x-openai-isConsequential propriedade no documento OpenAPI para a respetiva API. Definir esta propriedade para true desativar a opção Permitir sempre e defini-la como ativada false . Regra regra, qualquer ação com efeitos colaterais no sistema externo deve ser marcada com true para garantir que o utilizador está no controlo e evitar consequências indesejadas para ações com efeitos colaterais no sistema externo.

Por exemplo, considere uma API que cria um lembrete: POST /reminders. Uma vez que se trata de uma operação POST, Microsoft 365 Copilot pede ao utilizador para confirmar sempre que esta API é utilizada e não dá ao utilizador a opção de permitir sempre esta operação.

Para ativar a opção Permitir sempre , adicione a x-openai-isConsequential propriedade definida como falso, conforme mostrado no exemplo seguinte.

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

Agora, imagine uma API relacionada que obtém lembretes existentes: GET /reminders. Uma vez que é um GET, Microsoft 365 Copilot mostra ao utilizador a opção Permitir sempre.

Este comportamento pode ser alterado ao adicionar x-openai-isConsequential o conjunto como verdadeiro.

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

Personalizar texto de confirmação

Os programadores podem especificar o texto de confirmação ao definir a body propriedade no objeto Confirmação no objeto Capacidades de função da função no manifesto do plug-in. O valor de body deve ser indicativo do que a função faz. Se esta propriedade não estiver presente no manifesto, é utilizada a description propriedade no objeto Função .

{
  "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?"
    }
  }
}

Localizar texto de confirmação

Pode configurar cadeias localizáveis para serem utilizadas como pedidos de confirmação. Os passos seguintes descrevem o processo.

Passo 1: Utilizar chaves de localização no manifesto de plug-in

No manifesto de plug-in (por exemplo, plugin.json), substitua as cadeias literais por chaves de localização com o formato:

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

Estas chaves (por exemplo, plugin_name e plugin_description,) têm de corresponder às entradas no ficheiro de localização e estar em conformidade com o regex ^[a-zA-Z_][a-zA-Z0-9_]*.

Passo 2: Criar ficheiros de localização

Crie os seus ficheiros de localização no formato JSON e inclua uma localizationKeys propriedade que mapeia cada chave para a respetiva cadeia traduzida, conforme mostrado no exemplo seguinte.

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

Pode criar vários ficheiros de localização para idiomas diferentes (por exemplo, en.json, fr.json, de.json) e referenciá-los na configuração do plug-in.

Passo 3: Adicionar localizationInfo ao Manifesto da Aplicação

Inclua uma secção localizationInfo no manifesto da aplicação que referencia os ficheiros de localização. Por exemplo,

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

Conteúdo relacionado

Plug-ins de API para Microsoft 365 Copilot