View a markdown version of this page

Obiettivi dello schema OpenAPI - Amazon Bedrock AgentCore
Considerazioni e limitazioni principaliStrategia di autorizzazioneSpecificazione dello schema OpenAPI

Obiettivi dello schema OpenAPI

OpenAPI (precedentemente noto come Swagger) è uno standard ampiamente utilizzato per descrivere le API RESTful. Gateway supporta le specifiche OpenAPI 3.0 per la definizione degli obiettivi delle API.

Gli obiettivi OpenAPI collegano il gateway alle API REST definite utilizzando le specifiche OpenAPI. Il Gateway traduce le richieste MCP in entrata in richieste HTTP verso queste API e gestisce la formattazione delle risposte.

Esamina le considerazioni e le limitazioni principali, incluso il supporto delle funzionalità, per aiutarti a decidere se un target OpenAPI è applicabile al tuo caso d'uso. In tal caso, puoi creare uno schema che segua le specifiche e quindi impostare le autorizzazioni affinché il gateway possa accedere alla destinazione. Per ulteriori informazioni, scegli un argomento:

Considerazioni e limitazioni principali

Importante

La specifica OpenAPI deve includere operationId campi per tutte le operazioni che si desidera esporre come strumenti. L'OperationID viene utilizzato come nome dello strumento nell'interfaccia MCP.

Quando usi obiettivi OpenAPI, tieni presente i seguenti requisiti e limitazioni:

  • Sono supportate le versioni 3.0 e 3.1 di OpenAPI (Swagger 2.0 non è supportato)

  • Il file OpenAPI deve essere privo di errori semantici

  • L'attributo server deve avere un URL valido dell'endpoint effettivo

  • Solo application/json il tipo di contenuto è completamente supportato

  • Le funzionalità dello schema complesso come oneOf, anyOf e allOf non sono supportate

  • I serializzatori di parametri di percorso e i serializzatori di parametri per i parametri di query, header e cookie non sono supportati

  • Ogni LLM avrà dei vincoli. ToolSpec Se OpenAPI ha APIs/properties/object nomi non conformi ai ToolSpec rispettivi LLM downstream, il piano dati fallirà. Gli errori più comuni sono il nome della proprietà che supera la lunghezza consentita o il nome che contiene caratteri non supportati.

Per ottenere i migliori risultati con gli obiettivi OpenAPI:

  • Includi sempre OperationID in tutte le operazioni

  • Utilizzate strutture parametriche semplici anziché serializzazioni complesse

  • Implementa l'autenticazione e l'autorizzazione al di fuori delle specifiche

  • Utilizza solo i tipi di supporti supportati per la massima compatibilità

Procedure consigliate di sicurezza per i parametri URL

avvertimento

Quando definisci gli URL dei server nelle tue specifiche OpenAPI, evita di utilizzare modelli di parametri URL eccessivamente permissivi che potrebbero esporre il tuo gateway a rischi per la sicurezza.

I parametri URL nelle definizioni dei server OpenAPI consentono la configurazione dinamica degli endpoint. Tuttavia, alcuni modelli possono introdurre vulnerabilità di sicurezza se non adeguatamente vincolati. In particolare, evita di utilizzare modelli di dominio completamente dinamici come:

  • https://{yourDomain}/- Consente la sostituzione arbitraria del dominio

  • https://{subdomain}.{env}.{domain}.com- Segnaposto multipli non vincolati

  • https://{host}/api/- Parametro host senza restrizioni

Questi modelli possono essere potenzialmente sfruttati per:

  • Reindirizzare le richieste verso endpoint non intenzionali o dannosi

  • Accedi alle risorse di rete interne (Request Forgery) Server-Side

  • Efiltra credenziali o dati sensibili

Pratiche consigliate:

  • Utilizza URL statici completamente qualificati quando possibile: https://api.example.com/v1

  • Limita i parametri ai sottodomini all'interno del tuo dominio controllato e implementa la convalida nell'applicazione

  • Evitate di utilizzare parametri che consentano la sostituzione arbitraria del dominio o dell'host

  • Implementa una convalida aggiuntiva nella tua API per verificare che i valori dei parametri di runtime corrispondano ai modelli previsti

AgentCore Gateway convalida automaticamente i parametri della regione e blocca le richieste verso intervalli IP privati.

Esempio di configurazione URL sicura del server:

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

Se sono necessari parametri dinamici, utilizza domini completamente qualificati con segnaposto e restrizioni enumerative minime:

{
  "servers": [
    {
      "url": "https://{tenant}.api.example.com/v1",
      "variables": {
        "tenant": {
          "default": "default-tenant",
          "description": "Customer tenant identifier",
          "enum": ["tenant1", "tenant2", "tenant3"]
        }
      }
    }
  ]
}

Questo approccio limita i parametri URL a sottodomini specifici all'interno del dominio controllato, pur mantenendo la flessibilità per le implementazioni multi-tenant. L'uso delle restrizioni enum previene i valori arbitrari e aiuta a proteggere dagli attacchi SSRF limitando i parametri a valori predefiniti e sicuri. Inoltre, convalidate sempre i valori dei tenant nella logica dell'applicazione.

