Como tornar um documento OpenAPI eficaz na expansão do Copilot

Os plug-ins permitem Microsoft Copilot trabalhar com serviços Web e obter informações em tempo real. O Copilot utiliza estas informações para expandir as suas competências. Com um plug-in, um utilizador pode trazer dados em tempo real do sistema de linha de negócio (LOB) para o Copilot.

Um plug-in é composto por um serviço de API, a descrição openAPI e um ficheiro de manifesto. O manifesto de plug-in informa o Copilot sobre as capacidades da API. O manifesto de plug-in inclui uma descrição openAPI para o serviço de API. A descrição de OpenAPI é importante porque descreve a Copilot como ligar à API. Para obter um desempenho ideal do plug-in com o Copilot, forneça uma descrição clara e significativa da OpenAPI. Este documento explica os elementos que tornam uma descrição openAPI eficaz para um plug-in que expande o Copilot.

Aqui, presumimos que tem uma API e uma descrição de OpenAPI para a mesma.

Validação OpenAPI: um bom primeiro passo é verificar se a descrição de OpenAPI segue as regras da Especificação openAPI. Pode utilizar Hidi, uma ferramenta de linha de comandos que pode validar descrições openAPI entre outros casos de utilização ou qualquer outra ferramenta de eleição. Uma descrição de OpenAPI válida não só funciona bem com o Copilot, como também garante que a descrição openAPI pode funcionar com outras ferramentas.

A secção de informações: o campo de descrição é opcional na especificação OpenAPI, mas é essencial para uma descrição openAPI que se destina a expandir as competências do Copilot. O Copilot precisa do campo de descrição para saber o que a API faz e quando utilizar o plug-in. Ao gerar um manifesto de plug-in a partir de um documento OpenAPI, a descrição na secção de informações é utilizada como a descrição do manifesto de plug-in. Por conseguinte, é importante ter sempre um campo de descrição breve e claro. Por exemplo, eis uma secção de informações de uma loja de reparações Descrição de OpenAPI.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

IDs da Operação: Uma técnica útil para melhorar a usabilidade de uma descrição openAPI é adicionar um operationID para cada combinação de caminho da API e método HTTP oferecido pela API. Os IDs de operação são identificadores exclusivos para uma operação na API e são utilizados pelo Copilot para criar funções que são executadas ao responder ao pedido de um utilizador.

Além disso, adicione uma descrição significativa de cada operação suportada pela sua API. Depois de o Copilot optar por utilizar um plug-in com base no pedido do utilizador e na descrição do plug-in, procura nas descrições dos caminhos para determinar o ponto final a utilizar para satisfazer o pedido do utilizador.

Os IDs da operação são apresentados durante a depuração como funções para indicar as operações que o Copilot está a tentar executar. Eis um exemplo de um documento OpenAPI e um exemplo da saída do depurador correspondente:

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Saída do depurador:

Parâmetros: Se uma operação suportada pela API receber parâmetros, inclua os parâmetros na descrição openAPI. Inclua um campo de descrição para cada parâmetro para descrevê-lo brevemente e, se necessário, dar um exemplo da utilização do parâmetro. Os parâmetros são utilizados pelo Copilot para obter todas as informações necessárias do pedido de um utilizador para fazer um pedido à API.

Veja um exemplo:

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Respostas: Defina claramente todas as respostas possíveis para cada operação, incluindo respostas de êxito e de erro. Cada resposta tem de ter um código de status e uma descrição do que representa. A inclusão de exemplos de respostas ajuda a Copilot a compreender o que esperar da API.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error