Le fasi dell'API REST di Amazon API Gateway come obiettivi

Un target API REST API Gateway collega il gateway a una fase dell'API REST. Il gateway traduce le richieste MCP in entrata in richieste HTTP all'API REST e gestisce la formattazione delle risposte. Quando aggiungi o aggiorni un target API Gateway, AgentCore Gateway chiama l'API di GetExportAPI Gateway per tuo conto.

È possibile specificare filtri e sostituzioni degli strumenti nella configurazione di destinazione. I filtri degli strumenti consentono di rendere disponibili combinazioni specifiche di percorsi di risorse e metodi HTTP come strumenti sul gateway. Questi filtri creano un elenco di strumenti consentiti che mostra solo le operazioni specificate come strumenti.

Puoi anche configurare la fase API REST di API Gateway come destinazione gateway dalla console API Gateway. Per ulteriori informazioni, consulta Aggiungere una fase a un AgentCore gateway nella documentazione di Amazon API Gateway.

Considerazioni e limitazioni principali

Quando utilizzi una fase API REST di API Gateway come destinazione, tieni presente i seguenti requisiti e limitazioni:

Configurazione dello strumento API Gateway

Quando aggiungi un'API REST di API Gateway come destinazione del gateway, devi fornire una configurazione dello strumento API Gateway. La configurazione dello strumento API Gateway definisce quali operazioni dell'API REST sono esposte come strumenti. Richiede un elenco di filtri degli strumenti per selezionare le operazioni da esporre e, facoltativamente, accetta sostituzioni degli strumenti per personalizzare i metadati degli strumenti come i nomi e le descrizioni degli strumenti.

Filtri degli strumenti

I filtri degli strumenti consentono di selezionare le operazioni dell'API REST utilizzando combinazioni di percorsi e metodi. Ogni filtro supporta due strategie di abbinamento dei percorsi:

Ogni filtro specifica sia un percorso che un elenco di metodi HTTP. Il filtro si risolve in combinazioni corrispondenti esistenti nell'API. Più filtri possono sovrapporsi e i duplicati vengono deduplicati automaticamente.

Sostituzioni degli strumenti

Per impostazione predefinita, il nome dello strumento MCP viene preso dalla combinazione operationId per ogni percorso e metodo che corrisponde ai filtri. Se non esiste una corrispondenza tra operationId i filtri, avrai bisogno di uno strumento sostitutivo corrispondente che fornisca un nome. Se mancano sia il operationId nome che quello dell'override, la convalida della creazione e degli aggiornamenti del target non verrà convalidata. Per ulteriori informazioni sui nomi degli strumenti in AgentCore Gateway, vedi Scopri come vengono denominati gli strumenti AgentCore Gateway.

Le sostituzioni degli strumenti sono facoltative. Consentono di personalizzare il nome o la descrizione dello strumento per operazioni specifiche dopo il filtraggio. Ogni override deve specificare un percorso esplicito e un singolo metodo HTTP. I caratteri jolly non sono supportati. L'override deve corrispondere a un'operazione esistente nell'API e deve corrispondere a una delle operazioni risolte dai filtri. Non puoi sovrascrivere le operazioni che non sono state selezionate. Se riscontri errori nelle importazioni da operazioni senza un, operationId puoi invece utilizzare uno strumento override.

Esempi di configurazioni dello strumento API Gateway

Il seguente esempio di configurazioni dello strumento API Gateway mostra come utilizzare filtri e sostituzioni. Tutti gli esempi utilizzano un'API con i seguenti percorsi e metodi:

/pets/{petId} - GET
/pets/{petId}  - POST
/pets/{petId}  - OPTIONS
/pets          - GET
/pets          - OPTIONS
/              - GET

Percorso delle wild card ed elenco dei metodi

Configurazione dello strumento:

{
  "filterPath": "/pets/*",
  "methods": ["GET", "POST"]
}

Risultato

Percorso esplicito ed elenco di metodi

Configurazione dello strumento:

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}

Risultato

Percorso esplicito ed elenco dei metodi espliciti (i più specifici)

Configurazione dello strumento:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    }
  ]
}

Risultato

Mescola e abbina un percorso esplicito e con caratteri jolly:

Configurazione dello strumento:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

Risultato

Filtro utensile e sostituzione degli utensili

È possibile fornire un filtro per gli strumenti e aggiungere un'alternativa. L'override specifica un percorso di risorsa nell'API REST, ad esempio /pets, e un metodo HTTP da esporre per il percorso specificato. L'override deve corrispondere esplicitamente a un percorso esistente nell'API REST.

Configurazione dello strumento

{
  "toolFilters": [
    {
      "filterPath": "/pets/*",
      "methods": ["GET", "POST"]
    },
    {
      "filterPath": "/",
      "methods": ["GET"]
    }
  ],
  "toolOverrides": [
    {
      "path": "/pets/{petId}",
      "method": "GET",
      "name": "GetPetById",
      "description": "Retrieve a specific pet by its ID"
    }
  ]
}

Risultato

Esportazione API Gateway

Per configurare la destinazione API Gateway, AgentCore Gateway richiama l'GetExportoperazione per API Gateway per conto dell'utente per ottenere un'esportazione in formato OpenAPI 3.0 della definizione dell'API. Questo aiuta il gateway a tradurre correttamente le richieste MCP in entrata in richieste HTTP e a gestire la risposta. Di seguito sono riportate le considerazioni relative al momento in cui AgentCore Gateway chiama l'operazione: GetExport

Aggiornamento di OperationID sulla tua API REST

Puoi aggiornare la tua API REST per assicurarti che la definizione OpenAPI restituita da GetExportsia operationId impostata. Questa è un'alternativa alla fornitura di un tool override. Di seguito vengono illustrati due modi per impostare. operationId

Imposta l'OperationID aggiornando la definizione OpenAPI

Esporta la definizione OpenAPI dalla fase di implementazione dell'API chiamando GetExport, aggiornando le operazioni mancanti e reimportando operationId l'API.

Imposta l'OperationID aggiornando il metodo dell'API REST

Puoi configurare il tuo metodo API Gateway per aggiungerne uno operationName utilizzando il UpdateMethodcomando. Quando la tua API viene esportata, si operationName trasforma in. operationId

Metodi di autorizzazione in uscita supportati per un'API API Gateway

Puoi configurare il tuo target AgentCore Gateway per effettuare chiamate alla tua API con autenticazione in uscita.

AgentCore Gateway supporta i seguenti tipi di autorizzazione in uscita per API Gateway Targets:

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

Autorizzazione IAM in uscita

API Gateway ti consente di proteggere la tua API REST con IAM. Quando l'autorizzazione IAM è abilitata, i client devono utilizzare Signature Version 4 (SigV4 o SigV4A) per firmare le loro richieste con le credenziali. AWS

Per configurare l'autorizzazione IAM in uscita

Politiche relative alle risorse di API Gateway

Le policy delle risorse di API Gateway sono documenti di policy JSON che si collegano a un'API REST di API Gateway per controllare se un principale specificato può richiamare l'API. Affinché AgentCore Gateway possa chiamare l'API REST con una policy relativa alle risorse, è necessario effettuare le seguenti operazioni:

Di seguito è riportato un esempio di politica delle risorse API che concede a AgentCore Gateway l'accesso all'API REST dell'utente.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
        }
      }
    }
  ]
}

Autorizzazione in uscita della chiave API

Per configurare l'autorizzazione in uscita con una chiave API, si utilizza il servizio AgentCore Identity per creare un provider di credenziali e con una chiave API configurata tramite API Gateway.

Per configurare l'autorizzazione in uscita della chiave API