Per prendere in considerazione l'utilizzo di obiettivi dello schema OpenAPI con AgentCore Gateway, consulta la seguente tabella di supporto delle funzionalità.

Supporto delle funzionalità OpenAPI

La tabella seguente descrive le funzionalità di OpenAPI supportate e non supportate da Gateway:

Caratteristiche supportate Caratteristiche non supportate

Definizioni dello schema Tipi di dati di base (stringa, numero, numero intero, booleano, array, oggetto) Convalida dei campi obbligatoria Strutture a oggetti annidate Definizioni di array con specifiche degli elementi

Composizione dello schema Specifiche OneOf AnyOf specifiche Tutte le specifiche

Metodi HTTP Metodi HTTP standard (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

Schemi di sicurezza Schemi di sicurezza a livello di specifica OpenAPI (l'autenticazione deve essere configurata utilizzando la configurazione di autorizzazione in uscita del Gateway)

Tipi di file multimediali -data -www-form-urlencoded application/json application/xml multipart/form application/x

Tipi di file multimediali personalizzati oltre all'elenco supportato Tipi di file multimediali binari

Parametri del percorso Definizioni semplici dei parametri di percorso (esempio: /users/ {userId})

Serializzazione dei parametri Serializzatori di parametri di percorso complessi (esempio:/users { ;id\*} { ?metadata}) Interroga gli array di parametri con serializzazione complessa Serializzatori dei parametri di intestazione Serializzatori dei parametri dei cookie

Parametri di interrogazione Definizioni di base dei parametri di interrogazione Tipi semplici di stringhe, numeri e booleani

Callback e webhook Operazioni di callback Definizioni Webhook

Request/Response Corpi di richiesta e risposta JSON Corpi di richiesta e risposta XML Codici di stato HTTP standard (200, 201, 400, 404, 500, ecc.)

Collegamenti Collegamenti tra operazioni

Strategia di autorizzazione

I seguenti tipi di autorizzazione in uscita sono supportati per i target OpenAPI:

  • Nessuna autorizzazione: il gateway richiama il target OpenAPI senza autorizzazione preconfigurata. Questo approccio non è consigliato.

  • OAuth: il gateway supporta sia OAuth a due vie (tipo di concessione Client Credentials) che OAuth a tre vie (tipo di concessione del codice di autorizzazione). Puoi configurare il provider di autorizzazione in Amazon Bedrock AgentCore Identity nello stesso account e nella stessa regione del gateway.

  • Chiave API: il gateway utilizza un provider di credenziali di chiave API per l'autenticazione con il target OpenAPI. Puoi configurare il provider di chiavi API in Amazon Bedrock AgentCore Identity nello stesso account e nella stessa regione del gateway.

  • IAM (AWS Signature Version 4 (Sig V4)): il gateway firma le richieste al target OpenAPI utilizzando SigV4 con le credenziali del ruolo del servizio gateway. Si configura un IamCredentialProvider con un nome di servizio richiesto per la firma SigV4 e una regione opzionale (l'impostazione predefinita è la regione del gateway).

Importante

L'autorizzazione in uscita IAM (SigV4) richiede che il target OpenAPI sia ospitato dietro un AWS servizio che supporta nativamente l'autenticazione IAM. Il gateway firma le richieste in uscita con SigV4 ma non modifica la configurazione di autenticazione sulla destinazione. Il servizio di destinazione deve essere in grado di verificare le firme SigV4.

I seguenti AWS servizi supportano nativamente l'autenticazione IAM e sono compatibili con l'autorizzazione in uscita IAM per i target OpenAPI:

  • Gateway Amazon API

  • URL delle funzioni Lambda

  • Amazon Bedrock AgentCore Gateway

I servizi che non verificano nativamente le firme SigV4, come Application Load Balancer o gli endpoint diretti di Amazon EC2, non sono compatibili con l'autorizzazione in uscita IAM. Se il tuo target OpenAPI è ospitato dietro uno di questi servizi, usa invece OAuth o l'autorizzazione della chiave API.

Per ulteriori informazioni sulla configurazione dell'autorizzazione in uscita, consulta Configurare l'autorizzazione in uscita per il gateway.

Specificazione dello schema OpenAPI

La specifica OpenAPI definisce l'API REST che il gateway esporrà. Fai riferimento alle seguenti risorse quando configuri la tua specifica OpenAPI:

Dopo aver definito lo schema OpenAPI, puoi eseguire una delle seguenti operazioni:

  • Caricalo in un bucket Amazon S3 e fai riferimento alla posizione S3 quando aggiungi la destinazione al gateway.

  • Incolla la definizione in linea quando aggiungi il target al gateway.

Espandi una sezione per vedere esempi di specifiche OpenAPI supportate e non supportate:

Di seguito è riportato un esempio di una specifica OpenAPI supportata

Esempio di una specifica OpenAPI supportata:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}

Di seguito viene mostrato un altro esempio di una specifica OpenAPI supportata.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}

Di seguito viene mostrato un esempio di schema non supportato con OneOf:

{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}