在你的代理程式中加入 API 工具 (外掛)

重要事項

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

代理程式開發者經常需要發出 HTTP 請求，以建立完整的使用案例。

此範例示範如何建立一個代理，利用外掛與 API 工具連接至 REST API 服務，該服務 freeipapi.com提供 Geo-IP 查詢功能。

整體流程如下：

  1. 步驟 1：建立並發布定義 API 的 OpenAPI 規範

  2. 步驟 2：建立並上傳清單檔案至 Security Copilot

  3. 步驟 3：上傳使用該外掛的代理程式

  4. 步驟 4：發佈套件至 Security Store， (僅適用於合作夥伴代理)

    注意事項

    若想看使用 API 工具 (技能) 的清單 YAML 範例，請參見 「使用多工具建置代理」。 它會提供如何上傳代理、設定並執行已發佈在 Active agents 頁面的代理的說明。

步驟 1：建立並發布 OpenAPI 規範

以下章節將說明如何使用 API 外掛及 OpenAPI 規範來建立代理程式以進行地理位置查詢。

此範例整合了 Free IP REST API，用於執行 IP 位址地理定位查詢。 你必須將此規範公開到線上， (GitHub gist效果) 。 請參考以下範例來建立並架設您的規格。 關於認證的範例，請參見 Auth types。

openapi: 3.0.0

info:
    title: Free IP API
    description: A free IP lookup API
    version: "v1"

servers:
    - url: https://freeipapi.com/api/

paths:
    /json/{ipaddress}:
        get: 
            operationId: lookupIpAddressGeolocation
            summary: Lookup IP Address Geolocation information
            parameters:
                - in: path
                  name: ipaddress
                  schema:
                      type: string
                  required: true
                  description: The ip address to lookup
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/lookupIpAddressGeolocationResponse"

components:
    schemas:
        lookupIpAddressGeolocationResponse:
            type: object
            properties:
                ipVersion:
                    type: integer
                    description: The IP address version
                ipAddress:
                    type: string
                    description: The IP address
                latitude:
                    type: number
                    description: The latutude
                longitude:
                    type: number
                    description: The longitude
                countryName:
                    type: string
                    description: The country
                zipCode:
                    type: string
                    description: The zip code
                cityName:
                    type: string
                    description: The city
                regionName:
                    type: string
                    description: The region
                continent:
                    type: string
                    description: The continent

步驟 2：建立並上傳 API 清單 (外掛)

  1. 建立一個名為 http_manifest.yaml 的工具格式 API的檔案。

        Descriptor:
      Name: DCA_SampleAPIPlugin
      DisplayName: TESTDCA_Free IP API
      Description: Skills for looking up geolocation information for an IP address using the Free IP API

    SkillGroups:
      - Format: API
        Settings:
          OpenApiSpecUrl: <Reference to your openapispec.yaml schema created in Step 1>
          EndpointUrl: https://sampleurl <The server endpoint that is hosting the API>

  2. 把 yaml 上傳到 Security Copilot。 上傳 YAML 的說明詳見「 建置代理清單」。

    注意事項

    你需要完成設定步驟，外掛才能在 自訂 區塊中顯示。 上傳的 YAML 或清單僅在 manifest YAML 有定義代理定義 (AgentDefinitions 且定義) 時，才會以代理形式發佈給 Active 代理。

  3. 你可以透過提示中「系統能力」來測試這個工具或外掛。

  4. 搜尋 lookupIpAddressGeolocation，這是 operationId 你在 第一步定義的 API 規範中的值。

    工具查詢在 Security Copilot 中的圖片

    執行該工具後的回應會顯示出來。

    Security Copilot 中工具執行回應的圖片

步驟 3：上傳使用 API 外掛的代理程式

現在，上傳使用 API 外掛的代理程式。

  1. 當你上傳代理時，請在「新增插件」畫面中選擇「此工作區中的任何人」。

  2. 將代理 YAML 上傳到 Security Copilot。

步驟 4：將套件發佈到 Security Store (可選)

此步驟僅適用於開發代理的合作夥伴，該代理必須發佈至 Security Store。

發布 API 清單至安全商店的重要考量：

  • 在將您的套件發佈到 Security Store 時，必須包含在 openapispec.yaml 套件中。

  • 必須 OpenApiSpecUrl 參考套件內的本地檔案路徑。

  • 這是 EndpointUrl OpenAPI 規範的公開託管端點。

  • 如果這些 URL ChildSkills 在 Open API 規範中被引用，請確保你的 OpenAPISpec 全域 URL 和本地的 OpenAPISpec yaml 都是最新的。

  • 必須 openapispec.yaml 與代理清單 yaml (http_manifest.yaml) 同一個資料夾，且必須遵循命名規則： openapispec_<number>.yaml。

  • Last updated on