Amazon API Gateway REST-API-Stufen als Ziele

Ein API-Gateway-REST-API-Ziel verbindet Ihr Gateway mit einer Phase Ihrer REST-API. Das Gateway übersetzt eingehende MCP-Anfragen in HTTP-Anfragen an Ihre REST-API und kümmert sich um die Formatierung der Antworten. Wenn Sie ein API-Gateway-Ziel hinzufügen oder aktualisieren, ruft AgentCore Gateway die API von GetExportAPI Gateway in Ihrem Namen auf.

Sie können Tool-Filter und Tool-Overrides in Ihrer Zielkonfiguration angeben. Mit Toolfiltern können Sie bestimmte Kombinationen aus Ressourcenpfad und HTTP-Methoden als Tools auf Ihrem Gateway verfügbar machen. Diese Filter erstellen eine Zulassungsliste, die nur die Operationen anzeigt, die Sie als Tools angeben.

Sie können Ihre API Gateway Gateway-REST-API-Stufe auch über die API Gateway-Konsole als Gateway-Ziel konfigurieren. Weitere Informationen finden Sie unter Hinzufügen einer Phase zu einem AgentCore Gateway in der Amazon API Gateway Gateway-Dokumentation.

Wichtige Überlegungen und Einschränkungen

Beachten Sie bei der Verwendung einer API-Gateway-REST-API-Stufe als Ziel die folgenden Anforderungen und Einschränkungen:

Konfiguration des API-Gateway-Tools

Wenn Sie eine API-Gateway-REST-API als Gateway-Ziel hinzufügen, müssen Sie eine API-Gateway-Toolkonfiguration angeben. Die Konfiguration des API Gateway Gateway-Tools definiert, welche Operationen aus Ihrer REST-API als Tools verfügbar gemacht werden. Sie benötigt eine Liste von Toolfiltern, um Operationen auszuwählen, die verfügbar gemacht werden sollen, und akzeptiert optional Werkzeugüberschreibungen, um Tool-Metadaten wie Toolnamen und -beschreibungen anzupassen.

Werkzeugfilter

Mit Toolfiltern können Sie REST-API-Operationen mithilfe von Pfad- und Methodenkombinationen auswählen. Jeder Filter unterstützt zwei Strategien für den Pfadabgleich:

Jeder Filter gibt sowohl einen Pfad als auch eine Liste von HTTP-Methoden an. Der Filter löst passende Kombinationen auf, die in Ihrer API vorhanden sind. Mehrere Filter können sich überschneiden und Duplikate werden automatisch dedupliziert.

Werkzeugüberschreibungen

Standardmäßig wird der Name des MCP-Tools aus der Kombination operationId für jeden Pfad und jede Methode übernommen, die Ihren Filtern entspricht. Wenn es operationId für einen Filter keine Übereinstimmung gibt, benötigen Sie eine entsprechende Werkzeugüberschreibung, die einen Namen angibt. Wenn operationId sowohl der Name als auch der Override-Name fehlen, schlägt die Überprüfung der Zielerstellung und der Aktualisierungen fehl. Weitere Informationen zu Toolnamen in AgentCore Gateway finden Sie unter Grundlegendes zur Benennung von AgentCore Gateway-Tools.

Werkzeugüberschreibungen sind optional. Sie ermöglichen es Ihnen, den Namen oder die Beschreibung des Tools für bestimmte Operationen nach dem Filtern anzupassen. Bei jeder Überschreibung müssen ein expliziter Pfad und eine einzelne HTTP-Methode angegeben werden. Platzhalter werden nicht unterstützt. Die Überschreibung muss mit einer Operation übereinstimmen, die in Ihrer API vorhanden ist, und muss einer der von Ihren Filtern aufgelösten Operationen entsprechen. Sie können keine Operationen überschreiben, die nicht ausgewählt wurden. Wenn bei Importen von Vorgängen ohne an Fehler auftreten, können operationId Sie stattdessen ein Tool Override verwenden.

Beispielkonfigurationen API Gateway API-Gateway-Tools

Die folgenden Beispielkonfigurationen des API Gateway Gateway-Tools zeigen, wie Filter und Overrides verwendet werden. Alle Beispiele verwenden eine API mit den folgenden Pfaden und Methoden:

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

Wildcard-Pfad und Liste von Methoden

Konfiguration des Tools:

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

Ergebnis

Expliziter Pfad und Liste der Methoden

Konfiguration des Tools:

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

