# 게이트웨이 규칙 API 예제
다음 예제에서는 AWS CLI 및 AWS Python SDK(Boto3)를 사용하여 게이트웨이 규칙을 관리하는 방법을 보여줍니다.
## 정적 구성 번들 재정의로 규칙 생성
다음 예제에서는 특정 IAM 보안 주체를 구성 번들 버전에 고정시키는 규칙을 생성합니다. QA 또는 디버깅에이 접근 방식을 사용합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 100 \
--description "Pin QA role to bundle version" \
--conditions '[
{
"matchPrincipals": {
"anyOf": [
{
"iamPrincipal": {
"arn": "arn:aws:iam::123456789012:role/QARole",
"operator": "StringEquals"
}
}
]
}
}
]' \
--actions '[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=100,
description="Pin QA role to bundle version",
conditions=[
{
"matchPrincipals": {
"anyOf": [
{
"iamPrincipal": {
"arn": "arn:aws:iam::123456789012:role/QARole",
"operator": "StringEquals",
}
}
]
}
}
],
actions=[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab",
}
}
}
],
)
print(f"Rule ID: {response['ruleId']}")
```
## catch-all 기본 규칙 생성
다음 예제에서는 조건 없이 규칙을 생성합니다. 이 규칙은 모든 트래픽과 일치하며 기본값으로 사용됩니다. 보다 구체적인 규칙이 우선하도록 높은 우선 순위 번호를 할당합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 1000000 \
--description "Default configuration bundle for all traffic" \
--actions '[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=1000000,
description="Default configuration bundle for all traffic",
actions=[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab",
}
}
}
],
)
print(f"Rule ID: {response['ruleId']}")
```
## 가중치 기반 구성 번들 분할을 사용하여 규칙 생성
다음 예제에서는 A/B 테스트를 위해 두 구성 번들 버전 간에 트래픽을 분할하는 규칙을 생성합니다. 이 예제에서는 트래픽의 80%가 변형 A를 사용하고 20%가 변형 B를 사용합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 500 \
--description "A/B test: 80/20 traffic split" \
--actions '[
{
"configurationBundle": {
"weightedOverride": {
"trafficSplit": [
{
"name": "variant-a",
"weight": 80,
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab"
},
"description": "Control variant"
},
{
"name": "variant-b",
"weight": 20,
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "12345678-1234-5678-9abc-123456789012"
},
"description": "Treatment variant"
}
]
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=500,
description="A/B test: 80/20 traffic split",
actions=[
{
"configurationBundle": {
"weightedOverride": {
"trafficSplit": [
{
"name": "variant-a",
"weight": 80,
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab",
},
"description": "Control variant",
},
{
"name": "variant-b",
"weight": 20,
"configurationBundle": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "12345678-1234-5678-9abc-123456789012",
},
"description": "Treatment variant",
},
]
}
}
}
],
)
print(f"Rule ID: {response['ruleId']}")
```
**참고**
A/B 테스트 중에 일관된 사용자 환경을 유지하려면 게이트웨이 호출 요청에 `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` 헤더를 포함합니다. 자세한 내용은 [가중치 기반 규칙에 대한 세션 고정성](gateway-rules-session-stickiness.md) 단원을 참조하십시오.
## 대상 라우팅을 사용하여 규칙 생성
다음 예제에서는 특정 경로 패턴과 일치하는 요청을 대상으로 라우팅하는 규칙을 생성합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 150 \
--description "Route /my-target-canary requests to canary target" \
--conditions '[
{
"matchPaths": {
"anyOf": [
"/my-target-canary/*"
]
}
}
]' \
--actions '[
{
"routeToTarget": {
"staticRoute": {
"targetName": "my-target-canary"
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=150,
description="Route /my-target-canary requests to canary target",
conditions=[
{
"matchPaths": {
"anyOf": ["/my-target-canary/*"]
}
}
],
actions=[
{
"routeToTarget": {
"staticRoute": {
"targetName": "my-target-canary",
}
}
}
],
)
print(f"Rule ID: {response['ruleId']}")
```
## 가중치 대상 라우팅을 사용하여 규칙 생성
다음 예제에서는 두 대상 간에 트래픽을 분할하는 규칙을 생성합니다. 이 예제에서는 트래픽의 90%가 기본 대상으로 라우팅되고 10%가 카나리아 대상으로 라우팅됩니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 300 \
--description "Canary deployment: 90/10 target split" \
--actions '[
{
"routeToTarget": {
"weightedRoute": {
"trafficSplit": [
{
"name": "primary",
"weight": 90,
"targetName": "my-target-primary",
"description": "Primary target"
},
{
"name": "canary",
"weight": 10,
"targetName": "my-target-canary",
"description": "Canary target"
}
]
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=300,
description="Canary deployment: 90/10 target split",
actions=[
{
"routeToTarget": {
"weightedRoute": {
"trafficSplit": [
{
"name": "primary",
"weight": 90,
"targetName": "my-target-primary",
"description": "Primary target",
},
{
"name": "canary",
"weight": 10,
"targetName": "my-target-canary",
"description": "Canary target",
},
]
}
}
}
],
)
print(f"Rule ID: {response['ruleId']}")
```
## 조건과 작업이 결합된 규칙 생성
다음 예제에서는 조건 유형과 작업 유형을 모두 포함하는 규칙을 생성합니다. 요청은 각 조건 유형( 유형 간 AND 로직)에서 하나 이상의 항목과 일치해야 합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control create-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--priority 50 \
--description "QA role on /my-target-canary paths: pin bundle and route to canary" \
--conditions '[
{
"matchPrincipals": {
"anyOf": [
{
"iamPrincipal": {
"arn": "arn:aws:iam::123456789012:role/QARole",
"operator": "StringEquals"
}
}
]
}
},
{
"matchPaths": {
"anyOf": [
"/my-target-canary/*"
]
}
}
]' \
--actions '[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
},
{
"routeToTarget": {
"staticRoute": {
"targetName": "my-target-canary"
}
}
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
priority=50,
description="QA role on /my-target-canary paths: pin bundle and route to canary",
conditions=[
{
"matchPrincipals": {
"anyOf": [
{
"iamPrincipal": {
"arn": "arn:aws:iam::123456789012:role/QARole",
"operator": "StringEquals",
}
}
]
}
},
{
"matchPaths": {
"anyOf": ["/my-target-canary/*"]
},
},
],
actions=[
{
"configurationBundle": {
"staticOverride": {
"bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-abc1234567",
"bundleVersion": "1234abcd-12ab-34cd-56ef-1234567890ab",
}
}
},
{
"routeToTarget": {
"staticRoute": {
"targetName": "my-target-canary",
}
}
},
],
)
print(f"Rule ID: {response['ruleId']}")
```
**참고**
이 규칙은 호출자가 QA 역할이고 요청 경로가와 일치하는 경우에만 일치합니다`/my-target-canary/*`. 두 조건을 모두 충족해야 합니다.
## 게이트웨이 규칙 가져오기
다음 예시에서는 특정 게이트웨이 규칙의 세부 정보를 검색합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control get-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--rule-id 12345678-1234-1234-1234-123456789012
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.get_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
ruleId="12345678-1234-1234-1234-123456789012",
)
print(f"Priority: {response['priority']}")
print(f"Status: {response['status']}")
print(f"Actions: {response['actions']}")
```
## 게이트웨이 규칙 업데이트
다음 예시에서는 기존 게이트웨이 규칙의 우선 순위와 설명을 업데이트합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control update-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--rule-id 12345678-1234-1234-1234-123456789012 \
--priority 200 \
--description "Updated priority for QA rule"
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.update_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
ruleId="12345678-1234-1234-1234-123456789012",
priority=200,
description="Updated priority for QA rule",
)
print(f"Status: {response['status']}")
```
## 게이트웨이 규칙 나열
다음 예시에서는 게이트웨이에 대한 모든 규칙을 나열합니다. 결과는 우선 순위에 따라 오름차순으로 정렬됩니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control list-gateway-rules \
--gateway-identifier my-gateway-abc1234567
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.list_gateway_rules(
gatewayIdentifier="my-gateway-abc1234567"
)
for rule in response["gatewayRules"]:
print(f"Rule: {rule['ruleId']}, Priority: {rule['priority']}, Status: {rule['status']}")
```
## 게이트웨이 규칙 삭제
다음 예시에서는 게이트웨이 규칙을 삭제합니다.
**Example**
1. 다음 명령을 실행합니다.
```
aws bedrock-agentcore-control delete-gateway-rule \
--gateway-identifier my-gateway-abc1234567 \
--rule-id 12345678-1234-1234-1234-123456789012
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.delete_gateway_rule(
gatewayIdentifier="my-gateway-abc1234567",
ruleId="12345678-1234-1234-1234-123456789012",
)
print(f"Status: {response['status']}")
```