定義 OpenAPI Amazon 基岩中代理程式動作群組的結構描述 - Amazon Bedrock
範例API綱要

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

定義 OpenAPI Amazon 基岩中代理程式動作群組的結構描述

在 Amazon Bdrock 中建立動作群組時，必須定義代理程式需要從使用者呼叫的參數。您也可以定義代理程式可以使用這些參數呼叫的API作業。若要定義API作業，請建立 OpenAPI 結構描述JSON或YAML格式。您可以建立 OpenAPI 結構描述檔案並將其上傳到亞馬遜簡單儲存服務 (Amazon S3)。或者，您可以使用 OpenAPI 控制台中的文本編輯器，這將驗證您的模式。建立代理程式之後，您可以在將動作群組新增至代理程式或編輯現有動作群組時使用文字編輯器。如需詳細資訊，請參閱修改代理程式。

代理程式會使用結構描述來判斷需要呼叫的API作業，以及提出要API求所需的參數。然後，這些詳細資料會透過您定義的 Lambda 函數傳送，以執行動作，或在回應代理程式叫用時傳回。

如需API結構定義的詳細資訊，請參閱下列資源：

以下是一個的一般格式 OpenAPI 動作群組的結構描述。

{
    "openapi": "3.0.0",
    "paths": {
        "/path": {
            "method": {
                "description": "string",
                "operationId": "string",
                "parameters": [ ... ],
                "requestBody": { ... },
                "responses": { ... }
                "x-requireConfirmation": ENABLED | DISABLED
           }
       }
    }
}

下列清單說明 OpenAPI 結構描述

  • openapi— (必填) 的版本 OpenAPI 正在使用。此值必須是動"3.0.0"作群組才能運作。

  • paths— (必要) 包含個別端點的相對路徑。每個路徑都必須以正斜線 (/) 開頭。

  • method— (必要) 定義要使用的方法。

  • x-requireConfirmation— (選擇性) 指定在呼叫動作之前是否需要使用者確認。啟用此欄位可在呼叫動作前要求使用者確認。在呼叫動作之前要求使用者確認可能會保護您的應用程式不會因為惡意提示注入而採取動作。根據預設，使用者確認是DISABLED否未指定此欄位。

每個方法最低限度都需要下列欄位：

  • description— 作API業的描述。使用此欄位可通知代理程式何時呼叫此API作業以及作業的作業。

  • responses— 包含代理程式在回應中傳API回的屬性。代理程式會使用回應屬性來建構提示、準確處理API呼叫的結果，以及決定執行工作的正確步驟集。代理程式可以使用一項作業的回應值作為協調流程中後續步驟的輸入。

下列兩個物件中的欄位為您的代理提供更多資訊，使他們能有效利用您的動作群組。對於每個字段，將字required段的值設置為（true如果需要），如false果可選，則為。

  • parameters— 包含可納入請求中之參數的相關資訊。

  • requestBody— 包含操作請求內文中的欄位。請勿在 GET 和 DELETE 方法中包含此欄位。

若要瞭解有關結構的更多資訊，請從下列標籤中選取。

responses
"responses": {
    "200": {
        "content": {
            "<media type>": {
                "schema": {
                    "properties": {
                        "<property>": {
                            "type": "string",
                            "description": "string"
                        },
                        ...
                    }
                }
            }
        },
    },
    ...
}

responses對象中的每個鍵都是一個響應代碼，它描述了響應的狀態。回應碼會對應至包含下列回應資訊的物件：

  • content- (每個回應都需要)回應的內容。

  • <media type> — 回應主體的格式。如需詳細資訊，請參閱上的媒體類型 Swagger 網站。

  • schema— (每種媒體類型都需要) 定義回應內文及其欄位的資料類型。

  • properties— (如果結構描述中存在 items 則為必要) 您的代理會使用您在結構描述中定義的內容來決定傳回給使用者以完成任務所需的資訊。每個屬性包含下列欄位：

    • type— (每個屬性都需要) 回應欄位的資料類型。

    • description— (選用) 描述屬性。代理程式可以使用此資訊來判斷傳回給使用者所需的資訊。

parameters
"parameters": [
    {
        "name": "string",
        "description": "string",
        "required": boolean,
        "schema": {
            ...
        }
    },
    ...
]

您的代理程式會使用下列欄位來決定必須從使用者取得哪些資訊，才能執行動作群組的需求。

  • name— (必要) 參數的名稱。

  • description— (必要) 參數的描述。使用此欄位可協助代理了解如何從代理使用者取得此參數，或判斷其已具有先前動作或使用者向代理要求所產生的該參數值。

  • required— (選擇性) API 請求是否需要參數。使用此欄位可向代理程式指示每次呼叫是否需要此參數，或是否為選用參數。

  • schema— (選用) 輸入和輸出資料類型的定義。如需詳細資訊，請參閱上的資料模型 (結構描述) Swagger 網站。

requestBody

以下是一個requestBody字段的一般結構：

"requestBody": {
    "required": boolean,
    "content": {
        "<media type>": {
            "schema": {
                "properties": {
                    "<property>": {
                        "type": "string",
                        "description": "string"
                    },
                    ...
                }
            }
        }
    }
}

