閱讀英文

共用方式為


建立您的自訂外掛程式

重要

本文中的部分資訊與發行前版本產品有關,在產品正式發行前可能會大幅度修改。 Microsoft 對此處提供的資訊,不提供任何明確或隱含的瑕疵擔保。

提示

如果您需要非 Microsoft 外掛程式的協助,請參閱其文件和技術支援。

建立新的外掛程式

根據系統管理員設定 Security Copilot 的方式,您可以採取下列步驟來建立新的外掛程式:

  1. 從支援的外掛程式清單建置外掛程式。

  2. 建立 YAML 或 JSON 外掛程式資訊清單檔案,其中描述外掛程式的相關中繼資料,以及叫用它的方式。

  3. 將外掛程式資訊清單發佈至 Security Copilot。

外掛程式需求

每個 Security Copilot 外掛程式都需要 YAML 或 JSON 格式的資訊清單檔案 (例如: plugin.yamlplugin.json) ,其中描述技能集的中繼資料以及叫用技能之方法。

資訊清單包含兩個必要的最上層索引鍵 DescriptorSkillGroups,每個都有子金鑰或值組,以及視技能格式而定所需的/選用欄位。

如需 OpenAI 外掛程式的相關資訊,請參閱 開始使用

描述項欄位摘要

欄位 類型 描述 必要項目
Name 字串 外掛程式的內部名稱。 不允許 / \ ? # @
DisplayName 字串 外掛程式的人類可讀取名稱。 建議
Description 字串 外掛程式的人類可讀取描述。
DescriptionDisplay 字串 如果未指定 [描述],則為外掛程式的替代人類可讀取描述。
Category 字串 注意: 此值目前會在自定外掛程式上傳流程期間強制執行 Plugin
Prerequisites 字串
Icon 字串 用來擷取 Skillset 主要圖示的 URL。 建議

SkillGroups 欄位摘要

包含技能群組的清單,包括 FormatSettingsSkills

欄位 類型 描述 必要項目
Format 字串 如需可用的選項,請參閱 格式 一節。
Settings 物件 如需物件結構,請參閱 設定 一節。 是,針對格式: APIDOTNETCONTAINER
Skills 物件 如需物件結構,請參閱 技能 一節。 是,針對格式: GPTDOTNETKQLLogicApp

格式 (SkillGroups 欄位)

Format 欄位的選項:

API
GPT
KQL

設定 (SkillGroups 欄位)

Settings 欄位的物件結構。

欄位 類型 描述 必要項目
OpenApiSpecUrl 字串 公用 OpenAPI 規格的 URL。
EndpointUrl 字串 公用端點的 URL。

技能 (SkillGroups 欄位)

Skills 欄位的物件結構。

欄位 類型 描述 必要項目
Description 字串 此技能的人類可讀取描述。 建議
DescriptionForModel 字串 用於技能選取範圍的技能詳細描述
Inputs 物件 NameDescriptionRequiredDefaultValue (選用) 物件的清單,供使用者輸入技能。
Settings 物件 根據技能 格式 的自定設定。

OpenAI 和安全性 Copilot 資訊清單之間的差異

遵循 ChatGPT 外掛程式文件 所建置的 OpenAI 外掛程式,通常會使用與 Security Copilot 資訊清單格式不同的資訊清單格式。 Security Copilot 支援這兩種格式。

OpenAI 外掛程式 資訊清單 會在上傳時轉譯為 Security Copilot 資訊清單。

注意

對應詳細資料,特別是有關記事中的限制,未來可能會變更。 目前,平台僅支援 OpenAPI 3.0 或 3.0.1 版中的外掛程式。

外掛程式欄位對應

外掛程式欄位 類型 描述項欄位 必要項目 附註
schema_version 字串 它是 OpenAI 資訊清單結構描述版本,例如 'v1'。 目前未使用。
name_for_model 字串 名稱 長度限制為 100 個字元。 技能集的內部名稱。 不允許 / \ ? #
name_for_human 字串 DisplayName 外掛程式的人類可讀取名稱。 長度限制為 40 個字元。
description_for_model 字串 描述 長度限制為 16,000 個字元。 搭配 LLM 使用的內部描述。
description_for_human 字串 DescriptionDisplay 外掛程式的人類可讀取描述。 長度限制為 200 個字元。
logo_url 字串 圖示 建議 用來擷取外掛程式主要圖示的 URL。
contact_email 字串 外掛程式的電子郵件連絡人。 目前未使用。
legal_info_url 字串 外掛程式資訊的連結。 目前未使用。
api 物件 如需物件結構,請參閱 外掛程式 API 一節
auth 物件 authorization_type 限制為 bearer。 針對不同驗證 type (如 none、oauth、api_key、aad、aad_delegated) 的支援所遵循的詳細資料。

外掛程式 (API 欄位)

api 欄位的物件結構

欄位 類型 描述 必要項目
type 字串 目前唯一支援的類型是 openapi
url 字串 連結至 API 的 OpenAPI 規格 文件。

外掛程式撰寫指導方針

外掛程式撰寫有許多考量事項。 本文件旨在擷取一些撰寫 Security Copilot 專用的外掛程式指導方針和最佳做法。

注意

當 Security Copilot 無法正確區分兩種不同的技能時,就會發生「技能衝突」。

  • 與其擁有可傳回相同回應類型但只會根據輸入而有所不同的多個技能;不如定義技能,這可接受多個輸入,然後在內部找出取得資料的方法。

    • 例如,擁有採用裝置識別碼、使用者識別碼或使用者名稱的單一的 GetDevices 技能,而不是個別的 GetDeviceByIdGetDeviceByUserIdGetDeviceByUserName
  • Security Copilot 支援 DescriptionDescriptionForModel 欄位。 Description 用於 UX (和技能選取範圍,如果 DescriptionForModel 未設定) 且 DescriptionForModel 僅用於技能選取範圍。

    • 例如,假設我們有技能 GetSslCertsByHostname,其描述為「傳回與主機名稱相關聯的 SSL 憑證」。 詳細的 descriptionForModel 可能是「擷取 SSL 憑證 (也稱為 TLS 憑證) 作為 DNS 主機名稱或網域名稱。 傳回 SSL 憑證清單以及像是發行者、主旨、序號、sha1 和日期等憑證詳詳細資料」。
  • 對於具備合理知識但可能不是問題領域中專業人員的人員來說,技能描述應該是冗長且以慣用語表達的內容。 它不僅應該描述技能的用途,也應該描述為何想要使用它的原因。

    • 例如,良好的描述是「取得 IP 位址的信譽資訊。 允許使用者判斷 IP 位址是否具風險。」  

另請參閱