Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Etapas de la API REST de Amazon API Gateway como objetivos

Un objetivo de API REST API Gateway conecta su puerta de enlace con una etapa de su API REST. La puerta de enlace traduce las solicitudes MCP entrantes en solicitudes HTTP a su API REST y gestiona el formato de las respuestas. Cuando agregas o actualizas un objetivo de API Gateway, AgentCore Gateway llama a la API de GetExport API Gateway en tu nombre.

Puedes especificar los filtros y las anulaciones de herramientas en tu configuración de destino. Los filtros de herramientas le permiten hacer que combinaciones específicas de rutas de recursos y métodos HTTP estén disponibles como herramientas en su puerta de enlace. Estos filtros crean una lista de permitidos que expone solo las operaciones que especifique como herramientas.

También puedes configurar tu etapa de API REST de API Gateway como destino de puerta de enlace desde la consola de API Gateway. Para obtener más información, consulte Añadir una etapa a una AgentCore puerta de enlace en la documentación de Amazon API Gateway.

Consideraciones y limitaciones clave

Cuando utilices una fase de API REST de API Gateway como objetivo, ten en cuenta los siguientes requisitos y limitaciones:

Configuración de la herramienta API Gateway

Al agregar una API REST de API Gateway como objetivo de puerta de enlace, debe proporcionar una configuración de la herramienta API Gateway. La configuración de la herramienta API Gateway define qué operaciones de su API REST se exponen como herramientas. Requiere una lista de filtros de herramientas para seleccionar las operaciones que se van a exponer y, de forma opcional, acepta anulaciones de herramientas para personalizar los metadatos de las herramientas, como los nombres y las descripciones de las herramientas.

Filtros de herramientas

Los filtros de herramientas le permiten seleccionar las operaciones de la API REST mediante combinaciones de rutas y métodos. Cada filtro admite dos estrategias de coincidencia de rutas:

Cada filtro especifica una ruta y una lista de métodos HTTP. El filtro se convierte en combinaciones coincidentes que existen en tu API. Se pueden superponer varios filtros y los duplicados se deduplican automáticamente.

Anulaciones de herramientas

De forma predeterminada, el nombre de la herramienta MCP se toma del nombre operationId de cada combinación de ruta y método que coincida con sus filtros. Si no hay ninguna coincidencia operationId para un filtro, necesitará la anulación de herramienta correspondiente que proporcione un nombre. Si faltan tanto el operationId nombre de anulación como el nombre de anulación, la creación del objetivo y las actualizaciones no se validarán. Para obtener más información sobre los nombres de las herramientas en AgentCore Gateway, consulte Comprender cómo se denominan las herramientas de AgentCore Gateway.

Las anulaciones de herramientas son opcionales. Permiten personalizar el nombre o la descripción de la herramienta para operaciones específicas después del filtrado. Cada anulación debe especificar una ruta explícita y un único método HTTP. No se admite el uso de comodines. La anulación debe coincidir con una operación que exista en tu API y debe corresponder a una de las operaciones resueltas por tus filtros. No puedes anular las operaciones que no se seleccionaron. Si se producen errores al importar desde operaciones sin una, operationId puede utilizar una herramienta de anulación en su lugar.

Ejemplos de configuraciones de herramientas de API Gateway

El siguiente ejemplo de configuración de la herramienta API Gateway muestra cómo usar los filtros y las anulaciones. Todos los ejemplos utilizan una API con las siguientes rutas y métodos:

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

Ruta comodín y lista de métodos

Configuración de la herramienta:

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

Resultado

Ruta explícita y lista de métodos

Configuración de la herramienta:

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

Resultado

Ruta explícita y lista de métodos explícitos (el más específico)

Configuración de la herramienta:

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

Resultado

Mezcle y combine una ruta explícita y una comodín:

Configuración de la herramienta:

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

Resultado

Filtro de herramientas y anulación de herramientas

Puede proporcionar un filtro de herramientas y añadir una anulación. La anulación especifica una ruta de recursos en la API REST, como /pets, y un método HTTP para mostrar la ruta especificada. La anulación debe coincidir explícitamente con una ruta existente en la API REST.

Configuración de la herramienta

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

Resultado

Exportación de API Gateway

Para configurar tu destino de API Gateway, AgentCore Gateway llama a la GetExport operación de API Gateway en tu nombre para obtener una exportación con formato OpenAPI 3.0 de tu definición de API. Esto ayuda a la pasarela a traducir correctamente las solicitudes MCP entrantes en solicitudes HTTP y a gestionar la respuesta. A continuación se presentan algunas consideraciones para cuando AgentCore Gateway llama a la GetExport operación:

Actualización de OperationID en su API REST

Puede actualizar su API REST para asegurarse de que se GetExport haya operationId establecido la definición de OpenAPI devuelta por. Esta es una alternativa a proporcionar una herramienta de anulación. A continuación se explican dos formas de configurar eloperationId.

Configure el OperationID actualizando su definición de OpenAPI

Exporte la definición de OpenAPI desde la fase de API implementada llamando GetExport, actualizando las operaciones que faltan operationId y volviendo a importar su API.

Configura el OperationID actualizando el método de tu API REST

Puedes configurar tu método de puerta de enlace de API para agregar un operationName mediante el comando. UpdateMethod Cuando se exporta su API, se operationName convierte enoperationId.

Métodos de autorización saliente compatibles para una API de API Gateway

Puedes configurar tu destino de AgentCore Gateway para realizar llamadas a tu API con autenticación saliente.

AgentCore Gateway admite los siguientes tipos de autorización saliente para los objetivos de API Gateway:

Para obtener más información, consulta Cómo configurar la autorización de salida para tu puerta de enlace.

Autorización saliente de IAM

API Gateway le permite proteger su API REST con IAM. Cuando la autorización de IAM está habilitada, los clientes deben usar la versión 4 de Signature (SIGv4 o SIGv4a) para firmar sus solicitudes con credenciales. AWS

Para configurar la autorización saliente de IAM

Políticas de recursos de API Gateway

Las políticas de recursos de API Gateway son documentos de políticas de JSON que se adjuntan a una API REST de API Gateway para controlar si una entidad principal específica puede invocar la API. Para que AgentCore Gateway llame a tu API de REST con una política de recursos, debes hacer lo siguiente:

El siguiente es un ejemplo de una política de recursos de API que otorga a AgentCore Gateway acceso a su API de 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"
        }
      }
    }
  ]
}

Autorización saliente de la clave de API

Para configurar la autorización saliente con una clave de API, utiliza el servicio de AgentCore identidad para crear un proveedor de credenciales y con una clave de API que haya configurado a través de API Gateway.

Para configurar la autorización saliente de una clave de API