Ergebnis

Expliziter Pfad und Liste der expliziten Methoden (am spezifischsten)

Konfiguration des Tools:

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

Ergebnis

Kombinieren Sie einen expliziten Pfad und einen Platzhalterpfad:

Konfiguration des Tools:

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

Ergebnis

Werkzeugfilter und Werkzeugüberschreibung

Sie können einen Werkzeugfilter bereitstellen und eine Überschreibung hinzufügen. Die Überschreibung gibt einen Ressourcenpfad in der REST-API an, z. B. /pets, und eine HTTP-Methode, die für den angegebenen Pfad verfügbar gemacht werden soll. Die Überschreibung muss explizit mit einem vorhandenen Pfad in der REST-API übereinstimmen.

Konfiguration des Tools

{
  "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"
    }
  ]
}

Ergebnis

API-Gateway-Export

Um Ihr API-Gateway-Ziel einzurichten, ruft AgentCore Gateway in Ihrem Namen den GetExportVorgang für API Gateway auf, um einen OpenAPI 3.0-formatierten Export Ihrer API-Definition zu erhalten. Dies hilft dem Gateway, eingehende MCP-Anfragen ordnungsgemäß in HTTP-Anfragen zu übersetzen und die Antwort zu verarbeiten. Im Folgenden sind Überlegungen für den Zeitpunkt aufgeführt, zu dem AgentCore Gateway den GetExport Vorgang aufruft:

OperationID auf Ihrer REST-API aktualisieren

Sie können Ihre REST-API aktualisieren, um sicherzustellen, dass die von zurückgegebene OpenAPI-Definition operationId festgelegt GetExportwurde. Dies ist eine Alternative zur Bereitstellung einer Tool-Override. Im Folgenden werden zwei Möglichkeiten zum Einstellen von erläutertoperationId.

Legen Sie die OperationID fest, indem Sie Ihre OpenAPI-Definition aktualisieren

Exportieren Sie die OpenAPI-Definition aus Ihrer bereitgestellten API-Phase GetExport, indem Sie Ihre API aufrufen, die fehlenden operationId Operationen aktualisieren und erneut importieren.

Legen Sie die OperationID fest, indem Sie die Methode Ihrer REST-API aktualisieren

Sie können Ihre API-Gateway-Methode so konfigurieren, dass sie hinzugefügt wird, operationName indem Sie den UpdateMethodBefehl verwenden. Wenn Ihre API exportiert wird, operationName wird das zuoperationId.

Unterstützte ausgehende Autorisierungsmethoden für eine API-Gateway-API

Sie können Ihr AgentCore Gateway-Ziel so konfigurieren, dass es Aufrufe an Ihre API mit ausgehender Authentifizierung tätigt.

AgentCore Gateway unterstützt die folgenden Arten der ausgehenden Autorisierung für API-Gateway-Ziele:

Weitere Informationen finden Sie unter Ausgehende Autorisierung für Ihr Gateway einrichten.

IAM-Autorisierung für ausgehenden Datenverkehr

Mit API Gateway können Sie Ihre REST-API mit IAM sichern. Wenn die IAM-Autorisierung aktiviert ist, müssen Clients Signature Version 4 (Sigv4 oder SigV4a) verwenden, um ihre Anfragen mit Anmeldeinformationen zu signieren. AWS

Um die ausgehende IAM-Autorisierung einzurichten

API-Gateway-Ressourcenrichtlinien

API Gateway Gateway-Ressourcenrichtlinien sind JSON-Richtliniendokumente, die Sie an eine API-Gateway-REST-API anhängen, um zu steuern, ob ein bestimmter Prinzipal die API aufrufen kann. Damit AgentCore Gateway Ihre REST-API mit einer Ressourcenrichtlinie aufrufen kann, müssen Sie wie folgt vorgehen:

Im Folgenden finden Sie ein Beispiel für eine API-Ressourcenrichtlinie, die AgentCore Gateway Zugriff auf Ihre REST-API gewährt.

{
"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"
        }
      }
    }
  ]
}

Ausgehende API-Schlüssel-Autorisierung

Um die ausgehende Autorisierung mit einem API-Schlüssel einzurichten, verwenden Sie den AgentCore Identity-Dienst, um einen Anmeldeinformationsanbieter zu erstellen, und zwar mit einem API-Schlüssel, für den Sie über API Gateway konfiguriert haben.

Um die ausgehende API-Schlüssel-Autorisierung einzurichten