Étapes de l'API REST Amazon API Gateway en tant que cibles

Une cible d'API REST API Gateway connecte votre passerelle à une étape de votre API REST. La passerelle traduit les requêtes MCP entrantes en requêtes HTTP destinées à votre API REST et gère le formatage des réponses. Lorsque vous ajoutez ou mettez à jour une cible d'API Gateway, AgentCore Gateway appelle l'API d'GetExportAPI Gateway en votre nom.

Vous pouvez spécifier des filtres d'outils et des remplacements d'outils dans votre configuration cible. Les filtres d'outils vous permettent de rendre disponibles des combinaisons de chemins de ressources et de méthodes HTTP spécifiques sous forme d'outils sur votre passerelle. Ces filtres créent une liste d'autorisations qui expose uniquement les opérations que vous spécifiez en tant qu'outils.

Vous pouvez également configurer votre stage d'API REST API Gateway en tant que cible de passerelle depuis la console API Gateway. Pour en savoir plus, consultez la section Ajouter une étape à une AgentCore passerelle dans la documentation Amazon API Gateway.

Principales considérations et limites

Lorsque vous utilisez un stage d'API REST API Gateway comme cible, gardez à l'esprit les exigences et limites suivantes :

Configuration de l'outil API Gateway

Lorsque vous ajoutez une API REST API Gateway en tant que cible de passerelle, vous devez fournir une configuration de l'outil API Gateway. La configuration de l'outil API Gateway définit les opérations de votre API REST qui sont exposées en tant qu'outils. Il nécessite une liste de filtres d'outils pour sélectionner les opérations à exposer, et accepte éventuellement les remplacements d'outils pour personnaliser les métadonnées des outils, telles que les noms et les descriptions des outils.

Filtres à outils

Les filtres d'outils vous permettent de sélectionner les opérations de l'API REST à l'aide de combinaisons de chemins et de méthodes. Chaque filtre prend en charge deux stratégies de correspondance de chemins :

Chaque filtre spécifie à la fois un chemin et une liste de méthodes HTTP. Le filtre résout les combinaisons correspondantes qui existent dans votre API. Plusieurs filtres peuvent se chevaucher et les doublons sont automatiquement dédupliqués.

Dérogations d'outils

Par défaut, le nom de l'outil MCP provient de operationId la combinaison chemin/méthode correspondant à vos filtres. S'il n'existe pas de correspondance operationId pour un filtre, vous aurez besoin d'un outil de remplacement correspondant qui fournit un nom. Si le nom operationId et le nom de remplacement sont absents, la création et les mises à jour de la cible échoueront à la validation. Pour plus d'informations sur les noms d'outils dans AgentCore Gateway, voir Comprendre comment les outils AgentCore Gateway sont nommés.

Les remplacements d'outils sont facultatifs. Ils vous permettent de personnaliser le nom ou la description de l'outil pour des opérations spécifiques après le filtrage. Chaque remplacement doit spécifier un chemin explicite et une méthode HTTP unique. Les caractères génériques ne sont pas pris en charge. La dérogation doit correspondre à une opération qui existe dans votre API et doit correspondre à l'une des opérations résolues par vos filtres. Vous ne pouvez pas annuler les opérations qui n'ont pas été sélectionnées. Si vous rencontrez des erreurs lors des importations à partir d'opérations sans un, operationId vous pouvez utiliser un outil de remplacement à la place.

Exemples de configurations de l'outil API Gateway

Les exemples de configuration de l'outil API Gateway suivants montrent comment utiliser les filtres et les remplacements. Tous les exemples utilisent une API avec les chemins et méthodes suivants :

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

Chemin joker et liste des méthodes

Configuration de l'outil :

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

Result

Chemin explicite et liste de méthodes

Configuration de l'outil :

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

Result

Chemin explicite et liste des méthodes explicites (les plus spécifiques)

Configuration de l'outil :

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

Result

Mélangez un chemin explicite et un chemin générique :

Configuration de l'outil :

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

Result

Filtre d'outils et remplacement d'outils

Vous pouvez fournir un filtre d'outil et ajouter une dérogation. L'override spécifie un chemin de ressource dans l'API REST, tel que /pets, et une méthode HTTP à exposer pour le chemin spécifié. Le remplacement doit correspondre explicitement à un chemin existant dans l'API REST.

Configuration de l'outil

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

Result

Exportation via API Gateway

Pour configurer votre cible API Gateway, AgentCore Gateway appelle l'GetExportopération API Gateway en votre nom afin d'obtenir une exportation au format OpenAPI 3.0 de votre définition d'API. Cela permet à la passerelle de traduire correctement les requêtes MCP entrantes en requêtes HTTP et de gérer la réponse. Voici les points à prendre en compte lorsque AgentCore Gateway appelle l' GetExport opération :

Mettre à jour OperationID sur votre API REST

Vous pouvez mettre à jour votre API REST pour vous assurer que la définition OpenAPI renvoyée par GetExportest operationId définie. Il s'agit d'une alternative à la fourniture d'une dérogation à un outil. Ce qui suit explique deux manières de définir leoperationId.

Définissez l'OperationID en mettant à jour votre définition OpenAPI

Exportez la définition d'OpenAPI depuis votre phase d'API déployée en appelant GetExport, en mettant à jour les opérations operationId manquantes et en réimportant votre API.

Définissez l'OperationID en mettant à jour la méthode de votre API REST

Vous pouvez configurer votre méthode API Gateway pour en ajouter une à operationName l'aide de la UpdateMethodcommande. Lorsque votre API est exportée, elle operationName se transforme enoperationId.

Méthodes d'autorisation sortante prises en charge pour une API API Gateway

Vous pouvez configurer votre cible AgentCore Gateway pour qu'elle passe des appels à votre API avec une authentification sortante.

AgentCore Gateway prend en charge les types d'autorisation sortante suivants pour les cibles d'API Gateway :

Pour en savoir plus, consultez Configurer l'autorisation sortante pour votre passerelle.

Autorisation de sortie IAM

API Gateway vous permet de sécuriser votre API REST avec IAM. Lorsque l'autorisation IAM est activée, les clients doivent utiliser la version 4 de signature (Sigv4 ou Sigv4a) pour signer leurs demandes avec des informations d'identification. AWS

Pour configurer l'autorisation sortante IAM

Politiques relatives aux ressources d'API Gateway

Les politiques de ressources d'API Gateway sont des documents de politique JSON que vous attachez à une API REST d'API Gateway pour contrôler si un principal spécifié peut invoquer l'API. Pour que AgentCore Gateway puisse appeler votre API REST avec une politique de ressources, vous devez effectuer les opérations suivantes :

Voici un exemple de politique de ressources d'API qui accorde à AgentCore Gateway l'accès à votre 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"
        }
      }
    }
  ]
}

Autorisation sortante de la clé API

Pour configurer l'autorisation sortante avec une clé d'API, vous utilisez le service AgentCore Identity pour créer un fournisseur d'informations d'identification et avec une clé d'API que vous avez configurée via API Gateway.

Pour configurer l'autorisation sortante par clé d'API