建立有效的 OpenAPI 描述以延伸 Microsoft 365 Copilot

API 外掛程式可讓 Microsoft 365 Copilot 代理程式與 Web 服務互動並存取即時資訊。 API 外掛程式可讓使用者透過自然語言命令與Copilot Chat內代理程式 (LOB) 系統中的企業營運即時資料互動。

API 外掛程式是由 API 服務、其 OpenAPI 描述和資訊清單檔案所組成。 外掛程式資訊清單會通知 Copilot 協調器 API 的功能。 外掛程式資訊清單包含 API 服務的 OpenAPI 描述。 OpenAPI 描述很重要,因為它會向 Copilot 說明如何連線至 API。 若要使用 Copilot 獲得最佳外掛程式可探索性和效能,請提供清楚且有意義的 OpenAPI 描述。

本文說明讓 OpenAPI 描述對於擴充 Copilot 代理程式功能的外掛程式有效的元素。

OpenAPI 描述元素

本節說明 OpenAPI 描述的元素,以及如何針對 Copilot 代理程式進行最佳化。

OpenAPI 驗證:好的第一步是驗證您的 OpenAPI 描述是否遵循 OpenAPI 規範的規則。 您可以使用 Hidi(一種可以在其他用例中驗證 OpenAPI 描述的命令列工具)或任何其他選擇的工具。 有效的 OpenAPI 描述不僅可與 Copilot 搭配使用,也可確保您的 OpenAPI 描述可以與其他工具搭配使用。

資訊區段: 描述欄位在 OpenAPI 規格中是選擇性的,但對於旨在擴展 Copilot 技能的 OpenAPI 描述來說,這是必不可少的。 Copilot 需要描述欄位,才能知道 API 的功能以及何時使用外掛程式。 從 OpenAPI 文件產生外掛程式資訊清單時,資訊區段中的描述會做為外掛程式資訊清單的描述。 因此,請務必一律具有簡短明了的描述欄位。 例如,以下是維修店 OpenAPI 描述的資訊區段。

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

作業識別碼: 增強 OpenAPI 描述可用性的有用技術是為 API 提供的每個 API 路徑和 HTTP 方法組合新增一個 operationID 。 作業識別碼是 API 中作業的唯一識別碼,Copilot 使用它來建立回應使用者提示時要執行的函數。

此外,為您的 API 支援的每個作業新增有意義的描述。 在 Copilot 根據使用者的提示和外掛程式描述選擇使用外掛程式之後,它會搜尋路徑的描述,以決定要用來滿足使用者要求的端點。

作業識別碼會在偵錯期間顯示為函式,指出 Copilot 正在嘗試執行哪些作業。 以下是 OpenAPI 文件的範例,以及對應偵錯工具輸出的範例:

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

偵錯工具輸出:

偵錯工具的影像,顯示外掛程式的選取函數。

參數: 如果您的 API 支援的作業採用參數,請在 OpenAPI 描述中包含參數。 包含每個參數的描述欄位以簡要描述它,並在必要時提供參數用法範例。 Copilot 會使用參數,從使用者向 API 提出要求的提示中取得所有必要的資訊。

以下是範例:

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

回應: 明確定義每個作業的所有可能回應,包括成功和錯誤回應。 每個回應都必須有狀態代碼及其所代表內容的描述。 包含回應範例,有助於 Copilot 瞭解可從 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