대상으로서 Amazon API Gateway REST API 단계

API Gateway REST API 대상은 게이트웨이를 REST API의 단계에 연결합니다. 게이트웨이는 수신 MCP 요청을 REST API에 대한 HTTP 요청으로 변환하고 응답 형식을 처리합니다. API Gateway 대상을 추가하거나 업데이트하면 AgentCore Gateway가 사용자를 대신하여 API Gateway의 GetExport API를 호출합니다.

대상 구성에서 도구 필터 및 도구 재정의를 지정할 수 있습니다. 도구 필터를 사용하면 특정 리소스 경로와 HTTP 메서드 조합을 게이트웨이의 도구로 사용할 수 있습니다. 이러한 필터는 도구로 지정한 작업만 노출하는 허용 목록을 생성합니다.

API Gateway 콘솔에서 API Gateway REST API 단계를 게이트웨이 대상으로 구성할 수도 있습니다. 자세한 내용은 Amazon API Gateway 설명서의 AgentCore 게이트웨이에 스테이지 추가를 참조하세요.

주요 고려 사항 및 제한 사항

API Gateway REST API 단계를 대상으로 사용하는 경우 다음 요구 사항 및 제한 사항에 유의하세요.

API Gateway 도구 구성

API Gateway REST API를 게이트웨이 대상으로 추가할 때는 API Gateway 도구 구성을 제공해야 합니다. API Gateway 도구 구성은 REST API에서 도구로 노출되는 작업을 정의합니다. 표시할 작업을 선택하려면 도구 필터 목록이 필요하며 선택적으로 도구 이름 및 설명과 같은 도구 메타데이터를 사용자 지정하기 위해 도구 재정의를 허용합니다.

도구 필터

도구 필터를 사용하면 경로 및 메서드 조합을 사용하여 REST API 작업을 선택할 수 있습니다. 각 필터는 두 가지 경로 일치 전략을 지원합니다.

각 필터는 경로와 HTTP 메서드 목록을 모두 지정합니다. 필터는 API에 있는 일치하는 조합으로 확인됩니다. 여러 필터가 겹칠 수 있으며 중복은 자동으로 중복 제거됩니다.

도구 재정의

기본적으로 MCP 도구 이름은 필터와 일치하는 각 경로 및 메서드 조합operationId의에서 가져옵니다. 필터 일치에 operationId 대한이 없는 경우 이름을 제공하는 해당 도구 재정의가 필요합니다. operationId 및 재정의 이름이 모두 누락된 경우 대상 생성 및 업데이트는 검증에 실패합니다. AgentCore Gateway의 도구 이름에 대한 자세한 내용은 AgentCore Gateway 도구의 이름 지정 방법 이해를 참조하세요.

도구 재정의는 선택 사항입니다. 필터링 후 특정 작업에 대한 도구 이름 또는 설명을 사용자 지정할 수 있습니다. 각 재정의는 명시적 경로와 단일 HTTP 메서드를 지정해야 합니다. 와일드카드는 지원되지 않습니다. 재정의는 API에 있는 작업과 일치해야 하며 필터에서 확인된 작업 중 하나에 해당해야 합니다. 선택되지 않은 작업은 재정의할 수 없습니다. 를 사용하여 작업에서 가져오는 operationId 동안 오류가 발생하는 경우 대신 도구 재정의를 사용할 수 있습니다.

API Gateway 도구 구성 예

다음 예제 API Gateway 도구 구성은 필터 및 재정의를 사용하는 방법을 보여줍니다. 모든 예제는 다음 경로 및 메서드와 함께 API를 사용합니다.

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

와일드카드 경로 및 메서드 목록

도구 구성:

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

결과

명시적 경로 및 메서드 목록

도구 구성:

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

결과

명시적 경로 및 명시적 메서드 목록(가장 구체적)

도구 구성:

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

결과

명시적 경로와 와일드카드 경로를 혼합하여 일치시킵니다.

도구 구성:

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

결과

도구 필터 및 도구 재정의

도구 필터를 제공하고 재정의를 추가할 수 있습니다. 재정의는 /pets와 같은 REST API의 리소스 경로와 지정된 경로에 대해 노출할 HTTP 메서드를 지정합니다. 재정의는 REST API의 기존 경로와 명시적으로 일치해야 합니다.

도구 구성

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

결과

API Gateway 내보내기

API Gateway 대상을 설정하기 위해 AgentCore Gateway는 사용자를 대신하여 API Gateway에 대한 GetExport 작업을 호출하여 API 정의의 OpenAPI 3.0 형식 내보내기를 가져옵니다. 이렇게 하면 게이트웨이가 수신 MCP 요청을 HTTP 요청으로 올바르게 변환하고 응답을 처리할 수 있습니다. 다음은 AgentCore Gateway가 GetExport 작업을 호출하는 경우에 대한 고려 사항입니다.

REST API에서 operationId 업데이트

REST API를 업데이트하여 GetExport에서 반환한 OpenAPI 정의가 operationId 설정되었는지 확인할 수 있습니다. 이는 도구 재정의를 제공하는 대신 사용할 수 있습니다. 다음은를 설정하는 두 가지 방법을 설명합니다operationId.

OpenAPI 정의를 업데이트하여 operationID 설정

GetExport를 호출하고, 누락된 작업을 업데이트하고, API를 다시 가져와 배포된 API 단계에서 OpenAPI operationId 정의를 내보냅니다.

REST API의 메서드를 업데이트operationId하여 설정

UpdateMethod 명령을 operationName 사용하여를 추가하도록 API Gateway 메서드를 구성할 수 있습니다. API를 내보내면가 로 operationName 바뀝니다operationId.

API Gateway API에 지원되는 아웃바운드 권한 부여 방법

아웃바운드 인증을 사용하여 API를 호출하도록 AgentCore Gateway 대상을 구성할 수 있습니다.

AgentCore Gateway는 API Gateway 대상에 대해 다음과 같은 유형의 아웃바운드 권한 부여를 지원합니다.

자세한 내용은 게이트웨이에 대한 아웃바운드 권한 부여 설정을 참조하세요.

IAM 아웃바운드 권한 부여

API Gateway를 사용하면 IAM으로 REST API를 보호할 수 있습니다. IAM 인증이 활성화된 경우 클라이언트는 서명 버전 4(SigV4 또는 SigV4a)를 사용하여 자격 AWS 증명으로 요청에 서명해야 합니다.

IAM 아웃바운드 권한 부여를 설정하려면

API Gateway 리소스 정책

API Gateway 리소스 정책은 지정된 보안 주체가 API를 호출할 수 있는지 여부를 제어하기 위해 API Gateway REST API에 연결하는 JSON 정책 문서입니다. AgentCore Gateway가 리소스 정책을 사용하여 REST API를 호출하려면 다음을 수행해야 합니다.

다음은 AgentCore Gateway에 REST API에 대한 액세스 권한을 부여하는 API 리소스 정책의 예입니다.

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

API 키 아웃바운드 권한 부여

API 키를 사용하여 아웃바운드 권한 부여를 설정하려면 AgentCore Identity 서비스를 사용하여 자격 증명 공급자와 API Gateway를 통해 구성한 API 키를 생성합니다.

API 키 아웃바운드 권한 부여를 설정하려면