下列清單說明每個欄位：

  • required— (選擇性) 要求是否需要要API求主體。

  • content— (必要) 請求內文的內容。

  • <media type> — (選擇性) 要求主體的格式。如需詳細資訊，請參閱上的媒體類型 Swagger 網站。

  • schema— (選用) 定義請求內文及其欄位的資料類型。

  • properties— (選擇性) 您的代理程式會使用您在結構描述中定義的內容，判斷必須從使用者取得哪些資訊才能API提出要求。每個屬性包含下列欄位：

    • type— (選用) 請求欄位的資料類型。

    • description— (選用) 描述屬性。代理可以使用此資訊來判斷需傳回給終端使用者的資訊。

若要瞭解如何新增 OpenAPI 您在建立動作群組時建立的結構描述，請參閱在 Amazon 基岩中將動作群組新增至您的代理程式。

範例API綱要

下面的實例提供了一個簡單的 OpenAPI YAML格式的模式，以攝氏為單位獲取給定位置的天氣。

openapi: 3.0.0
info:
  title: GetWeather API
  version: 1.0.0
  description: gets weather
paths:
  /getWeather/{location}/:
    get:
      summary: gets weather in Celsius
      description: gets weather in Celsius
      operationId: getWeather
      parameters:
        - name: location
          in: path
          description: location name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: weather in Celsius
          content:
            application/json:
              schema:
                type: string

下列範例API結構描述定義了一組協助處理保險理賠的API作業。三APIs個定義如下：

  • getAllOpenClaims-您的代理可以使用該description字段來確定如果需要打開聲明列表，它應該調用此API操作。properties 在 responses 中指定傳回 ID 和保單持有人和理賠的狀態。代理程式會將此資訊傳回給代理程式使用者，或使用部分或全部回應作為後續API呼叫的輸入。

  • identifyMissingDocuments— 您的代理人可以使用該description字段來確定它應該調用此API操作，如果缺少的文件必須被識別為保險索賠. name、description 和 required 欄位會告訴代理，必須向客戶取得未結索賠的唯一識別碼。properties在responses指定返回未結IDs保險索賠的。代理程式會將此資訊傳回給最終使用者，或使用部分或全部回應作為後續API呼叫的輸入。

  • sendReminders— 您的代理可以使用該description字段來確定如果需要向客戶發送提醒，它應該調用此API操作。例如，有關未結索賠的待處理文件的提醒。properties在requestBody告訴代理人，它必須找到索賠IDs和待處理的文件。properties中的responses指定以傳回提醒的 ID 及其狀態。代理程式會將此資訊傳回給最終使用者，或使用部分或全部回應作為後續API呼叫的輸入。

{
    "openapi": "3.0.0",
    "info": {
        "title": "Insurance Claims Automation API",
        "version": "1.0.0",
        "description": "APIs for managing insurance claims by pulling a list of open claims, identifying outstanding paperwork for each claim, and sending reminders to policy holders."
    },
    "paths": {
        "/claims": {
            "get": {
                "summary": "Get a list of all open claims",
                "description": "Get the list of all open insurance claims. Return all the open claimIds.",
                "operationId": "getAllOpenClaims",
                "responses": {
                    "200": {
                        "description": "Gets the list of all open insurance claims for policy holders",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "claimId": {
                                                "type": "string",
                                                "description": "Unique ID of the claim."
                                            },
                                            "policyHolderId": {
                                                "type": "string",
                                                "description": "Unique ID of the policy holder who has filed the claim."
                                            },
                                            "claimStatus": {
                                                "type": "string",
                                                "description": "The status of the claim. Claim can be in Open or Closed state"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/claims/{claimId}/identify-missing-documents": {
            "get": {
                "summary": "Identify missing documents for a specific claim",
                "description": "Get the list of pending documents that need to be uploaded by policy holder before the claim can be processed. The API takes in only one claim id and returns the list of documents that are pending to be uploaded by policy holder for that claim. This API should be called for each claim id",
                "operationId": "identifyMissingDocuments",
                "parameters": [{
                    "name": "claimId",
                    "in": "path",
                    "description": "Unique ID of the open insurance claim",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }],
                "responses": {
                    "200": {
                        "description": "List of documents that are pending to be uploaded by policy holder for insurance claim",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "pendingDocuments": {
                                            "type": "string",
                                            "description": "The list of pending documents for the claim."
                                        }
                                    }
                                }
                            }
                        }

                    }
                }
            }
        },
        "/send-reminders": {
            "post": {
                "summary": "API to send reminder to the customer about pending documents for open claim",
                "description": "Send reminder to the customer about pending documents for open claim. The API takes in only one claim id and its pending documents at a time, sends the reminder and returns the tracking details for the reminder. This API should be called for each claim id you want to send reminders for.",
                "operationId": "sendReminders",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "claimId": {
                                        "type": "string",
                                        "description": "Unique ID of open claims to send reminders for."
                                    },
                                    "pendingDocuments": {
                                        "type": "string",
                                        "description": "The list of pending documents for the claim."
                                    }
                                },
                                "required": [
                                    "claimId",
                                    "pendingDocuments"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Reminders sent successfully",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "sendReminderTrackingId": {
                                            "type": "string",
                                            "description": "Unique Id to track the status of the send reminder Call"
                                        },
                                        "sendReminderStatus": {
                                            "type": "string",
                                            "description": "Status of send reminder notifications"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request. One or more required fields are missing or invalid."
                    }
                }
            }
        }
    }
}

如需更多範例 OpenAPI 結構描述，請參閱API網站上的https://github.com/OAI/開放規格/樹/主/示例 /V3.0。 GitHub