Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

É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 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 mettre à disposition 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'autorisation 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 à partir de 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, tenez compte des 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 d'outil API Gateway. La configuration de l'outil API Gateway définit quelles opérations de votre API REST 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 d'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 permet de résoudre les combinaisons correspondantes qui existent dans votre API. Plusieurs filtres peuvent se chevaucher et les doublons sont automatiquement dédupliqués.

Remplacements d'outils

Par défaut, le nom de l'outil MCP provient de celui operationId de chaque combinaison de chemin et de méthode correspondant à vos filtres. S'il n'y a 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 manquants, la création et les mises à jour de la cible échoueront à la validation. Pour plus d'informations sur les noms des 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 seule méthode HTTP. Les caractères génériques ne sont pas pris en charge. Le remplacement 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 depuis des opérations sans an, 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 du 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 et associez un chemin explicite et un chemin générique :

Configuration de l'outil :

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

Result

Filtre d'outil et remplacement d'outil

Vous pouvez fournir un filtre d'outil et ajouter un remplacement. Le remplacement 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 d'API Gateway

Pour configurer votre cible API Gateway, AgentCore Gateway appelle l'GetExportopération pour 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. Les considérations suivantes doivent être prises 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 GetExport est operationId définie. Il s'agit d'une alternative à la fourniture d'un outil de remplacement. 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 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 UpdateMethod commande. Lorsque votre API est exportée, elle operationName se transforme enoperationId.

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

Vous pouvez configurer votre cible de AgentCore passerelle pour passer des appels vers votre API avec une authentification sortante.

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

Pour en savoir plus, consultez la section Configuration de l'autorisation sortante pour votre passerelle.

Autorisation IAM pour les envois sortants

API Gateway vous permet de sécuriser votre API REST avec IAM. Lorsque l'autorisation IAM est activée, les clients doivent utiliser Signature Version 4 (Sigv4 ou SigV4a) pour signer leurs demandes à l'aide d'informations d'identification. AWS

Pour configurer l'autorisation IAM pour les envois sortants

Politiques relatives aux ressources d'API Gateway

Les politiques de ressources API Gateway sont des documents de stratégie JSON que vous joignez à une API REST 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 par clé d'API

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

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