足球API网关目标
适用于AWS Bedrock AgentCore网关的RapidAPI Football API集成。将足球数据访问部署到任何网关，作为MCP兼容目标。
概述
该项目将RapidAPI Football API部署为AWS Bedrock AgentCore Gateway的OpenAPI目标，使人工智能代理能够查询：
- 欧洲前5名联赛赛程、结果和排名
- 欧洲冠军联赛和欧洲联赛数据
- 球员统计数据（得分王、助攻数）
- 国内杯赛
主要特点
- ✨ 全自动部署：自定义资源自动配置网关服务角色权限
- 多网关支持：通过简单的环境配置部署到多个网关
- 内置联赛ID：在工具描述中预先配置的常见联盟，将API调用减少50%
- 共享凭据：一个RapidAPI密钥可用于多个网关部署
- CDK资产管理：OpenAPI模式自动上传到CDK暂存桶
- 安全凭据：存储在AWS Secrets Manager中的RapidAPI密钥
- 幂等：多次部署安全，智能权限合并
先决条件
- Node.js：>=18.x
- AWS-CLI：已配置凭据
- AWS CDK: >= 2.100.0
- 无效账户：主动订阅 足球API
- 现有网关：目标网关必须存在于您的AWS帐户中
创建AgentCore网关
如果您没有现有的网关，则需要先创建一个。网关是代理通过模型上下文协议（MCP）访问工具和资源的统一入口点。
快速启动选项
选择以下方法之一创建网关：
| 方法 | 最适合 | 命令示例 |
|---|---|---|
| AWS控制台 | 可视化界面，首次设置 | 带分步向导的Web UI |
| AWS-CLI | 简单自动化，IAM身份验证 | aws bedrock-agentcore-control create-gateway --name my-gateway --authorizer-type AWS_IAM ... |
| AgentCore工具包 | 自动OAuth设置 | agentcore create_mcp_gateway --region us-west-2 --name my-gateway |
AWS CLI示例（IAM授权-最简单）
aws bedrock-agentcore-control create-gateway \
--name my-gateway \
--role-arn arn:aws:iam::123456789012:role/MyAgentCoreServiceRole \
--protocol-type MCP \
--authorizer-type AWS_IAM \
--region us-west-2网关创建后
从输出中保存这些值：
gatewayIdentifier→ 在中使用.env文件为GATEWAY_IDENTIFIERgatewayUrl→ 用于连接客户端的MCP端点URLroleArn→ 网关服务角色ARN
重要说明
- 语义搜索：只能在网关创建期间启用（以后不能更改）
- IAM权限：此CDK堆栈通过自定义资源自动添加凭据提供程序权限
- 服务角色：您只需要基本的网关权限；凭证提供者访问权限是自动添加的
📚 完整的文件:
快速开始
1.安装依赖项
npm install2.配置环境
复制 .env.example 到特定于网关的env文件：
cp .env.example .env.my-gateway.local
# Edit and set:
# - GATEWAY_IDENTIFIER: Your gateway identifier
# - CREDENTIAL_PROVIDER_NAME: Your credential provider name3.一次性设置：创建凭据提供程序
步骤1：创建凭据提供程序
# Create credential provider (only once for shared strategy)
aws bedrock-agentcore-control create-api-key-credential-provider \
--name FootballAPICredentialProvider \
--description "RapidAPI Football API Key (shared)" \
--profile default --region 步骤2：存储您的RapidAPI密钥
从以下位置获取RapidAPI密钥：https://rapidapi.com/api-sports/api/api-football
然后使用您的API密钥更新凭据提供商：
# IMPORTANT: Use bedrock-agentcore-control to update the API key
# DO NOT use secretsmanager put-secret-value directly
aws bedrock-agentcore-control update-api-key-credential-provider \
--name FootballAPICredentialProvider \
--api-key "YOUR_RAPID_API_KEY" \
--profile default --region 为什么要使用更新api密钥凭据提供程序？
- 这个秘密由
bedrock-agentcore-identity服务 - Direct Secrets Manager操作可能会因服务所有权而失败
- 此命令可确保格式正确(
{"apiKey": "..."})自动 - 为无效密钥提供更好的错误消息
常见问题：
- ❌ 错误：
{"api_key": "..."}或{"api_key_value": "..."} - ✅ 对的：
{"apiKey": "..."}（由命令自动处理） - 如果API调用返回“错误/缺少应用程序密钥”，请验证密钥是否已成功更新
4.Bootstrap CDK（仅限首次使用）
cdk bootstrap --profile default5.部署到网关
./deploy.sh .env.my-gateway.local建筑
┌─────────────────────────────────────────────────────┐
│ AWS Bedrock AgentCore Gateway (pre-existing) │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ GatewayRoleUpdater (Custom Resource) │ │
│ │ ↓ Automatically adds IAM permissions │ │
│ │ ↓ to Gateway service role │ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ FootballAPITarget (OpenAPI Target) │ │
│ │ │ │
│ │ • OpenAPI Schema (CDK Asset → S3) │ │
│ │ • API Key (Secrets Manager) │ │
│ │ • Credential Provider: API_KEY │ │
│ │ • Headers: x-rapidapi-key, x-rapidapi-host│ │
│ └────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ Available Tools: │ │
│ │ • getFixtures │ │
│ │ • getStandings │ │
│ │ • getTopScorers │ │
│ │ • getTopAssists │ │
│ │ • getLeagues (fallback) │ │
│ └────────────────────────────────────────────┘ │
└──────────────────┬───────────────────────────────────┘
│ RapidAPI Key from Secrets Manager
▼
RapidAPI Football API v3
(https://v3.football.api-sports.io)部署流程
cdk deploy
↓
1. GatewayRoleUpdater (Custom Resource)
├── Lambda checks Gateway service role
├── Adds missing IAM permissions
└── ✅ Role updated automatically
↓
2. OpenAPI Schema Asset
└── Upload to S3
↓
3. Gateway Target
├── Reference Gateway
├── Reference Credential Provider
└── Link OpenAPI schema from S3
↓
✅ Target READY (fully automated)可用工具
1.装配夹具
获取比赛赛程、结果和时间表。
参数：
league（整数）：联赛ID（见下面的常用ID）season（整数，必填）：季节年份（例如2024/2025年为2024年）date（字符串）：匹配日期（YYYY-MM-DD）last（整数）：获取最后N个匹配项next（整数）：获取接下来的N场比赛status（字符串）：比赛状态（FT=全职，LIVE=进行中，NS=未开始）team（整数）：按团队ID筛选
示例：
// Premier League last 10 matches
{ league: 39, season: 2024, last: 10 }
// Champions League next 5 matches
{ league: 2, season: 2024, next: 5 }
// La Liga matches on specific date
{ league: 140, season: 2024, date: "2024-11-10" }
// Live matches across all leagues
{ season: 2024, status: "LIVE" }2.获得展位
获取联赛排名/表格。
参数：
league（整数，必填）：联赛IDseason（整数，必填）：季节年份team（整数）：特定团队ID
示例：
// Premier League standings
{ league: 39, season: 2024 }
// Serie A standings
{ league: 135, season: 2024 }3.获得高分
获得最高分。
参数：
league（整数，必填）：联赛IDseason（整数，必填）：季节年份
示例：
// Bundesliga top scorers
{ league: 78, season: 2024 }4.获取TopAssists
获得顶级助攻领袖。
参数：
league（整数，必填）：联赛IDseason（整数，必填）：季节年份
5.获取联赛
搜索联赛（仅用于不常见的联赛）。
参数：
id（整数）：特定联赛IDname（string）：按名称搜索country（string）：按国家筛选season（整数）：按季节筛选current（布尔值）：仅限活动联赛
普通联赛ID
欧洲五大联赛
- 英超联赛 （英国）：
39 - 西甲联赛 （西班牙）：
140 - 意甲联赛 （意大利）：
135 - 德甲 （德国）：
78 - 联赛 1 （法国）：
61
欧洲竞赛
- 欧洲冠军联赛:
2 - 欧洲足球联赛:
3
国内杯
- 足总杯 （英国）：
45 - 国王杯 （西班牙）：
143 - 意大利 杯 （意大利）：
137 - 德国杯 （德国）：
81 - 法国杯 （法国）：
66
优化策略
OpenAPI模式在工具描述中包含了常见的联盟ID，从而实现了：
- 直接使用：AI代理可以立即使用普通联赛的联赛ID
- 减少了API调用：无需查询
getLeagues用于流行比赛 - 更快的响应：消除了一个API往返行程（节省200-500ms）
- 配额节省：将API在典型查询中的使用量减少约50%
示例流程（优化）：
User: "Get Premier League standings"
→ Agent directly calls: getStandings({ league: 39, season: 2024 })
→ API calls: 1示例流程（未优化）：
User: "Get Premier League standings"
→ Agent calls: getLeagues({ name: "Premier League" })
→ Agent calls: getStandings({ league: 39, season: 2024 })
→ API calls: 2 ❌季节参数指南
API足球使用年份来表示赛季：
2024= 2024/2025赛季 （2024年8月至2025年5月）2023= 2023/2024赛季 （2023年8月至2024年5月）2022= 2022/2023赛季 （2022年8月至2023年5月）
例子： 对于2024年11月的比赛，请使用 season: 2024 （当前2024/2025赛季）。
快速使用示例
查看英超联赛排名
Tool: getStandings
Parameters: { "league": 39, "season": 2024 }获取今天的冠军联赛比赛
Tool: getFixtures
Parameters: { "league": 2, "season": 2024, "date": "2024-11-10" }比较前5名联赛的顶级得分者
# AI agent can call these in parallel:
getTopScorers({ "league": 39, "season": 2024 }) # Premier League
getTopScorers({ "league": 140, "season": 2024 }) # La Liga
getTopScorers({ "league": 135, "season": 2024 }) # Serie A
getTopScorers({ "league": 78, "season": 2024 }) # Bundesliga
getTopScorers({ "league": 61, "season": 2024 }) # Ligue 1常见错误
超出费率限制
{ "errors": { "requests": "The request limit has been reached" } }解决方案： 升级RapidAPI计划或等待配额重置。
联盟ID无效
{ "errors": { "league": "Invalid league id" } }解决方案： 使用 getLeagues 以搜索正确的联盟ID。
未返回数据
{ "results": 0, "response": [] }原因： 赛季不正确、联赛不活跃或日期超出范围。
RapidAPI速率限制
- 免费计划：100个请求/天
- 基础方案：500个请求/天（10美元/月）
- 专业计划：5 000次请求/天（35美元/月）
在RapidAPI仪表板中监控使用情况：https://rapidapi.com/developer/dashboard
项目结构
agentcore-gateway-targets/
├── schemas/
│ └── football-api-openapi.yaml # OpenAPI 3.0 schema with embedded league IDs
├── lib/
│ └── football-gateway-stack.ts # CDK Stack implementation
├── bin/
│ └── football-gateway-app.ts # CDK App entry point
├── deploy.sh # Deployment script for CDK stack
├── package.json # Node.js dependencies
├── tsconfig.json # TypeScript configuration
├── cdk.json # CDK configuration
├── .env.example # Environment template
├── .env.*.local # Gateway-specific configs (git-ignored)
├── CLAUDE.md # Project documentation (environment-agnostic)
├── CLAUDE.local.md # Environment-specific notes (git-ignored)
└── README.md # This file发展
构建
npm run build观看模式
npm run watchCDK命令
# List stacks
cdk list
# Show diff
cdk diff
# Synthesize CloudFormation
cdk synth
# Deploy
cdk deploy --profile default
# Destroy (remove target)
cdk destroy --profile default验证
部署后，验证目标：
# List all targets on your gateway
aws bedrock-agentcore-control list-gateway-targets \
--gateway-identifier \
--profile default --region
# Get specific target details
aws bedrock-agentcore-control get-gateway-target \
--gateway-identifier \
--target-id \
--profile default --region 故障排除
目标创建失败
- 检查网关是否存在：
aws bedrock-agentcore-control get-gateway --gateway-identifier - 验证凭据提供程序是否存在以及名称是否正确
- 检查CloudWatch日志是否有错误
- 验证OpenAPI模式语法
API调用失败
- 验证RapidAPI订阅是否处于活动状态
- 在机密管理器中检查API密钥
- 确保x-rapidapi-host头球匹配
- 查看速率限制状态
架构验证错误
- 确保所有操作
operationId - 避免一个/任何/所有构造
- 使用简单的参数结构
- 使用OpenAPI验证器进行验证：https://validator.swagger.io/
成本考虑
AWS成本
- AgentCore网关：按工具调用付费
- 拉姆达 （GatewayRoleUpdater）：每次部署约0.01美元（适用于免费层）
- CloudWatch日志：可忽略不计（保留7天）
- 秘密经理：每个秘密约0.40美元/月
- S3存储：可忽略不计（架构文件\<1KB）
- 云层形成：免费
RapidAPI成本
- 自由：100个请求/天
- 基础：10美元/月（500次请求/天）
- 专业版每月35美元（每天5000次请求）
参考文献
许可证
请参阅存储库根目录中的LICENSE文件。