本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用浏览器代理 亚马逊基岩 AgentCore 浏览器支持通过您自己的外部代理服务器路由浏览器流量。这使组织能够： + **通过具有已知出口 IP 的代理路由流量，从而实现 IP 稳定性**，从而消除轮换 IP 地址导致的重新身份验证周期 Amazon + ****通过为需要访问控制的服务提供稳定、可控制的出口地址，支持 IP 许可名单 IP-based + **通过现有代理服务器进行路由以访问内部网页和资源，与企业基础设施**集成 ## 概述 当您使用代理配置创建浏览器会话时， AgentCore 浏览器会将浏览器配置为通过您指定的代理服务器路由 HTTP 和 HTTPS 流量。 ![浏览器代理请求流显示了从浏览器会话通过客户管理的代理服务器到目标网站的流量路由。](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/browser-proxies-flow.png) 请求流程： 1. 您`StartBrowserSession`使用`proxyConfiguration`指定代理服务器进行调用。 1. 如果使用身份验证，则从 S Amazon ecrets Manager AgentCore 检索代理证书。 1. 浏览器会话从应用您的代理配置开始。 1. 浏览器流量根据您的域路由规则通过代理服务器进行路由。 1. 您的代理服务器将请求转发到目标网站。 代理服务器是您拥有和管理的基础架构。 AgentCore 浏览器作为客户端连接到它。 代理配置在启动时将 Chromium `--proxy-server` 标志应用于浏览器实例，在浏览器级别引导流量通过指定的代理。对于需要网络层强制执行的场景（例如，在运行时可以修改浏览器级设置时），在您自己的 VPC 中部署浏览器会话。请参阅[为 VPC ](agentcore-vpc.md) 配置亚马逊 Bedrock AgentCore 运行时和工具。 ## 先决条件 在配置浏览器代理之前，请确保您有： + **一般浏览器先决条件 **-完成标准浏览器工具设置。请参阅 “ AgentCore 浏览器[入门](browser-quickstart.md)”。 + **代理服务器 **-可从公共互联网访问的 HTTP/HTTPS 代理服务器（如果使用 VPC 配置，则可在您的 VPC 内访问），并支持 HTTP 连接方法进行 HTTPS 流量隧道。 + ** Amazon 密钥管理器密钥**（如果使用身份验证）— 一个包含 JSON 格式的代理凭据`username`以及和`password`密钥的密钥。 + **IAM 权限**（如果使用身份验证）— IAM 身份调用`StartBrowserSession`必须具有凭证密钥的`secretsmanager:GetSecretValue`权限。 ## 开始使用 本节显示了通过代理路由浏览器流量的最简单配置。 ### 第 1 步：创建凭据密钥（如果使用身份验证） 如果您的代理需要身份验证，请在密钥管理器中创建密 Amazon 钥： ``` aws secretsmanager create-secret \ --name "my-proxy-credentials" \ --secret-string '{"username":"","password":""}' ``` 凭证格式要求： | 字段 | 允许使用的字符 | | --- | --- | | `username` | 字母数字加号 `@ . _ + = -` | | `password` | 字母数字加上 @. \_ \+ =-\!\# $% \* | 不允许使用字符：冒号 (`:`)、换行符、空格、引号。 ### 第 2 步：添加 IAM 权限 将此策略添加到将创建浏览器会话的 IAM 身份中： ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:AWS Region:AWS account:secret:secret-name*" } ] } ``` ### 第 3 步：使用代理创建浏览器会话 您可以使用 Amazon CLI、SDK 或 API 使用代理配置创建浏览器会话。 **Example** 1. 要使用 Amazon CLI 启动与代理的浏览器会话，请执行以下操作： ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "aws.browser.v1" \ --name "my-proxy-session" \ --proxy-configuration '{ "proxies": [{ "externalProxy": { "server": "your-proxy-hostname", "port": 8080, "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }] }' ``` 对于使用 IP 许可名单而不是凭据的代理，请省略该字段：`credentials` ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "aws.browser.v1" \ --name "my-proxy-session" \ --proxy-configuration '{ "proxies": [{ "externalProxy": { "server": "your-proxy-hostname", "port": 8080 } }] }' ``` 1. 要使用 Amazon 适用于 Python 的软件开发工具包 (Boto3) 启动与代理的浏览器会话，请执行以下操作： ``` import boto3 client = boto3.client('bedrock-agentcore', region_name='region') response = client.start_browser_session( browserIdentifier="aws.browser.v1", name="my-proxy-session", proxyConfiguration={ "proxies": [{ "externalProxy": { "server": "your-proxy-hostname", "port": 8080, "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }] } ) print(f"Session ID: {response['sessionId']}") ``` 对于使用 IP 许可名单而不是凭据的代理，请省略该字段：`credentials` ``` proxyConfiguration={ "proxies": [{ "externalProxy": { "server": "your-proxy-hostname", "port": 8080 } }] } ``` 1. 要使用 API 启动与代理的浏览器会话，请执行以下操作： ``` PUT /browsers/aws.browser.v1/sessions/start HTTP/1.1 Host: bedrock-agentcore.region.amazonaws.com Content-Type: application/json Authorization: AWS4-HMAC-SHA256 ... { "name": "my-proxy-session", "proxyConfiguration": { "proxies": [{ "externalProxy": { "server": "your-proxy-hostname", "port": 8080, "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }] } } ``` ## 配置选项 ### Domain-based 路由 `domainPatterns`用于通过指定代理路由特定域： **Example** 1. ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "aws.browser.v1" \ --name "domain-routing-session" \ --proxy-configuration '{ "proxies": [ { "externalProxy": { "server": "corp-proxy.example.com", "port": 8080, "domainPatterns": [".company.com", ".internal.corp"] } }, { "externalProxy": { "server": "general-proxy.example.com", "port": 8080 } } ] }' ``` 1. ``` proxyConfiguration={ "proxies": [ { "externalProxy": { "server": "corp-proxy.example.com", "port": 8080, "domainPatterns": [".company.com", ".internal.corp"] } }, { "externalProxy": { "server": "general-proxy.example.com", "port": 8080 } } ] } ``` 1. ``` { "proxyConfiguration": { "proxies": [ { "externalProxy": { "server": "corp-proxy.example.com", "port": 8080, "domainPatterns": [".company.com", ".internal.corp"] } }, { "externalProxy": { "server": "general-proxy.example.com", "port": 8080 } } ] } } ``` 使用此配置： + 向 \*.company.com 和 \*.internal.corp 发送的请求通过 `corp-proxy.example.com` + 所有其他请求都会通过`general-proxy.example.com`（默认） 域模式格式： | 模式 | Matches | 不匹配 | | --- | --- | --- | | `.example.com` | `example.com` , `www.example.com` , `api.example.com` | `notexample.com` | | `example.com` | `example.com`（仅限精确匹配） | `www.example.com` | 使用`.example.com`（前导点）表示子域名。不要使用 \*.example.com。 ### 绕过域名 `bypass.domainPatterns`用于应在没有任何代理的情况下直接连接的域名： **Example** 1. ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "aws.browser.v1" \ --name "bypass-session" \ --proxy-configuration '{ "proxies": [{ "externalProxy": { "server": "proxy.example.com", "port": 8080 } }], "bypass": { "domainPatterns": [".amazonaws.com"] } }' ``` 1. ``` proxyConfiguration={ "proxies": [{ "externalProxy": { "server": "proxy.example.com", "port": 8080 } }], "bypass": { "domainPatterns": [".amazonaws.com"] } } ``` 1. ``` { "proxyConfiguration": { "proxies": [{ "externalProxy": { "server": "proxy.example.com", "port": 8080 } }], "bypass": { "domainPatterns": [".amazonaws.com"] } } } ``` **注意** 代理配置是浏览器级别的路由设置，不提供网络级别的流量控制。要执行网络层，请在您的 VPC 中部署浏览器会话。请参阅[为 VPC ](agentcore-vpc.md) 配置亚马逊 Bedrock AgentCore 运行时和工具。 ### 路由优先级 根据此优先顺序（从高到低）的交通路线： 1. **绕过域名 **-匹配的域名直接`bypass.domainPatterns`连接。 1. **代理域模式 **-通过该代理匹配代理`domainPatterns`路由的域（根据数组顺序首先匹配获胜）。 1. **默认代理 ** — 不匹配的域通过代理进行路由，但不使用`domainPatterns`。 ## 完整示例 以下示例显示了包含域模式、绕过域和身份验证凭据的完整代理配置。 **Example** 1. ``` aws bedrock-agentcore start-browser-session \ --browser-identifier "aws.browser.v1" \ --name "proxy-session" \ --proxy-configuration '{ "proxies": [{ "externalProxy": { "server": "proxy-hostname", "port": 8080, "domainPatterns": [".company.com"], "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }], "bypass": { "domainPatterns": [".amazonaws.com"] } }' ``` 1. ``` import boto3 client = boto3.client('bedrock-agentcore', region_name='region') response = client.start_browser_session( browserIdentifier="aws.browser.v1", name="proxy-session", proxyConfiguration={ "proxies": [{ "externalProxy": { "server": "proxy-hostname", "port": 8080, "domainPatterns": [".company.com"], "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }], "bypass": { "domainPatterns": [".amazonaws.com"] } } ) print(f"Session ID: {response['sessionId']}") ``` 1. ``` PUT /browsers/aws.browser.v1/sessions/start HTTP/1.1 Host: bedrock-agentcore.region.amazonaws.com Content-Type: application/json Authorization: AWS4-HMAC-SHA256 ... { "name": "proxy-session", "proxyConfiguration": { "proxies": [{ "externalProxy": { "server": "proxy-hostname", "port": 8080, "domainPatterns": [".company.com"], "credentials": { "basicAuth": { "secretArn": "arn:aws:secretsmanager:region:account-id:secret:secret-name" } } } }], "bypass": { "domainPatterns": [".amazonaws.com"] } } } ``` ## 使用案例 ### 基于会话的门户的 IP 稳定性 医疗保健和金融门户网站通常根据源 IP 地址验证会话。轮换 Amazon IP 地址会导致频繁的重新认证。通过具有稳定出口 IP 的代理路由流量，以保持会话连续性。 ### 企业基础设施集成 通过公司代理路由流量的组织可以将这种做法扩展到 AgentCore 浏览器会话，从而允许访问需要基于代理的连接的内部网页和资源。 ### 地理内容访问权限 通过特定地理位置的代理路由流量，访问特定地区的内容或测试区域网站变体。 ### 合作伙伴网络访问权限 通过专用的代理基础架构路由合作伙伴特定的流量，同时对其他流量使用通用代理。 ## 会话行为 ### 配置生命周期 + **创建时设置 **-代理配置在会话创建时设置一次。不支持在运行时进行配置更改。创建一个新会话以使用不同的设置。 + **Session-scoped**— 每个浏览器会话都有独立的代理配置。 + **超时 **-标准会话超时适用。会话结束时，代理配置将被丢弃。 ### 连接行为 + **Fail-open**— 创建会话时未验证代理连接。加载页面时，使用不可用代理配置的会话将显示错误。 + **运行时错误 **-连接失败显示为浏览器错误页面，可在实时视图中显示以进行故障排除。 + **不自动重试 **-失败的请求不会自动重试。 ## Cross-account 秘密访问 如果证书密钥位于其他 Amazon 账户中，请配置以下内容： **机密资源政策**（在拥有密钥的账户中）： ``` { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::caller-account-id:root"}, "Action": "secretsmanager:GetSecretValue", "Resource": "*" }] } ``` **KMS 密钥政策**（如果使用客户管理的 KMS 密钥）： ``` { "Effect": "Allow", "Principal": {"AWS": "arn:aws:iam::caller-account-id:root"}, "Action": "kms:Decrypt", "Resource": "*" } ``` ## 安全注意事项 ### 凭据保护 + 证书存储在 Amazon 密钥管理器中，并使用您的 IAM 证书获取。 + API 响应中永远不会返回证书。`GetBrowserSession`仅退货`secretArn`。 + 凭据不会写入日志。 ### 访问控制 + IAM 权限控制哪些身份可以使用哪些凭证机密。 + Cross-account 访问需要明确的资源策略。 ## 性能注意事项 + **容量 **-确保您的代理能够处理预期的请求量。 + **绕过 ** — `bypass.domainPatterns` 为延迟敏感呼叫添加 Amazon 端点。 + **邻近度 ** — 使用地理位置靠近您所在 Amazon 地区的代理。 ## 约束 | 约束 | 限制 | 可调整 | | --- | --- | --- | | 每个会话的最大代理数 | 5 | 是 | | 每个代理的最大域模式 | 100 | 是 | | 最大绕过域模式 | 100 | 是 | | 服务器主机名长度 | 253 个字符 | 否 | | 域模式长度 | 253 个字符 | 否 | | 端口范围 | 1—65535 | 否 | 要申请增加可调整的约束条件，请联系 Amazon 支持部门。 ## 限制 在配置浏览器代理之前，请查看以下限制以确保该功能符合您的要求： | 限制 | 说明 | | --- | --- | | 交通路线 | 代理配置是在会话启动时应用的浏览器级别设置。它不是网络级别的控制，不能保证所有流量都会通过代理。要执行网络层，请使用[为 VPC 配置亚马逊 Bedrock AgentCore 运行时和工具。](agentcore-vpc.md) | | 受支持的协议 | 仅限 HTTP 和 HTTPS 代理。不支持 SOCKS4 和 SOCKS5 代理。 | | 身份验证 | HTTP 基本身份验证或不进行身份验证（IP 许可名单）。不支持 NTLM、Kerberos 和基于证书的身份验证。 | | 代理变更 | 代理配置在会话创建时设置一次。不支持在运行时更改配置。创建新会话以更改代理设置。 | | 代理轮换 | 不支持针对 IP 循环或负载分配的自动代理轮换。创建新会话来轮换代理。 | | 连接验证 | 创建会话时未验证代理连接。运行时出现连接错误。 |