Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

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

Una destinazione 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 una destinazione API Gateway, AgentCore Gateway chiama l'API di API Gateway per tuo conto GetExport.

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

Puoi anche configurare la fase API REST di API Gateway come destinazione del 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 chiave

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

Configurazione dello strumento API Gateway

Quando aggiungi un'API REST 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 le 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 2 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 nella tua API. Più filtri possono sovrapporsi e i duplicati vengono deduplicati automaticamente.

Sostituzioni degli strumenti

Per impostazione predefinita, il nome dello strumento MCP deriva dalla combinazione operationId di ogni percorso e metodo che corrisponde ai filtri. Se non c'è una corrispondenza operationId per un filtro, avrai bisogno di una sostituzione dello strumento corrispondente che fornisca un nome. Se mancano sia il operationId nome che il nome dell'override, la creazione e gli aggiornamenti del target falliranno la convalida. Per ulteriori informazioni sui nomi degli strumenti in AgentCore Gateway, consulta Comprendere il nome degli strumenti di AgentCore Gateway.

Le sostituzioni degli strumenti sono opzionali. 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 si verificano errori nelle importazioni da operazioni prive di an, operationId è possibile utilizzare invece uno strumento di override.

Esempi di configurazioni dello strumento API Gateway

Le seguenti configurazioni dello strumento API Gateway mostrano 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 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 del metodo esplicito (il più specifico)

Configurazione dello strumento:

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

Risultato

Mescola e abbina un percorso esplicito e un percorso con caratteri jolly:

Configurazione dello strumento:

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

Risultato

Filtro e sostituzione degli strumenti

È possibile fornire un filtro degli strumenti e aggiungere un override. 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 tramite API Gateway

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

Aggiornamento dell'OperationID sull'API REST

Puoi aggiornare la tua API REST per assicurarti che la definizione OpenAPI restituita da sia GetExport impostataoperationId. Si tratta di un'alternativa alla sostituzione dello strumento. Di seguito vengono spiegati 2 modi per impostare. operationId

Imposta l'OperationID aggiornando la tua definizione OpenAPI

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

Imposta l'OperationID aggiornando il metodo dell'API REST

Puoi configurare il tuo metodo API Gateway per aggiungerne uno operationName utilizzando il UpdateMethod comando. Quando la tua API viene esportata, operationName diventa. operationId

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

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 in uscita IAM

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

Per configurare l'autorizzazione IAM in uscita

Politiche relative alle risorse API Gateway

Le policy sulle risorse di API Gateway sono documenti di policy JSON da allegare a un'API REST di API Gateway per controllare se un principal specificato può richiamare l'API. Affinché AgentCore Gateway possa chiamare la tua API REST con una policy sulle risorse, devi fare quanto segue:

Di seguito è riportato un esempio di policy sulle risorse API che concede a AgentCore Gateway l'accesso alla tua API REST.

{
"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 con chiave API

Per configurare l'autorizzazione in uscita con una chiave API, utilizzi il servizio AgentCore Identity per creare un provider di credenziali e con una chiave API che hai configurato tramite API Gateway.

Per configurare l'autorizzazione in uscita con chiave API